OpenSpec

例とレシピ ​

実際の変更を最初から最後まで紹介します。各レシピは、入力するコマンドとその結果を表示しているので、自分の状況に合ったパターンを見つけてコピーできます。ここではデフォルトのコアコマンド（propose、explore、apply、update、sync、archive）を使用します。拡張コマンドセットが役立つ場合は、その都度注記します。

始める前の注意：/opsx:propose のようなスラッシュコマンドは AIアシスタントのチャット に入力し、openspec コマンドは ターミナル に入力します。これが初めての場合は、最初に コマンドの仕組み を読んでください。以下のトランスクリプトでは、あなた: と AI: はチャットを表し、$ で始まる行はターミナルを表します。

まだ何を作るか決めていない場合 これらのレシピのほとんどは、最初に /opsx:explore でじっくり考えると効果的です。レシピ3 でその動作を確認でき、Explore First ガイドで詳しく説明しています。

レシピ1: 小さな機能、高速パス ​

使用場面： 何をしたいか明確で、限定された作業である場合。これは最も一般的なレシピです。

全体は3つのコマンドです。提案、構築、アーカイブ。

text
あなた: /opsx:propose add-logout-button

AI:  openspec/changes/add-logout-button/ を作成しました
     ✓ proposal.md — 理由と内容
     ✓ specs/      — 新しい要件とそのシナリオ
     ✓ design.md   — 技術的アプローチ
     ✓ tasks.md    — 実装チェックリスト
     実装の準備ができました。/opsx:apply を実行してください。

次に計画を読みます。プロポーザルと差分スペックを開いてください。OpenSpec は、誤った前提をまだ1段落のうちに発見するために作られています（400行のコードになる前に）。何か問題があれば、任意のアーティファクトを直接編集してから続行してください。

text
あなた: /opsx:apply

AI:  タスクを処理中...
     ✓ 1.1 ヘッダーにログアウトボタンを追加
     ✓ 1.2 クリック時にセッションをクリア
     ✓ 1.3 確認ダイアログを追加
     すべてのタスクが完了しました！

あなた: /opsx:archive

AI:  add-logout-button をアーカイブ中...
     ✓ スペックを openspec/specs/auth/spec.md にマージしました
     ✓ openspec/changes/archive/2026-06-22-add-logout-button/ に移動しました
     完了。次の変更の準備ができました。

これで完了です。ログアウト動作がスペックに組み込まれ、変更は完全なコンテキストとともに保管されました。

レシピ2: バグ修正 ​

使用場面： 何かが壊れていて、その修正を意図的な動作変更として記録したい場合（謎のコミットにしたくない場合）。

バグ修正は機能とまったく同じように動作します。違いはプロポーザルの組み立て方にあります。「バグを修正」ではなく、正しい 動作を記述してください。

text
あなた: /opsx:propose fix-login-redirect-loop

AI:  openspec/changes/fix-login-redirect-loop/ を作成しました
     プロポーザルは現在の壊れた動作と意図した動作を捉えています。
     差分スペックはリダイレクト要件を MODIFY し、今や正確でテスト可能になりました。
     実装の準備ができました。

修正が MODIFIED 要件と新しいシナリオとして記録されるため、次の人（または次のAIセッション）は、修正したことだけでなく、「正しい」とは何かを理解できます。それから通常どおり /opsx:apply と /opsx:archive を実行します。

ヒント: 修正の場合、良いシナリオは散文での回帰テストです。「ログアウトしたユーザーが有効な資格情報を送信した場合、ダッシュボードに到達し、再びリダイレクトされない。」これを書けば、実装には明確な目標があります。

レシピ3: コミット前の探索 ​

使用場面： 問題はあるがまだ計画がない、何を構築すべきか、どのアプローチが正しいかわからない場合。

/opsx:explore から始めます。これは構造や生成物のない思考パートナーです。コードベースを読み、決定を支援します。

text
あなた: /opsx:explore

AI:  何を探索したいですか？

あなた: ページの読み込みが遅く感じますが、時間のどこに費やされているかわかりません。

AI:  見てみましょう... 可能性の高い原因が3つ見つかりました：
     1. 商品リストの最適化されていない大きな画像
     2. レンダリングをブロックする同期データ取得
     3. コンテキスト変更によってトリガーされる再レンダリング
     どれから取り組みますか？

あなた: データ取得の問題から。

あなた: /opsx:propose optimize-product-list-fetching

AI:  変更を作成しました。今見つけた内容に基づいたプロポーザルがあります。実装の準備ができました。

探索は、変更に着手する前に思考を明確にします。洞察が固まったら提案し、AI がコンテキストを引き継ぎます。

レシピ4: 2つの変更を同時に扱う ​

使用場面： 機能の途中で緊急の修正が割り込む場合。

変更は独立したフォルダーなので、並行作業は衝突しません。修正を開始してリリースし、その後、中断した場所から機能に戻ります。

text
あなた: add-dark-mode の途中ですが、今ログインバグを修正する必要があります。

あなた: /opsx:propose fix-login-redirect

AI:  openspec/changes/fix-login-redirect/ を作成しました。実装の準備ができました。

あなた: /opsx:apply

AI:  修正を実装しました。すべてのタスクが完了しました。

あなた: /opsx:archive

AI:  ✓ fix-login-redirect をアーカイブしました。

あなた: ダークモードに戻ります。

あなた: /opsx:apply add-dark-mode

AI:  add-dark-mode を再開します。タスク2.3「ヘッダーを更新」から再開します。

/opsx:apply add-dark-mode のように変更名を指定することで、複数の変更がアクティブなときに AI を特定の変更に導きます。タスクは tasks.md で完了状況を追跡するため、AI は中断した場所を正確に把握できます。

複数の変更が同時に完了した場合は、拡張コマンドの /opsx:bulk-archive でまとめてアーカイブし、実際に実装された内容を確認してスペックの衝突を解決します。ワークフロー を参照してください。

レシピ5: 動作変更のないリファクタリング ​

使用場面： コードを再構築し、外部から見える動作が同一でなければならない場合。

これは興味深いケースです。純粋なリファクタリングでは、スペックに追加するものは何もありません。動作の契約は変わらず、実装のみが変わります。そのため、作業は設計とタスクに含まれ、スペック差分は空または存在しません。

text
あなた: /opsx:propose refactor-payment-module

AI:  変更を作成しました。プロポーザルは目標（ペイメントモジュールの分割、動作変更なし）を述べ、設計は新しい構造を捉えています。動作が同一なのでスペックの変更はありません。実装の準備ができました。

変更の .openspec.yaml に skip_specs: true を設定して、空の差分を明示的に宣言します：

yaml
schema: spec-driven
skip_specs: true

このマーカーがない場合、openspec validate は差分がゼロの変更を拒否します（これにより、スペック段階の忘れも検出されます）。マーカーがあれば検証は通り、openspec status はスペック段階を保留中ではなく明示的にスキップとして表示します。リファクタリングが結局動作を変更することが判明した場合は、.openspec.yaml から skip_specs を削除して差分スペックを書いてください。検証はマーカーとスペックファイルの併存を衝突として扱うため、古いマーカーが静かに残ることはありません。

マーク付き変更のアーカイブには追加フラグは不要です（マージする差分がないため）。独立して、--skip-specs フラグはターミナルコマンドにスペックステップを明示的にスキップするよう指示します：

bash
$ openspec archive refactor-payment-module --skip-specs

同じフラグは、ツーリング、CI、ドキュメントのみの変更にも便利です。原則：スペックは動作を記述するものであり、動作が変わっていないならスペックも変わらないはずです。コンセプト を参照してください。

レシピ6: ステップバイステップ制御（拡張コマンド） ​

使用場面： 複雑またはリスクの高い変更で、各アーティファクトを移動前にレビューしたい場合。

コアの /opsx:propose は一度にすべてをドラフトします。1ステップずつ進めたい場合は、拡張コマンドを有効にします：

bash
$ openspec config profile      # 拡張ワークフローを選択
$ openspec update              # このプロジェクトに適用

これで段階的にスキャフォールドとビルドができます：

text
あなた: /opsx:new add-2fa

AI:  openspec/changes/add-2fa/ を作成しました。作成待ち: proposal。

あなた: /opsx:continue

AI:  proposal.md を作成しました。利用可能: specs、design。

あなた: /opsx:continue

AI:  specs/auth/spec.md を作成しました。利用可能: design。

各アーティファクトが生成されたらレビューし、自由に編集し、満足したら続行します。残りを一度にドラフトしたい場合は、/opsx:ff で残りの計画アーティファクトを高速処理します。アーカイブ前には、/opsx:verify で実装が実際にスペックと一致するかを確認します。ワークフロー を参照してください。

レシピ7: ループ全体を実践的に学ぶ ​

使用場面： OpenSpec をインストールし、おもちゃの例ではなく自分のコードでワークフローを体感したい場合。

拡張コマンドを有効にし（レシピ6を参照）、次に：

text
あなた: /opsx:onboard

AI:  OpenSpec へようこそ！実際のコードベースを使った完全な変更を案内します。
     一緒にできる小さく安全な改善を探してみましょう...

/opsx:onboard は実際の（小さな）改善を見つけ、変更を作成し、実装し、アーカイブし、各ステップを説明します。所要時間は15〜30分で、保持または破棄できる実際の変更が残ります。最も穏やかな学習方法です。コマンド を参照してください。

ターミナルから作業を確認する ​

いつでもターミナルから状態を確認できます：

bash
$ openspec list                      # アクティブな変更
$ openspec show add-dark-mode        # 1つの変更を詳細に表示
$ openspec validate add-dark-mode    # 構造をチェック
$ openspec view                      # インタラクティブダッシュボード

これらは読み取り・調査用ツールです。提案と構築は引き続きチャットのスラッシュコマンドで行います。詳細は CLIリファレンス を参照してください。

次のステップ ​

  • Explore First: 不確かな場合に推奨される開始方法
  • Workflows: 上記のパターンと、いつ使用するかの判断ガイド
  • Commands: すべてのスラッシュコマンドの詳細
  • Getting Started: 標準的な最初の変更のウォークスルー
  • Concepts: 各部分がなぜそのように連携するのか