OpenSpec

先探索 ​

/opsx:explore 是你的思考夥伴。當你遇到問題但還沒有計畫時，就找它。 它會調查你的程式碼庫，與你一起權衡各種選項，並釐清你真正想要的東西——這一切都在任何產出物或程式碼被建立之前完成。當方向明確時，它會交接給 /opsx:propose。

如果你從這些文件中只帶走一個習慣，那就帶走這個：不確定的時候，先探索再提案。

這很重要。AI 編碼助手很急於行動。你模糊地問，它們就會自信地構建某種東西，只是可能不是你需要的東西。探索就是解藥。它是一場沒有風險的對話，讓你和 AI 一起找出正確的方向，這樣當你提案時，你提案的就是正確的東西。

何時探索 ​

探索作為第一步的時機比人們預期的更頻繁。以下任何情況都適用：

  • 你知道問題但不確定解決方案。（「頁面感覺很慢。」「認證系統亂成一團。」「我們不斷收到重複訂單。」）
  • 你在多種方案之間抉擇，希望針對實際程式碼列出權衡。
  • 你是新接觸一個程式碼庫，需要先理解某部分如何運作才能修改。
  • 需求模糊，你想在承諾之前將其釐清。
  • 你懷疑工作量比看起來更大或更小，想誠實地評估範圍。

只有當你已經完全清楚想要什麼以及如何實現時，才跳過探索。那種情況下直接前往 /opsx:propose。

它能做什麼（以及不能做什麼） ​

探索是一場對話，不是生成器。

它能做：

  • 讀取和搜尋你的程式碼庫來回答實際問題。
  • 比較選項並指出每個選項的權衡。
  • 繪製圖表讓設計更清晰易讀。
  • 幫助你將模糊的想法收窄為具體、可實作的範圍。
  • 當你準備好時，過渡到 /opsx:propose。

它不能做：

  • 建立變更資料夾。
  • 撰寫任何產出物（沒有提案、規格、設計或任務）。
  • 撰寫或修改程式碼。

這就是重點。探索不花費你任何成本，也不讓你承諾任何事。你可以探索三個死胡同，從每個中學習一些東西，然後才提案那條存活下來的路徑。

它已經安裝好了 ​

好消息：/opsx:explore 包含在預設的 core 配置中，與 propose、apply、update、sync 和 archive 並列。你不需要啟用任何東西。如果 OpenSpec 已在你的專案中設定好，探索功能就已在你的 AI 對話中就緒。（與所有 /opsx:* 命令一樣，你在助手的對話中輸入它，而不是在終端機中。請參閱 命令如何運作。）

完整範例 ​

看看一個模糊的擔憂如何變成一個明確、可實作的變更。

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.

注意發生了什麼。起點是「有什麼不對，我不敢碰。」二十秒的探索將其轉化為一個命名的根本原因、三個排序的選項、一個與現有程式碼相連的建議，以及一個精確的變更。後續的提案之所以精準，是因為思考先於行動。

交接給提案 ​

探索不會歸檔到任何地方。當你準備好時，你只需開始一個變更，AI 會將對話中的上下文帶入產出物中。

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

你可以用自然語言表達（「讓我們把這個變成一個變更」），或者直接執行 /opsx:propose <name>。無論哪種方式，你剛完成的探索都會成為提案的基礎，而不是被丟棄的閒聊。

如果你使用擴展命令集，探索可以交接給 /opsx:new，進行逐步的產出物建立。請參閱 工作流程。

良好探索的建議 ​

  • 帶問題來，而不是解決方案。 「登入感覺很慢」給 AI 留出調查空間。「加一個 Redis 快取」讓你預先承諾了一個尚未驗證的答案。
  • 大聲問出權衡。 「每個選項的缺點是什麼？」會讓你得到更誠實的比較。
  • 讓它先讀取。 最好的探索從 AI 實際查看你的程式碼開始，而不是猜測。如果有助於聚焦，可以指向相關區域。
  • 隨時可以撤退。 如果探索顯示這個想法不值得，那就是一次勝利。你以低廉的代價學到了東西。
  • 變更中途再次探索。 在 /opsx:apply 期間卡住了？你可以退後一步探索一個子問題，然後回來。

誠實的權衡 ​

你獲得的： 探索在成本最低的時間點捕捉錯誤方向，在任何產出物存在之前。它在陌生的程式碼中特別強大，AI 讀取和總結系統的能力為你節省了半天的摸索時間。

你付出的： 一點耐心。探索是一場對話，所以它比直接發射 /opsx:propose 然後寄希望於結果要慢。對於你已經真正理解的工作，那額外的步驟是純粹的開銷，你應該跳過它。

經驗法則：任務越模糊，探索的回報越高。任務越明確，你越可以直接跳過到提案。

接下來去哪裡 ​