OpenSpec

探索から始める ​

/opsx:explore はあなたの思考パートナーです。問題はあるが計画がまだないときは、いつでもこれに頼ってください。 これはあなたのコードベースを調査し、選択肢を一緒に検討し、あなたが本当に何をしたいかを明確にします。すべては、成果物やコードが一行も書かれる前の段階で行われます。状況が明確になったら、/opsx:propose に引き継ぎます。

これらのドキュメントから一つだけ習慣を身につけるなら、これにしてください：わからないときは、提案する前に探索する。

なぜこれが重要なのか。AIコーディングアシスタントは意欲的です。曖昧に頼むと、自信満々に何かを構築してくれますが、それはあなたが本当に必要としたものとは限らないでしょう。Exploreはその処方箋です。リスクなしの対話で、あなたとAIが正しい手を一緒に見つけ出し、提案する段階に到達したときには、まさに正しいものを提案できるようにします。

探索すべきタイミング ​

Exploreが適切な第一歩となる場面は、多くの人が思っているより頻繁にあります。以下のいずれかに当てはまる場合は、Exploreを使用してください。

  • 問題はわかっているが、解決策はわからない。（「ページが遅い気がする」「認証がめちゃくちゃ」「重複注文が頻発する」）
  • 複数のアプローチの間で選んでおり、実際のコードに対するトレードオフを整理したい。
  • コードベースに慣れておらず、変更する前に仕組みを理解したい。
  • 要件が曖昧で、コミットする前に明確にしたい。
  • 作業量が見た目より大きくも小さくも思えて、正直にスコープを把握したい。

Exploreをスキップするのは、やりたいこととやり方がすでに明確にわかっている場合だけです。その場合は /opsx:propose に直接進んでください。

何をするのか（しないのか） ​

Exploreは対話であり、生成器ではありません。

やること：

  • コードベースを読み込み・検索し、実質的な質問に答える。
  • 選択肢を比較し、それぞれのトレードオフを明示する。
  • 図を描いて設計を可読にする。
  • 曖昧なアイデアを、具体的な・実装可能なスコープに絞り込むのを助ける。
  • 準備ができた時点で /opsx:propose へ移行する。

やらないこと：

  • 変更フォルダを作成しない。
  • 成果物を一切書かない（提案書、仕様、設計、タスクはすべて対象外）。
  • コードを書いたり変更したりしない。

これがポイントです。探索にはコストがかからず、何にもコミットしません。3つの行き止まりを探索し、それぞれから学び、最後に生き残った道筋だけを提案できます。

すでにインストール済み ​

朗報です。/opsx:explore はデフォルトの core プロファイルに同梱されており、propose、apply、update、sync、archive と並んでいます。何かを有効にする必要はありません。プロジェクトでOpenSpecが設定されていれば、ExploreはAIチャットでいつでも利用できます。（他の /opsx:* コマンドと同様、ターミナルではなくアシスタントのチャットに入力します。詳しくは How Commands Work を参照。）

完全な例 ​

曖昧な懸念が、明確で実装可能な変更に変化する様子をご覧ください。

text
You: /opsx:explore

AI:  What would you like to explore?

You: Our checkout sometimes creates duplicate orders. I don't know why
     and I don't know how to fix it safely.

AI:  Let me dig into the checkout path...
     [reads the order service, the payment webhook handler, and the
      client submit logic]

     Here's what I found. There are two ways a duplicate can happen:

     1. The client can submit twice (double-click, retry on slow network).
        Nothing debounces it.
     2. The payment webhook can fire more than once, and the handler
        creates an order each time. There's no idempotency key.

     Cause #2 is the dangerous one: it can charge and fulfill twice.

     Three ways to fix it, roughly in order of robustness:
     - Idempotency key on the order-creation endpoint (handles both causes)
     - Dedup on the webhook by payment-intent id (handles #2 only)
     - Client-side debounce (handles #1 only, papers over the real bug)

     Given your code already stores the payment-intent id, the
     idempotency-key approach is a small change with the biggest payoff.
     Want me to scope that?

You: Yes, let's do the idempotency key.

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

AI:  Created openspec/changes/add-order-idempotency-key/, with a proposal
     and delta spec grounded in what we just found. Ready for implementation.

何が起きたかに注目してください。出発点は「何かおかしいし、触るのが怖い」でした。20秒の探索で、それは名前のついた根本原因、3つの優先順位付きの選択肢、既存コードに紐づいた推奨案、そして正確な変更内容へと変わりました。続く提案が的確なのは、先に思考が行われたからです。

propose への引き継ぎ ​

Exploreは何かをアーカイブしません。準備ができた時点で、単に変更を開始すればよく、AIが対話の文脈を成果物に持ち込みます。

text
explore  ──►  propose  ──►  apply  ──►  archive
 (think)     (agree)       (build)     (record)

自然な言葉で伝える（「これを变更に変えよう」など）か、/opsx:propose <name> を直接実行するか、どちらでも構いません。どちらにせよ、先ほど行った探索は使い捨てのチャットではなく、提案の基盤になります。

拡張コマンドセットを使用している場合、Exploreは /opsx:new へ引き継ぐこともでき、成果物をステップバイステップで作成できます。詳しくは Workflows を参照。

良い探索のためのヒント ​

  • 問題を持ってきて、解決策は持たない。 「ログインが遅い気がする」なら、AIが調査する余地があります。「Redisキャッシュを追加」は、まだ検証していない答えに先回りしてコミットしてしまいます。
  • トレードオフを声に出して聞く。 「各選択肢のデメリットは？」と聞くと、より誠実な比較が得られます。
  • まず読ませる。 最高の探索は、AIが推測するのではなく、実際にコードを見てから始まります。関連する領域を指し示すと助けになります。
  • 途中でやめるのはOK。 探索の結果、アイデアが価値がないとわかったら、それは勝利です。低コストで学べたからです。
  • 変更の途中でまた探索する。 /opsx:apply の途中で詰まった？ 一歩下がってサブ問題を探索し、戻ってくることができます。

正直なトレードオフ ​

得られるもの： Exploreは、成果物が存在する前の最もコストの低いタイミングで、誤った方向性をキャッチします。特に馴染みのないコードでは、AIの読み取り・要約能力が、半日の探索作業を節約してくれます。

かかるコスト： 少しの忍耐。Exploreは対話なので、/opsx:propose を投げて運に任せるより遅いです。本当にすでに理解している作業には、この追加ステップは純粋なオーバーヘッドであり、スキップすべきです。

目安はこれです：タスクが曖昧なほど、Exploreの効果が大きくなります。タスクが明確なほど、提案に直接進んで問題ありません。

次のステップ ​