よくある質問

よく寄せられる質問への簡潔な回答です。「何かが動かない」という問題については、トラブルシューティングを参照してください。用語の意味を知りたい場合は、用語集を確認してください。

基本

OpenSpec を一言で言うと何ですか？

コードを書く前に、何を作るのかをあなたと AI コーディングアシスタントが文書で合意するための軽量なレイヤーです。

なぜそれが必要なのですか？

AI アシスタントは間違っていても自信満々に答えるからです。要件がチャット内にしかないと、AI は不足部分を推測で補い、コードができてから誤りに気付きます。OpenSpec は合意のタイミングを早めるため、誤りを低コストで修正できます。詳しくはコア概念の概要を参照してください。

すべての作業に使う必要がありますか？

いいえ。合意が重要な作業（ほとんどの些細ではない作業）で使ってください。1文字のタイプミス修正では手順に見合う効果がないかもしれません。それで問題ありません。

大規模な既存コードベースでも使えますか？新規プロジェクト専用ですか？

既存コードベースでの利用こそが主な用途です。OpenSpec は既存システムを重視しているため、最初にアプリ全体を文書化する必要はありません。各 change が対象とする部分だけを仕様化し、実際の作業を通じて徐々に仕様を増やします。専用ガイドの既存プロジェクトで OpenSpec を使うを参照してください。

特定の AI ツール専用ですか？

いいえ。OpenSpec は Claude Code、Cursor、Devin Desktop、GitHub Copilot、Gemini CLI、Codex など、30以上のアシスタントに対応しています。全一覧とツールごとの詳細は対応ツールにあります。

コマンドの実行

/opsx:propose はどこに入力しますか？

ターミナルではなく、AI アシスタントとのチャットです。最もよくある混乱なので、専用ページのコマンドの実行方法があります。簡単に言うと、openspec ... はターミナルで、/opsx:... はチャットで実行します。

「対話モード」を開始するには？

別のモードを開始する必要はありません。通常どおり AI アシスタントを開いて、チャットにスラッシュコマンドを入力します。スラッシュコマンドが OpenSpec を「開始」する方法です。（本当に対話型のターミナル機能は、仕様や change を閲覧するダッシュボード openspec view です。）詳しくはコマンドの実行方法を参照してください。

スラッシュコマンドを入力しても何も起きません。なぜですか？

AI とのチャットではなくターミナルに入力した、ツールが認識しない表記を使った、またはコマンドがまだインストールされていない可能性が高いです。ファイルがない場合、またはツールをまだ設定していない場合は openspec init を実行してください。openspec update は既存ファイルの更新のみ行います。その後アシスタントを再起動し、「はじめに」に表示される形式を使います。呼び出し方法を参照してください。詳細なチェックリストはトラブルシューティングにあります。

ツールによって /opsx:propose と /opsx-propose のように構文が異なるのはなぜですか？

AI ツールごとにカスタムコマンドの表示方法が異なるため、OpenSpec はツールが読み込むファイルに合わせて表記します。opsx-propose.md というコマンドファイルは /opsx-propose と入力し、commands/opsx/ 以下に置かれたものは /opsx:propose と入力します。コマンドではなくスキルを使うツールでは、スキル名を使います。Codex では $openspec-propose、Kimi Code では /skill:openspec-propose です。openspec init の「はじめに」には、選んだツールに適した形式が表示されます。完全な一覧は呼び出し方法にあります。

スキルとコマンドの違いは何ですか？

どちらも、アシスタントがワークフローを実行できるよう OpenSpec が作成するファイルです。スキル（.../skills/openspec-*/SKILL.md）は新しいツール横断型の標準で、コマンド（.../commands/opsx-*）は従来のツール固有スラッシュファイルです。どちらを使うか選ぶ必要はありません。スラッシュコマンドを入力すれば、OpenSpec がツールに応じた形式をインストールします。

ワークフロー

何を作るか決まっていない場合、どこから始めればよいですか？

/opsx:explore から始めてください。コードを書く前にコードベースを読み、選択肢を整理し、曖昧な問題を具体的な計画にする、リスクのない思考パートナーです。既定のプロファイルに含まれるため、いつでも使えます。計画が明確になったら /opsx:propose に引き継ぎます。AI が自信満々に間違ったものを作るのを防ぐ、最も有効な習慣です。まず Exploreを参照してください。

最も簡単なワークフローは何ですか？

/opsx:explore (任意)       次に   /opsx:propose <実現したいこと>   次に   /opsx:apply   次に   /opsx:archive

explore で考えを整理し、propose で計画を下書きし、apply で実装し、archive で保管します。実現したいことが明確な場合は explore を省略してください。

/opsx:propose と /opsx:new はどう違いますか？

/opsx:propose は既定の一段階コマンドです。change を作成し、すべての計画成果物を一度に下書きします。/opsx:new は拡張コマンドセットの一部で、空の change のひな型だけを作成します。その後 /opsx:continue で成果物を1つずつ作成するか、/opsx:ff ですべてまとめて作成します。段階的に制御したい場合を除き、propose を使ってください。コマンドを参照してください。

core と expanded プロファイルとは何ですか？

プロファイルでは、どのスラッシュコマンドをインストールするかを決めます。既定の Core では propose、explore、apply、update、sync、archive が使えます。expanded セットでは、より細かく制御できるよう new、continue、ff、verify、bulk-archive、onboard が追加されます。openspec config profile で切り替え、openspec update で適用します。

/opsx:sync を実行する必要がありますか？

通常は必要ありません。sync は change の差分仕様をメイン仕様にマージし、/opsx:archive が代わりに実行するか確認します。長期間続く change など、アーカイブ前に仕様をマージしたい場合に限り、sync を手動で実行してください。コマンドを参照してください。

開始後に提案、仕様、タスクを編集するには？

ファイルを編集するだけです。すべての成果物は openspec/changes/<name>/ 内の通常の Markdown であり、固定されたフェーズや特別な編集モードはありません。手動で変更するか、AI に「キューを使うよう設計を更新して」と依頼してから、作業を続けてください。AI は常に現在のファイル内容に基づいて作業します。詳しくは変更の編集と反復を参照してください。

一部を実装した後でも、計画を変更できますか？

はい、いつでも可能です。ワークフローは柔軟なので、レビューや編集ができなくなるフェーズはありません。成果物を編集して続けてください。コードが引き続き計画に一致しているか体系的に確認するには /opsx:verify を実行します。変更の編集と反復を参照してください。

コードを手動で編集しました。仕様と整合させるには？

アーカイブすると仕様が公式な記録になるため、アーカイブ前にコードと仕様を同期してください。コードが正しい場合は、実装した内容に合わせて差分仕様を更新します。仕様が正しい場合は、コードが一致するまで実装を続けます。/opsx:verify で不一致を見つけられます。変更の編集と反復を参照してください。

既存の change を更新するのと、新しいものを始めるのはどちらがよいですか？

同じ作業を洗練させる場合は更新します。目的が根本的に変わったり、範囲が別の作業にまで広がったりした場合は新しく始めます。ワークフローに判断フローチャートと例があります。

セッションのコンテキストが尽きた場合や、実装途中に要件が変わった場合はどうなりますか？

ここで仕様が役立ちます。計画はチャット履歴だけではなくファイルに保存されているので、コンテキストをクリアし、新しい AI セッションを開始して /opsx:apply を再開できます。成果物が読み込まれ、最初の未完了タスクから再開します。要件が変わった場合は、実情に合わせて成果物を編集して続けてください。コンテキストウィンドウを整理しておくと結果も良くなるため、実装前にクリアしてください。

openspec/ フォルダーを git にコミットする必要がありますか？

はい。仕様、作業中の change、アーカイブはプロジェクトの履歴の一部です。他のソースと同じようにコミットしてください。特にアーカイブは、システムがそのように動作する理由を長期にわたって記録します。

仕様と change

仕様と設計にはそれぞれ何を記述しますか？

仕様には観測可能な動作（システムが行うこと、入力、出力、エラー条件）を記述します。設計には実装方法（技術的なアプローチ、アーキテクチャ上の判断、ファイルの変更）を記述します。外部から見える動作を変えずに実装を変更できるなら、それは仕様ではなく設計に記述します。詳しくは概念を参照してください。

差分仕様とは何ですか？

仕様全体を書き直すのではなく、ADDED、MODIFIED、REMOVED の節を使って変更点だけを記述する仕様です。OpenSpec が既存システムの変更を整理して扱う方法です。概念を参照してください。

アーカイブされた change はどこに移動しますか？

すべての成果物を保持したまま、openspec/changes/archive/YYYY-MM-DD-<name>/ に移動します。change は作業中の一覧から外れます。retire_capabilities: true を明示した change で機能の最後の要件を削除すると、メインの機能仕様も削除できます。

設定とカスタマイズ

技術スタックを AI に伝えるには？

openspec/config.yaml の context: に記述します。その内容は計画に関するすべての依頼に追加されるため、AI が常に技術スタックと規約を把握できます。カスタマイズを参照してください。

英語以外の言語で仕様を生成できますか？

はい。設定の context: に言語の指示を追加してください。多言語ガイドには、複数の言語の例があります。

ワークフロー自体を変更できますか？

はい。カスタムスキーマを使います。スキーマでは成果物とその依存関係を定義します。openspec schema fork spec-driven my-workflow で既定のスキーマをフォークして編集してください。カスタマイズを参照してください。

モデル、プライバシー、アップグレード

どの AI モデルを使えばよいですか？

OpenSpec は推論能力の高いモデルで最もよく機能します。README では計画と実装の両方に Codex 5.5 や Opus 4.7 などのモデルを推奨しています。また、より良い結果を得るため、実装前にコンテキストウィンドウをクリアして整理してください。

OpenSpec はデータを収集しますか？

匿名の利用統計（コマンド名とバージョンのみ）を収集します。引数、パス、コンテンツ、個人情報は収集せず、CI では自動的に無効になります。export OPENSPEC_TELEMETRY=0 または export DO_NOT_TRACK=1 でオプトアウトできます。

アップグレードするには？

2つの手順があります。パッケージをアップグレードし（npm install -g @fission-ai/openspec@latest）、各プロジェクト内で openspec update を実行して、生成済みのスキルとコマンドを更新します。

OpenSpec をアンインストールするには？

OpenSpec はグローバルパッケージとプロジェクト内のファイルだけで構成されるため、アンインストールコマンドはありません。パッケージ（npm uninstall -g @fission-ai/openspec）を削除し、必要に応じて openspec/ ディレクトリと生成されたツールファイルも削除してください。安全に残せるものを含む詳しい手順は、インストール: アンインストールにあります。

サポートを受ける

質問やバグの報告はどこでできますか？

• Discord: discord.gg/YctCnvvshC
• GitHub の Issue: github.com/Fission-AI/OpenSpec/issues
• ターミナルから: openspec feedback "your message" で GitHub Issue を作成できます。

ドキュメントが間違っている、または分かりにくい場合はどうすればよいですか？

お知らせいただくか、直接修正してください。ドキュメントの PR は歓迎され、重視されています。Issue を作成するか、プルリクエストを送ってください。