まず Explore

/opsx:explore は考えを整理するパートナーです。問題はあるけれど計画がまだないときは、いつでも使ってください。 コードを1行も書く前にコードベースを調査し、選択肢を比較し、本当に実現したいことを明確にします。全体像が見えたら /opsx:propose に引き継ぎます。

このドキュメントから習慣を1つだけ身に付けるなら、これにしてください。迷ったら、提案する前に explore する。

これが重要な理由を説明します。AI コーディングアシスタントは積極的です。曖昧に頼むと、自信満々に 何か を作りますが、それは必要なものではないかもしれません。explore はその解決策です。リスクのない対話を通じて AI と一緒に適切な進め方を見つけるので、提案するときには正しい内容を提案できます。

explore を使うタイミング

explore は、多くの人が思うよりも幅広い場面で最初の一歩として適しています。次のいずれかに当てはまる場合に使ってください。

• 問題 は分かっているが、解決策 は分からない。（「ページの表示が遅い」「認証の仕組みが複雑」「注文が重複する」）
• 方法をいくつか比較しており、実際のコードに即したトレードオフを整理したい。
• コードベースに詳しくなく、変更前に動作を理解したい。
• 要件が曖昧で、確定する前に明確にしたい。
• 作業が見た目より大きい、または小さいのではないかと思い、正直に範囲を見極めたい。

実現したいことと方法が明確な場合に限り、explore を省略できます。その場合は直接 /opsx:propose を実行してください。

explore でできること・できないこと

explore は生成ツールではなく、対話です。

できること:

• 実際の質問に答えるため、コードベースを読み、検索する。
• 選択肢を比較し、それぞれのトレードオフを示す。
• 図を描いて設計を分かりやすくする。
• 曖昧なアイデアを、具体的で実装可能な範囲に絞り込む。
• 依頼された場合、または提示に同意した場合に、調査内容を記録する。openspec new change で change のひな型を作り、指定された計画成果物を作成するか、既存 change の成果物を更新する。
• 準備ができたら /opsx:propose に移行する。

できないこと:

• コードを書く、または変更する。調査内容を記録する場合も、どのパスのコードも変更しない。
• スキーマやテンプレートを設計、編集する。それらを整えるのは思考ではなく変更作業です。
• 独断で change を開始したり、成果物を書いたりする。依頼するか提示に同意しない限り、何も書き込みません。同意した場合も、合意した内容と change の開始に必要なセットアップファイルだけを作成します（後述）。
• 記録を強要する。考えがまとまったときに提案しますが、決めるのはあなたです。

これが重要な点です。明示するまで、explore に費用も確約も伴いません。3つの行き止まりを調べてそれぞれから学び、最後に残った道筋だけを提案できます。

すでに使える状態です

朗報です。/opsx:explore は propose、apply、update、sync、archive とともに、既定の core プロファイルに含まれています。有効化の操作は必要ありません。プロジェクトに OpenSpec を設定済みなら、AI とのチャットですぐに使えます（すべての /opsx:* コマンドと同様、入力する場所はターミナルではなくアシスタントのチャットです。コマンドの実行方法を参照してください）。

実例

漠然とした心配が、明確で実装可能な change に変わる様子を見てみましょう。

あなた: /opsx:explore

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

あなた: チェックアウトで注文が重複することがあります。原因が分からず、
     安全に修正する方法も分かりません。

AI:  チェックアウトの処理を調べます...
     [注文サービス、決済 webhook ハンドラー、クライアントの送信処理を確認]

     調査したところ、重複が起きる経路は2つあります。

     1. クライアントが2回送信する（ダブルクリックや低速ネットワークでの再試行）。
        送信を抑止する仕組みはありません。
     2. 決済 webhook が複数回発火すると、そのたびにハンドラーが注文を作成します。
        冪等性キーもありません。

     危険なのは原因2です。二重に課金され、二重に注文が処理されるおそれがあります。

     修正方法は大きく分けて3つあり、堅牢性の高い順に示します。
     - 注文作成エンドポイントに冪等性キーを設ける（両方の原因に対応）
     - payment-intent ID で webhook の重複を排除する（原因2のみ対応）
     - クライアント側で連続送信を抑止する（原因1のみ対応し、根本原因には対処しない）

     既存コードでは payment-intent ID が保存されているため、
     冪等性キー方式なら小さな変更で大きな効果が得られます。
     この方法で範囲を整理しましょうか？

あなた: はい、冪等性キーを使いましょう。

You: /opsx:propose add-order-idempotency-key

AI:  調査結果に基づいて proposal と差分仕様を作成し、
     openspec/changes/add-order-idempotency-key/ に保存しました。実装を開始できます。

何が起きたかに注目してください。出発点は「何かがおかしいが、触るのが怖い」でした。20秒の調査で、特定された根本原因、優先順位を付けた3つの選択肢、既存コードに基づく推奨案、明確な change が得られました。先に考えを整理したため、その後の提案も明確になります。

propose に引き継ぐ

explore は何かをアーカイブするコマンドではありません。準備ができたら change を開始するだけで、AI が対話の文脈を成果物に引き継ぎます。

explore  ──►  propose  ──►  apply  ──►  archive
 (考える)     (合意する)     (構築する)   (記録する)

「これを change にしましょう」と普通の言葉で伝えるか、/opsx:propose <name> を直接実行できます。どちらの場合も、直前の調査内容が使い捨てのチャットではなく、提案の基礎になります。

会話を続けたまま、explore に change の記録を頼むこともできます。「これについて change を開始して」と伝えるとフォルダーが作られ、「proposal も書いて」と頼むと指定した成果物だけが書き込まれます。ひな型の作成では change 固有のメタデータも用意し、プロジェクトに不足しているルート項目（openspec/specs/、openspec/changes/archive/、config.yaml）も補います。

行き着く先は引き継ぎと同じですが、違いが1つあります。propose はスキーマで実装までに必要とされる成果物一式を作成するのに対し、記録では指定した成果物だけを書き込みます。

拡張コマンドセットを使っている場合、explore から /opsx:new に引き継いで、成果物を段階的に作成することもできます。ワークフローを参照してください。

効果的に explore するためのヒント

• 解決策ではなく問題を伝える。 「ログインが遅い」なら AI が調査できます。「Redis キャッシュを追加して」では、まだ検証していない答えに最初から決めつけてしまいます。
• トレードオフを具体的に尋ねる。 「各選択肢の欠点は何ですか？」と聞くと、より率直な比較が得られます。
• まずコードを読ませる。 推測ではなく、実際にコードを調べるところから始めるのが最良です。必要なら関連領域を指定してください。
• 途中でやめてもかまいません。 調査の結果、そのアイデアに価値がないと分かったなら、それも成果です。少ないコストで学べました。
• change の途中でも再度 explore する。 /opsx:apply 中に行き詰まったら、いったん戻ってサブ問題を調査し、その後に作業を再開できます。

正直なトレードオフ

得られるもの: 何かに着手する前の最小コストの段階で、誤った方向を見つけられます。特に不慣れなコードでは、AI がシステムを読み解いて要約することで、何時間もコードを調べる手間を省けます。

必要なコスト: 少しの時間です。explore は対話なので、/opsx:propose をすぐ実行して結果に期待するより時間がかかります。作業内容をすでに十分理解している場合、その手順は単なる余計な負担なので省略してください。

目安として、タスクが曖昧なほど explore の効果は大きく、明確なほど直接提案に進みやすくなります。

次に読むページ

• コマンド: /opsx:explore: 詳細なリファレンス
• ワークフロー: 日常の作業における explore の使い方
• 例とレシピ: 一連の手順を通した explore の例
• はじめに: explore を含む最初の変更ガイド