トラブルシューティング

具体的な問題に対する具体的な解決策。各項目は症状、考えられる原因（1文）、および解決策を示します。ここであなたの問題が見つからない場合は、FAQ が役立つかもしれませんし、Discord であれば確実に解決できます。

インストールとセットアップ

openspec: command not found

CLI がインストールされていないか、シェルが見つけられていません。グローバルにインストールして確認してください：

npm install -g @fission-ai/openspec@latest
openspec --version

インストールされたにもかかわらずまだ見つからない場合、グローバルな npm の bin ディレクトリが PATH に含まれていない可能性があります。npm prefix -g を実行して、グローバルパッケージの場所を確認してください：macOS および Linux ではバイナリはそのディレクトリの bin/ にあり、Windows ではそのディレクトリ内に直接配置されています。そのパスが PATH に含まれていることを確認してください。（npm 9 で npm bin -g は削除されました。）

AI支援によるインストールを使用した場合、これが期待される引き継ぎポイントです：このプロンプトは、アシスタントにシェルの起動ファイルを直接編集するのではなく、PATH の変更を表示するように指示します。

"Requires Node.js 20.19.0 or higher"

OpenSpec は Node 20.19.0 以上で動作します。バージョンを確認し、必要に応じてアップグレードしてください：

node --version

bun を使用して OpenSpec をインストールする場合、OpenSpec は Node 上で実行 するため、PATH 上に Node 20.19.0 以上が利用可能である必要があります。Installation を参照してください。

openspec init で AI ツールが設定されなかった

init はどのツールを設定するかを尋ねます。ツールをスキップした場合や、別のツールを追加したい場合は、もう一度実行するか、非インタラクティブ形式を使用してください：

openspec init --tools claude,cursor

ツールの ID の全リストは Supported Tools にあります。すべてに対しては --tools all を、ツール設定をスキップするには --tools none を使用します。

コマンドが表示されない

/opsx:propose（またはお使いのツールの同等コマンド）が表示されない、または何もしない場合は、以下のリストを下ってください。チェックしやすい順に並んでいます。

1. 間違った場所にいる可能性があります。 スラッシュコマンドはターミナルではなく、AI アシスタントのチャットで使用します。シェルに /opsx:propose と入力したのが問題です。How Commands Work を参照してください。

2. ファイルを再生成する。 プロジェクトルートから：

   openspec update

   これにより、設定済みのすべてのツールに対してスキルファイルとコマンドファイルが書き換えられます。

   指示ファイルは インストール済み の CLI から取得されるため、古い CLI は新しいワークフローを書き出すことなく、すべてが最新であると報告します。openspec update はこれをチェックし、アップグレードを提案します — 表示された場合はそれを受けてください。

3. アシスタントを再起動する。 ほとんどのツールは起動時にスキルとコマンドをスキャンします。新しいウィンドウを開くだけで済むことが多いです。

4. ファイルが存在することを確認する。 Claude Code の場合、.claude/skills/ に openspec-* フォルダが含まれているか確認してください。他のツールは独自のディレクトリを使用しており、それらはすべて Supported Tools にリストされています。

5. このプロジェクトを初期化したか確認する。 スキルはプロジェクトごとに記述されます。リポジトリをクローンした、またはフォルダを切り替えた場合は、そこで openspec init（または openspec update）を実行してください。

6. お使いのツールがコマンドファイルをサポートしているか確認する。 Codex、CodeArts、ForgeCode、Hermes、Kimi Code、Mistral Vibe、Zed Agent、および共有 .agents ターゲットには opsx-* コマンドファイルが生成されず、代わりにスキルベースの呼び出しを使用するため、これらでは /opsx のオートコンプリートは決して行われません。Codex では $openspec-propose、Kimi Code では /skill:openspec-propose、その他では /openspec-propose と入力してください。共有 .agents ターゲットはベンダーニュートラルであるため、/openspec-propose は保証された形式ではなく共通の形式です — アシスタントがそれに反応しない場合は、スキルを呼び出す方法を自身のドキュメントで確認してください。Amazon Q はコマンドファイルを取得しますが、スラッシュメニューではなくプロンプトライブラリに読み込まれるため、そこでは /opsx ではなく @opsx-propose と入力してください。各ツールの形式は How To Invoke にリストされています。

変更の取り扱い

"Change not found"

コマンドがどの変更を指しているのか判断できませんでした。明示的に名前を指定するか、存在するものを確認してください：

openspec list                    # アクティブな変更を見る
/opsx:apply add-dark-mode        # チャットで変更名を指定

また、正しいプロジェクトディレクトリにいることも確認してください。

"No artifacts ready"

各アーティファクトはすでに作成されているか、依存関係の待ち状態にあります。何がブロックしているかを確認してください：

openspec status --change <name>

その後、不足している依存関係を先に作成してください。順序を覚えておいてください：proposal が specs と design を有効にし、specs と design が一緒に tasks を有効にします。

openspec validate が警告またはエラーを報告する

検証は、構造上の問題について specs と changes をチェックします。メッセージを読んでください：ファイル名と問題点が明記されています。

openspec validate <name>           # 1つのアイテムを検証
openspec validate --all            # すべてを検証
openspec validate --all --strict   # より厳格なチェック（CIに適す）
openspec validate --archived       # アーカイブ済み変更の未チェックタスクがある場合に失敗

一般的な原因として、必須セクションの欠如（例：シナリオのない spec）またはフォーマット不正の delta ヘッダーがあります。ファイルを修正して再実行してください。出力形式については CLI reference で文書化されています。

1つのメッセージには独自の注釈が必要です：

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

MODIFIED 要件は全体の要件ブロックを置き換えるため、変更で生き残るすべてのシナリオを保持する必要があり、編集したものだけでなくなければなりません。openspec/specs/<capability-path>/spec.md から指定されたシナリオをコピーし、パス内のドメインディレクトリを維持したまま delta に戻してください。これは通常、他の誰かの変更が同じ要件にシナリオを追加した後、古い変更で発生します — archive はどちらの場合でもその変更を拒否し、実装する前に検証がそれを通知します。

AI が不完全または誤ったアーティファクトを作成した

AI に十分なコンテキストがありませんでした。いくつかの調整方法があります：

• openspec/config.yaml でプロジェクトコンテキストを追加し、スタックと規約をすべてのリクエストに注入させます。Customization を参照してください。
• 特定のアーティファクト（例えば specs など）のみに関連するガイダンスのために、アーティファクトごとの rules: を追加します。
• 提案する際に、より詳細な説明を提供します。
• /opsx:ff ですべてを一度に行うのではなく、/opsx:continue を使用してアーティファクトを1つずつ作成し、それぞれレビューします。

Archive が完了しない、または不完全なタスクについて警告する

Archive は不完全なタスクで ブロック しませんが、作業が完了したことを意味するため警告します。意図的にタスクが残っている場合（部分的な変更を提出するなど）、続行してください。そうでない場合は、まずタスクを完了させてください。Archive は、まだ同期していない場合、delta specs をメイン specs に同期するかどうかを提案します — 理由がない限りはいと答えてください。

"User force closed the prompt with 0 null"

質問に答えられない場所で openspec archive が実行されました — ツールから呼び出される AI エージェント、CI ジョブ、または stdin が閉じた任意のシェルなど。Archive は最大3回の確認を求め、答えられない確認は以前はその生メッセージで失敗していました。

upfront で回答するために --yes を渡してください：

openspec archive <change-name> --yes

既に渡していたフラグはそのまま保持してください — --skip-specs や --no-validate は archive の動作を変更するため、単なる --yes の再実行は同じコマンドではありません。現在のバージョンはフラグ名を提示し、貼り付け可能な Fix: ラインを出力します。リストから選択しようとした場合は、変更名を明示的に渡してください — ピッカーにも回答が必要です。

代わりに、archive を実行してその出力をファイルにリダイレクトしたりツールでキャプチャしたりし、かつ実際に回答をパイプした場合（printf 'y\n' | openspec archive …）、古いバージョンはプロンプトを描画しながらそのキャプチャにターミナルのエスケープコードを書き込みました — 一部の環境ではファイルサイズが大幅に膨張するほどでした。現在のバージョンは stdout がターミナルでない場合、確認プロンプトをプレーンテキストとして読み取り、引数なしの openspec archive（本来対話型の変更ピッカーを描画するはずのもの）は、キャプチャにメニューを描画するのではなく、 upfront で変更名を渡すよう求めます。いずれにせよ、リダイレクトおよびエージェントの実行はクリーンに保たれます；--yes（変更名付き）を渡すと、プロンプトを完全にスキップします。

設定

config.yaml が適用されない

3つの主な疑わしい点があります：

1. ファイル名が間違っている。 openspec/config.yaml であり、.yml であってはなりません。
2. YAML が無効。 任意の YAML バリデーターに通してください；CLI も行数付きで構文エラーを報告します。
3. 再起動を期待していた。 再起動は不要です。設定変更は即座に反映されます。

"Unknown artifact ID in rules: X"

rules: 下のキーがスキーマ内のどのアーティファクトとも一致しません。デフォルトの spec-driven スキーマの場合、有効な ID は proposal、specs、design、tasks です。任意のスキーマの ID を確認するには：

openspec schemas --json

"Context too large"

context: フィールドは、すべてのリクエストに注入されるため、意図的に 50KB に制限されています。要約するか、貼り付けるのではなく長いドキュメントへのリンクを使用してください。軽量なコンテキストは、より良く、高速な結果を生み出します。

"Schema not found"

参照したスキーマ名が存在しません。利用可能なものをリストし、スペルを確認してください：

openspec schemas                    # 利用可能なスキーマをリスト
openspec schema which <name>        # スキーマがどこから解決されるかを確認
openspec schema init <name>         # カスタムスキーマを作成

Customization を参照してください。

レガシーワークフローからの移行

"Legacy files detected in non-interactive mode"

CI または非インタラクティブシェルにいて、OpenSpec がクリーンアップすべき古いファイルを見つけましたが、プロンプトできません。自動的に承認してください：

openspec init --force

Codex の場合、OpenSpec は $CODEX_HOME/prompts または ~/.codex/prompts 内の古い管理対象プロンプトファイルを検出する可能性があります。そのクリーンアップは OpenSpec の許可リストにあるレガシー Codex プロンプトファイル名に限定されており、非インタラクティブな openspec init は、置換用の .agents/skills/openspec-* スキルが存在するファイルのみを削除します。非インタラクティブな openspec update は、--force を渡さない限り、すべてのレガシークリーンアップ untouched にします。

移行後もコマンドが表示されない

IDE を再起動してください。スキルは起動時に検出されます。それでも表示されない場合は、openspec update を実行し、Supported Tools のファイル場所を確認してください。

古い project.md が移行されなかった

これは意図的です。OpenSpec は、あなたが書いたコンテキストを含んでいる可能性があるため、project.md を自動的に削除しません。有用な部分を config.yaml の context: セクションに移動し、自分で削除してください。Migration Guide はこれを段階的に解説しており、AI に抽出を依頼するためのプロンプトも含まれています。

まだ詰まっている？

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• ターミナルから： openspec feedback "what went wrong" はあなたのために issue を開きます。

問題を報告する際は、OpenSpec のバージョン（openspec --version）、Node のバージョン（node --version）、AI ツール、および正確なコマンドと出力を含めてください。そうすると、サポートがずっと速くなります。