例とレシピ
実際の変更を、最初から最後まで。各レシピでは、入力するコマンドとその結果を表示するので、自分の状況に合わせてパターンを選んでコピーできます。ここではデフォルトのコアコマンド（propose、explore、apply、sync、archive）を使用しています。拡張コマンドセットが役立つ場合は、その旨を記載しています。
開始前の注意：/opsx:proposeのようなスラッシュコマンドはAIアシスタントのチャットに入力し、openspecコマンドはターミナルで実行します。これが初めての方は、まずコマンドの仕組みをお読みください。以下の記録では、You:とAI:がチャットでのやり取りを、$で始まる行がターミナルでの実行を示しています。
まだ何を作るか決まっていませんか？ ほとんどのレシピは、まず
/opsx:exploreで検討を始めるとより効果的です。レシピ3で実際の使い方を示しており、最初に探索ガイドではその詳細を説明しています。
レシピ1：小さな機能、高速パス
使用タイミング： 作りたいものが明確で、作業範囲が限定されている場合。最も一般的なレシピです。
全体で3つのコマンドです。提案（propose）、構築（apply）、アーカイブ（archive）。
text
You: /opsx:propose add-logout-button
AI: openspec/changes/add-logout-button/ を作成しました
✓ proposal.md — 目的と内容
✓ specs/ — 新しい要件とそのシナリオ
✓ design.md — 技術的アプローチ
✓ tasks.md — 実装チェックリスト
実装の準備ができました。/opsx:apply を実行してください。次に計画を確認してください。提案書と差分仕様を開いてください。これこそがOpenSpecの真骨頂です：誤った前提を、400行のコードになってしまう前に、たった1段落の段階で捉えることができます。何かおかしい場合は、成果物を直接編集してから続行してください。
text
You: /opsx:apply
AI: タスクを実行中...
✓ 1.1 ヘッダーにログアウトボタンを追加
✓ 1.2 クリック時にセッションをクリア
✓ 1.3 確認ダイアログを追加
すべてのタスクが完了しました！
You: /opsx:archive
AI: add-logout-button をアーカイブしています...
✓ 仕様を openspec/specs/auth/spec.md にマージ
✓ openspec/changes/archive/2026-06-22-add-logout-button/ に移動
完了しました。次の変更の準備ができました。以上です。ログアウトの動作が仕様の一部となり、変更内容とその完全なコンテキストがアーカイブされました。
レシピ2：バグ修正
使用タイミング： 何かが壊れており、その修正を「謎のコミット」ではなく、意図的な動作変更として記録したい場合。
バグ修正は機能と全く同じように動作します。違いは提案書の記載方法にあります：単に「バグを修正」と書くのではなく、正しい動作を説明してください。
text
You: /opsx:propose fix-login-redirect-loop
AI: openspec/changes/fix-login-redirect-loop/ を作成しました
提案書には、現在の壊れた動作と意図した動作の両方が記載されています。
差分仕様はリダイレクトの要件を MODIFY（変更）し、それが正確でテスト可能なものになっています。
実装の準備ができました。修正がMODIFIED要件として新しいシナリオとともに適用されるため、次の担当者（または次のAIセッション）は「修正した」という事実だけでなく、「正しい」とは何かを理解できます。その後は、通常通り/opsx:applyと/opsx:archiveを実行してください。
ヒント：修正の場合、良いシナリオとは回帰テストを文章で記述したものです。「前提：ログアウト状態のユーザー、条件：有効な認証情報を送信した場合、結果：ダッシュボードに遷移し、再びリダイレクトされない」と書けば、実装すべき明確な目標が定まります。
レシピ3：コミット前に探索する
使用タイミング： 問題はあるが計画が立っていない場合。何を作るべきか、どのアプローチが適しているか分からない場合。
/opsx:exploreから始めましょう。これは構造がなく、成果物も作成しない思考パートナーです。コードベースを読み、意思決定を支援します。
text
You: /opsx:explore
AI: 何を探索しますか？
You: ページの読み込みが遅いが、時間がかかっている箇所が分からない。
AI: 調べてみます... 以下の3つが考えられます：
1. 商品一覧の最適化されていない大きな画像
2. レンダリングをブロックする同期的なデータフェッチ
3. コンテキストの変更による再レンダリング
どれから対処しますか？
You: データフェッチの方です。
You: /opsx:propose optimize-product-list-fetching
AI: 変更を作成しました。先ほど見つかった内容に基づいた提案書です。
実装の準備ができました。探索により、変更に着手する前に思考を明確にできます。洞察が固まったら提案を行えば、AIがコンテキストを引き継ぎます。
レシピ4：2つの変更を同時に進める
使用タイミング： 機能開発の途中で、緊急の修正が割り込んできた場合。
変更は独立したフォルダーで管理されるため、並行作業が競合することはありません。修正を開始してリリースし、その後、中断した箇所から機能開発に戻れます。
text
You: add-dark-mode の途中だが、今すぐログインのバグを修正する必要がある。
You: /opsx:propose fix-login-redirect
AI: openspec/changes/fix-login-redirect/ を作成しました。実装の準備ができました。
You: /opsx:apply
AI: 修正を実装しました。すべてのタスクが完了しました。
You: /opsx:archive
AI: ✓ fix-login-redirect をアーカイブしました。
You: ダークモードに戻る。
You: /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
You: /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
You: /opsx:new add-2fa
AI: openspec/changes/add-2fa/ を作成しました。作成可能：提案書。
You: /opsx:continue
AI: proposal.md を作成しました。利用可能：仕様、設計。
You: /opsx:continue
AI: specs/auth/spec.md を作成しました。利用可能：設計。各成果物が作成されたら確認し、自由に編集して、満足したら続行してください。残りの計画成果物を一度に下書きしたい場合は、/opsx:ffでスキップできます。アーカイブする前に、/opsx:verifyで実装が仕様と実際に一致するか確認します。ワークフローを参照してください。
レシピ7：全体のワークフローを実践で学ぶ
使用タイミング： OpenSpecをインストールし、サンプルではなく実際のコードでワークフローを体感したい場合。
拡張コマンドを有効にしてから（レシピ6を参照）、以下を実行してください：
text
You: /opsx:onboard
AI: OpenSpecへようこそ！実際のコードベースを使用して、完全な変更を一緒に進めます。
小さく安全な改善点を探してみます.../opsx:onboardは実際の（小さな）改善点を見つけ、変更を作成して実装し、アーカイブするまで、各ステップを説明しながら進めます。所要時間は15〜30分で、残る結果は保存または破棄できる実際の変更です。これが最も優しい学習方法です。コマンドを参照してください。
ターミナルから作業を確認する
いつでもターミナルから、状態を確認できます：
bash
$ openspec list # アクティブな変更
$ openspec show add-dark-mode # 変更の詳細
$ openspec validate add-dark-mode # 構造を確認
$ openspec view # インタラクティブなダッシュボードこれらは読み取り・確認用のツールです。提案と構築は、チャットのスラッシュコマンドで行います。詳細はCLIリファレンスを参照してください。