例とレシピ

実際の変更を最初から最後まで紹介します。各レシピでは、入力するコマンドとその結果を示すため、自分の状況に近いパターンを見つけて手順を応用できます。既定の core コマンド（propose、explore、apply、update、sync、archive）を使います。拡張セットが役立つ場合はその旨を記載します。

始める前に確認してください。/opsx:propose などのスラッシュコマンドは AI アシスタントとのチャット に、openspec コマンドは ターミナル に入力します。初めての場合は、先にコマンドの実行方法を読んでください。以下の会話例で You: と AI: はチャット、$ で始まる行はターミナルです。

何を作るかまだ決まっていませんか？ まず /opsx:explore で考えを整理すると、多くのレシピでより良い結果が得られます。レシピ3では具体的な使い方を、まず Exploreでは詳しい理由を紹介します。

レシピ1: 小さな機能を素早く実装する

使う場面: 実現したいことが分かっていて、作業範囲が限られている場合。最もよく使われるレシピです。

コマンドは3つだけです。提案し、実装し、アーカイブします。

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

AI:  openspec/changes/add-logout-button/ を作成しました
     ✓ proposal.md — 理由と内容
     ✓ specs/      — 新しい要件とシナリオ
     ✓ design.md   — 技術的な方針
     ✓ tasks.md    — 実装チェックリスト
     実装を開始できます。/opsx:apply を実行してください。

次に計画を読みます。提案と差分仕様を開いてください。1段落の誤った前提を、400行のコードになる前に見つけることこそ、OpenSpec が役立つ場面です。問題があれば成果物を直接編集してから続けます。

あなた: /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/ に移動しました
     完了しました。次の change に進めます。

これで完了です。ログアウトの動作が仕様に反映され、change は全体の文脈とともに保管されました。

レシピ2: バグを修正する

使う場面: 何かが壊れていて、謎のコミットとしてではなく、意図的な動作変更として修正を記録したい場合。

バグ修正も機能追加と同じ手順です。違いは提案の表現方法です。「バグを直す」だけではなく、正しい 動作を記述してください。

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

AI:  openspec/changes/fix-login-redirect-loop/ を作成しました
     提案では現在の不具合と意図する動作を記述しています。
     差分仕様ではリダイレクト要件を MODIFIED として変更し、
     明確でテスト可能な内容にしました。
     実装を開始できます。

修正内容は新しいシナリオを伴う MODIFIED 要件として記録されるため、次の担当者（または次の AI セッション）は、修正したことだけでなく「正しい」とはどういうことかも把握できます。その後は通常どおり /opsx:apply と /opsx:archive を実行してください。

ヒント: 修正時に有効なシナリオは、文章で記述した回帰テストです。「GIVEN ログアウト状態のユーザーがいる、WHEN 有効な認証情報を送信する、THEN ダッシュボードに移動し、再度リダイレクトされない」と書けば、実装の目標が明確になります。

レシピ3: 着手前に explore する

使う場面: 問題はあるものの計画がなく、何を作るべきか、どの方法が適切か分からない場合。

/opsx:explore から始めます。形式に縛られない思考パートナーです。コードを書くことはなく、決定した内容を記録するよう依頼するか、記録の提案に同意しない限り、他のファイルも書き込みません。コードベースを読み、判断を支援します。

あなた: /opsx:explore

AI:  何を調べましょうか？

あなた: ページの読み込みが遅いと感じますが、どこで時間がかかるか分かりません。

AI:  調べてみます... 主な原因として、次の3つが考えられます。
     1. 商品一覧に最適化されていない大きな画像がある
     2. 同期的なデータ取得がレンダリングを妨げている
     3. context の変更によって再レンダリングが発生している
     どれから対処しましょうか？

あなた: データ取得の問題からお願いします。

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

AI:  直前の調査結果に基づく提案とともに change を作成しました。
     実装を開始できます。

explore を使えば、change に着手する 前 に考えを明確にできます。結論が出たら提案し、AI がそれまでの文脈を引き継ぎます。

レシピ4: 2つの change を並行して進める

使う場面: 機能の実装中に、緊急の修正が割り込んだ場合。

change は独立したフォルダーなので、並行作業でも競合しません。修正を始めてリリースし、その後、中断した機能の作業に戻ります。

あなた: 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: Header の更新から始めます...

複数の change が作業中の場合、/opsx:apply add-dark-mode のように名前を指定すると、対象を AI に伝えられます。完了状況は tasks.md で追跡するため、AI は中断した位置を正確に把握できます。

複数の change をまとめて完了する場合、拡張コマンド /opsx:bulk-archive で一括アーカイブし、実際の実装内容を確認して仕様の競合を解決できます。ワークフローを参照してください。

レシピ5: 動作を変えないリファクタリング

使う場面: コードを再構成するが、外部から見える動作は変えない場合。

これは興味深いケースです。純粋なリファクタリングでは、仕様に追加する内容がありません。動作の契約は変わらず、実装だけが変わります。そのため、作業内容は設計とタスクに記述し、仕様の差分は空にするか省略します。

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

AI:  change を作成しました。提案では目標（決済モジュールを分割し、動作は変えない）を
     示し、設計では新しい構成を記述します。動作は同じなので仕様の変更はありません。
     実装を開始できます。

change の .openspec.yaml に skip_specs: true を設定し、差分が空であることを明示します。

schema: spec-driven
skip_specs: true

このマーカーがない場合、openspec validate は差分が0件の change を拒否します（仕様作成フェーズの忘れを検出できます）。マーカーがあれば検証を通過し、openspec status では specs 段階が未着手ではなく明示的なスキップとして表示されます。リファクタリングによって動作が変わると分かった場合は、.openspec.yaml から skip_specs を削除し、差分仕様を作成してください。検証ではマーカーと仕様ファイルの併用が競合と見なされるため、古いマーカーが気付かれずに残ることはありません。

マーカーを付けた change のアーカイブには追加のフラグは不要です（マージする差分がありません）。また、ターミナルコマンドに --skip-specs フラグを指定すると、仕様の手順を明示的にスキップできます。

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

同じフラグは、ツール、CI、ドキュメントのみの変更にも便利です。仕様は動作を記述するため、動作が変わらなければ仕様も変えるべきではありません。概念を参照してください。

レシピ6: 段階的に制御する（拡張コマンド）

使う場面: 各成果物を確認してから次に進みたい、複雑またはリスクの高い change。

core の /opsx:propose はすべてを一度に下書きします。1段階ずつ進めたい場合は、拡張コマンドを有効にしてください。

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

これでひな型を作成し、段階的に進められます。

あなた: /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を参照）、次を実行します。

あなた: /opsx:onboard

AI:  OpenSpec へようこそ。実際のコードベースで変更の全工程を案内します。
     一緒に取り組める小さく安全な改善を探します...

/opsx:onboard は実際の（小さな）改善を見つけて change を作成し、各手順を説明しながら実装とアーカイブまで行います。所要時間は15〜30分で、保持または破棄できる実際の change が残ります。最も気軽に学べる方法です。コマンドを参照してください。

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

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

$ openspec list                      # 作業中の change
$ openspec show add-dark-mode        # 1つの change の詳細
$ openspec validate add-dark-mode    # 構造を確認
$ openspec view                      # 対話型ダッシュボード

これらは読み取りと確認のためのツールです。提案や実装は引き続きチャット内のスラッシュコマンドで行います。詳しくはCLI リファレンスを参照してください。

次に読むページ

• まず Explore: 迷っているときに推奨する開始方法
• ワークフロー: 各パターンをいつ使うかの判断ガイド
• コマンド: すべてのスラッシュコマンドの詳細
• はじめに: 最初の change を一通り進めるガイド
• 概念: それぞれの要素がどのように連携するか