OpenSpec

FAQ ​

よくある質問への迅速な回答。もしあなたの質問が「何かが壊れている」という種類のものなら、トラブルシューティング のページの方が適しています。用語の定義を知りたい場合は、用語集 を参照してください。

基本事項 ​

OpenSpec とは一言で何ですか？ ​

コードが書かれる前に、あなたと AI コーディングアシスタントが何を構築するかについて合意形成を行うための軽量なレイヤーです。

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

AI アシスタントは間違っているときでも自信を持っていることが多いからです。要件がチャットスレッドの中だけに存在する場合、AI は隙間を推測で埋め、コードが存在してから問題に気づくことになります。OpenSpec は、修正コストが低い段階で合意形成を早期に行います。詳細な理由は コアコンセプト一覧 をご覧ください。

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

いいえ。合意形成が重要な場面で使用します。それは、大抵の場合、非自明な作業においてです。1文字のタイプミス修正のような単純な作業では、手続き的なオーバーヘッドに見合わないため、使用しないのも問題ありません。

既存の大規模なコードベースで使用できますか？ それとも新規プロジェクトのみですか？ ​

既存のコードベースが主な対象です。OpenSpec はブラウンフィールド（既存環境）ファーストです：最初からアプリ全体を文書化する必要はありません。各変更が影響を与える部分に対してのみ仕様を書き、実際の作業に合わせて仕様が徐々に充実していきます。専用のガイドがあります：既存プロジェクトでの OpenSpec の使用。

特定の AI ツールに縛られますか？ ​

いいえ。OpenSpec は Claude Code、Cursor、Devin Desktop、GitHub Copilot、Gemini CLI、Codex など、30以上のアシスタントと連携します。完全なリストとツール別の詳細は サポートされているツール に記載されています。

コマンドの実行 ​

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

ターミナルではなく、AI アシスタントのチャットウィンドウに入力します。これは最も一般的な混乱の原因となるポイントであるため、専用のページを用意しています：コマンドの動作方法。簡易版：openspec ... はターミナルで実行し、/opsx:... はチャットで実行します。

「インタラクティブモード」を開始するにはどうすればよいですか？ ​

別途開始するモードはありません。通常通り AI アシスタントを開き、そのチャットにスラッシュコマンドを入力します。スラッシュコマンドを入力することで OpenSpec に「入り」ます。（ターミナル上で真にインタラクティブな機能は 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 が自信を持って間違ったものを構築するのを防ぎます。詳しくは まず探索する を参照してください。

最もシンプルなフローは何ですか？ ​

text
/opsx:explore (オプション)   →   /opsx:propose <やりたいこと>   →   /opsx:apply   →   /opsx:archive

検討するために explore を使い、計画をドラフトするために propose を使い、構築するために apply を使い、記録するために archive を使います。やりたいことが明確な場合は explore をスキップしてください。

/opsx:propose と /opsx:new の違いは何ですか？ ​

/opsx:propose はデフォルトのワンステップコマンドで、変更を作成し、すべての計画アーティファクトを一度にドラフトします。/opsx:new は拡張コマンドセットの一部であり、空の変更のスケルトンだけを作成し、/opsx:continue（または /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 は変更のデルタ仕様をメインの仕様にマージしますが、/opsx:archive がそれを代行してくれるよう提案します。長期にわたる変更など、アーカイブする前に仕様をマージしたい場合にのみ手動で sync を実行してください。詳しくは コマンド を参照してください。

提案、仕様、またはタスクの編集はどのように行いますか？ ​

ファイルを直接編集してください。すべてのアーティファクトは openspec/changes/<name>/ 内のプレーンな Markdown であり、ロックされたフェーズや特別な編集モードはありません。手動で変更するか、AI に修正を依頼（「キューを使うようにデザインを更新」など）してから続行してください。AI は常に現在のファイル内容に基づいて動作します。完全なガイド：変更の編集と反復。

実装の一部を行った後で計画を変更することはできますか？ ​

はい、いつでも可能です。ワークフローは流動的であるため、レビューや編集はロックアウトされるフェーズではありません。アーティファクトを編集し、続行してください。コードが依然として計画と一致しているかどうかを構造化されたチェックで行いたい場合は、/opsx:verify を実行してください。詳しくは 変更の編集と反復 を参照してください。

コードを手動で編集しました。これを仕様とどのように整合させますか？ ​

アーカイブする前に同期させてください。アーカイブすると、仕様が生きた記録となるためです。コードが現在正しい場合は、出荷済みの内容に合わせてデルタ仕様を更新します。仕様の方が正しい場合は、コードがそれに一致するまで構築を続けます。/opsx:verify は不一致を浮き彫りにします。詳しくは 変更の編集と反復 を参照してください。

既存の変更を更新すべきか、それとも新規に変更を開始すべきかはいつ判断すればよいですか？ ​

同じ作業の洗練であれば更新し、意図が根本的に変わった場合や範囲が異なる作業に膨れ上がった場合は新規に開始します。意思決定のフローチャートと例は ワークフロー にあります。

コンテキストが溢れた場合、または実装中に要件が変わった場合はどうすればよいですか？ ​

ここで仕様が出番となります。計画がチャット履歴だけでなくファイルにも保存されているため、コンテキストをクリアして新しい AI セッションを開始し、/opsx:apply で再開できます。アーティファクトを読み取り、未チェックの最初のタスクから再開します。要件が変わった場合は、アーティファクトを新しい状況に合わせて編集し、続行してください。クリーンなコンテキストウィンドウを維持することも、より良い結果を生みます。実装前にクリアしてください。

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

はい。仕様、アクティブな変更、アーカイブはプロジェクトの履歴の一部です。他のソースコードと同様にコミットしてください。特にアーカイブは、システムがなぜそのように動作しているのかという永続的な記録となります。

仕様と変更 ​

仕様と設計、それぞれに何が記載されますか？ ​

仕様は観測可能な挙動を記述します：システムが行うこと、入出力、エラー条件などです。設計はどのように構築するかを記述します：技術的アプローチ、アーキテクチャの意思決定、ファイル変更などです。実装方法が変わっても外部から見える挙動が変わらない場合、それは設計に記載され、仕様には記載されません。詳しくは コンセプト を参照してください。

デルタ仕様とは何ですか？ ​

全体の仕様を再述するのではなく、ADDED、MODIFIED、REMOVED セクションを使用して、変更される部分のみを記述した仕様です。これが OpenSpec が既存システムへの変更をきれいに処理する方法です。詳しくは コンセプト を参照してください。

アーカイブされた変更はどこに保存されますか？ ​

openspec/changes/archive/YYYY-MM-DD-<name>/ に保存され、すべての変更アーティファクトが保持されます。変更はアクティブなリストから移動します。retire_capabilities: true を明示的に宣言している変更は、最終要件を削除する際にメインの機能仕様も削除できます。

設定とカスタマイズ ​

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 を実行して、生成されたスキルとコマンドを更新します。

アンインストールするにはどうすればよいですか？ ​

アンインストールコマンドはありません。これはグローバルパッケージとプロジェクト内のファイルの組み合わせだからです。パッケージを削除し（npm uninstall -g @fission-ai/openspec）、必要に応じて openspec/ ディレクトリと生成されたツールファイルを削除してください。安全に保持できるものを含む手順については インストール：アンインストール を参照してください。

ヘルプの取得 ​

質問をしたりバグを報告したりするにはどこに行けばよいですか？ ​

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

私たちに連絡するか、修正してください。ドキュメントに関する PR は歓迎され、高く評価されています。Issue を開くか、プルリクエストを送信してください。