FAQ

よくある質問へのクイックアンサー。もしあなたの質問が「何かが壊れている」という問題であれば、トラブルシューティング のページを参照してください。用語を定義したい場合は、用語集 をご覧ください。

基本事項

OpenSpecとは何ですか？（一言で）

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

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

なぜなら、AIアシスタントは間違っている場合でも自信を持っているからです。要件がチャットスレッドにのみ存在する場合、AIは推測でギャップを埋め、コードが存在した後に問題が発覚します。OpenSpecは合意形成をより早い段階に移動させ、間違いを安く修正できるようにします。完全な背景については、概要（Core Concepts at a Glance） を参照してください。

すべてのプロジェクトでそれを使う必要がありますか？

いいえ。合意が重要となる部分、つまりほとんどすべての非自明な作業で使用してください。1文字のタイプミスを修正する場合、その儀式は価値がない可能性があり、それは問題ありません。

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

既存のコードベースこそがメインの対象です。OpenSpecはブラウンフィールド（既存システム）ファーストであり、アプリケーション全体を事前に文書化する必要はありません。変更によって影響を受ける部分についてのみ仕様書を作成し、実際に作業を進めるにつれて仕様書を補完していきます。専用ガイドがあります：既存プロジェクトでのOpenSpecの使用。

特定のAIツールに紐づいていますか？

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

コマンドの実行

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

ターミナルではなく、AIアシスタントのチャットに入力します。これが最も一般的な混乱点であるため、専用のページがあります：コマンドの仕組み。簡単な説明は次のとおりです：openspec ... はターミナルで実行し、/opsx:... はチャットで実行します。

「インタラクティブモード」をどのように「開始」しますか？

別途起動するモードはありません。通常通りAIアシスタントを開き、そのチャットにスラッシュコマンドを入力します。このスラッシュコマンドがOpenSpecに「入る」方法です。（真にインタラクティブなターミナル機能は openspec view であり、これは仕様と変更を閲覧するためのダッシュボードです。）完全な説明は コマンドの仕組み を参照してください。

スラッシュコマンドを入力したのに何も起こりませんでした。なぜですか？

おそらくターミナルで入力したか、まだコマンドがインストールされていないかのどちらかです。プロジェクト内で openspec update を実行し、アシスタントを再起動してから、チャットに /opsx と入力してオートコンプリートが表示されるか確認してください。トラブルシューティング に完全なチェックリストがあります。

なぜあるツールでは構文が /opsx:propose であり、別のツールでは /opsx-propose なのですか？

各AIツールはカスタムコマンドをわずかに異なる方法で表示します。意図は同一であり、句読点だけが異なります。チャットにスラッシュを入力すると、使用しているツールが必要とする形式が表示されます。各ツールに関する表は コマンドの仕組み にあります。

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

どちらもOpenSpecがアシスタントを実行できるように書き出すファイルです。スキル（.../skills/openspec-*/SKILL.md）は新しいクロスツール標準であり、コマンド（.../commands/opsx-*）は古いパー・ツールスラッシュファイルです。どちらかを選ぶ必要はありません。スラッシュコマンドを入力するだけで、OpenSpecが使用しているものをインストールします。

ワークフロー

何を構築すべきかわからない場合、どこから始めればよいですか？

/opsx:explore からです。これは思考のパートナーであり、コードベースを読み込み、選択肢を提示し、変更やコードが存在する前に曖昧な問題を具体的な計画に落とし込みます。デフォルトプロファイルに含まれているため、常に利用可能です。計画が明確になったら、/opsx:propose に引き継ぎます。これは最も重要な習慣であり、熱心なAIが間違ったものを自信を持って構築することを防ぎます。まず探索（Explore First） をご覧ください。

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

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

まず探索して考え、提案で計画をドラフトし、適用で構築し、アーカイブでファイルを保管します。何をしたいか正確に分かっている場合は、探索はスキップしてください。

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

/opsx:propose はデフォルトのワンステップコマンドであり、変更を作成し、すべての計画アーティファクトを一度にドラフトします。/opsx:new は拡張されたコマンドセットの一部であり、空の変更のみをスキャフォールドし、/opsx:continue で一つずつ（または /opsx:ff ですべてまとめて）アーティファクトを作成するように促します。段階的な制御が必要ない限り、proposeを使用してください。コマンド をご覧ください。

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

プロファイルはどのスラッシュコマンドをインストールするかを決定します。Core（デフォルト）には propose、explore、apply、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 にコミットすべきですか？

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

仕様と変更

仕様（spec）とデザイン（design）には何を入れるべきですか？

仕様は観察可能な振る舞いを記述します：システムが何をするか、入力、出力、エラー条件など。デザインはそれをどのように構築するかを記述します：技術的アプローチ、アーキテクチャ上の決定、ファイル変更など。実装が外部に見える振る舞いを変更せずに変化できる場合、それは仕様ではなくデザインに属します。概念（Concepts） でより深く掘り下げます。

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

全体的な仕様を再記述するのではなく、ADDED、MODIFIED、REMOVED セクションを使用して変更点のみを記述する仕様です。これはOpenSpecが既存のシステムへの編集をクリーンに処理する方法です。概念（Concepts） をご覧ください。

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

すべてのアーティファクトを保持したまま、openspec/changes/archive/YYYY-MM-DD-<name>/ に保存されます。何も削除されません。その変更がアクティブリストから移動するだけです。

設定とカスタマイズ

AIに対して自分の技術スタックを伝えるにはどうすればよいですか？

openspec/config.yaml の context: 以下に記述してください。このテキストはすべての計画リクエストに注入されるため、AIは常にあなたのスタックと慣習を知っています。カスタマイズ をご覧ください。

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

はい。設定の context: に言語指示を追加してください。多言語（Multi-Language） にいくつかの言語のコピー＆ペースト可能なスニペットがあります。

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

カスタムスキーマを使用することで可能です。スキーマはどのアーティファクトが存在し、それらが互いにどのように依存するかを定義します。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のアンインストール方法はありますか？

アンインストールコマンドはありません。なぜなら、それはグローバルパッケージとプロジェクト内のファイルだからです。パッケージを削除し（npm uninstall -g @fission-ai/openspec）、オプションで openspec/ ディレクトリと生成されたツールファイルを削除してください。安全に保持すべきものを含めて、ステップバイステップのガイドは インストール：アンインストール にあります。

ヘルプを得る

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

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• ターミナルから: openspec feedback "your message" を実行すると、GitHubでIssueが作成されます。

このドキュメントは間違っているか、分かりにくいです。どうすればよいですか？

私たちに教えていただくか、修正してください。ドキュメンテーションのPR（プルリクエスト）は大歓迎であり、高く評価します。Issueを作成するか、プルリクエストを送信してください。