OpenSpec

先探索 ​

/opsx:explore 是你的思维伙伴。 当你遇到问题但尚未制定计划时，请随时使用它。它会调查你的代码库，与你权衡各种选项，并澄清你真正的需求，这一切都发生在生成任何工件或编写任何代码之前。当思路清晰后，它会将任务移交给 /opsx:propose。

如果你从这些文档中只养成一个习惯，那就是：当你不确定时，先探索再提议。

这就是为什么这很重要。AI 编程助手通常很积极。如果你提问模糊，它们会自信地构建某些东西，但可能并不是你真正需要的东西。探索就是解药。这是一个无风险的对话过程，你和 AI 共同找出正确的方向，这样当你提出建议时，你提出的才是正确的方案。

何时探索 ​

探索往往是比人们预期的更合适的起步步骤。在以下情况下使用它：

  • 你知道问题所在，但不知道解决方案。（例如：“页面感觉很慢。”、“认证逻辑一团糟。”、“我们总是收到重复订单。”）
  • 你在几种方法之间犹豫，希望结合你的实际代码来了解各自的利弊。
  • 你是新接触某个代码库，需要在修改之前理解其工作原理。
  • 需求模糊不清，你希望在承诺实施之前将其明确化。
  • 你怀疑工作量看起来比实际大或小，希望诚实地评估范围。

只有在你已经确切知道想要什么以及怎么做的时候，才跳过探索。在这种情况下，直接前往 /opsx:propose。

它能做什么（和不能做什么） ​

探索是一种对话，而不是生成器。

它能：

  • 阅读和搜索你的代码库以回答实际问题。
  • 比较各种选项并指出每种方案的利弊。
  • 绘制图表以使设计更加清晰易懂。
  • 帮助你将一个模糊的想法缩小为具体、可构建的范围。
  • 在你准备好时过渡到 /opsx:propose。

它不能：

  • 创建变更文件夹。
  • 编写任何工件（没有提案、规范、设计或任务）。
  • 编写或修改代码。

这正是它的目的。探索不会花费你任何东西，也不会让你做出任何承诺。你可以探索三个死胡同，从每个死胡同中学到一些东西，然后再提出那条幸存的路径。

它已安装就绪 ​

好消息是：/opsx:explore 包含在默认的 core 配置文件中，与 propose、apply、update、sync 和 archive 并列。你不需要启用任何额外功能。如果 OpenSpec 已在你的项目中设置，那么在你的 AI 聊天中即可使用探索功能。（与所有 /opsx:* 命令一样，你在助手的聊天窗口中输入它，而不是终端。请参阅 命令如何工作。）

完整示例 ​

看看一个模糊的担忧是如何变成一个尖锐、可构建的变更的。

text
你: /opsx:explore

AI: 你想探索什么？

你: 我们的结账流程有时会创建重复订单。我不知道原因，也不知道如何安全地修复它。

AI: 让我深入了解一下结账路径...
     [读取了订单服务、支付 webhook 处理程序和客户端提交逻辑]

     我发现了以下内容。有两种情况会导致重复：

     1. 客户端可以提交两次（双击、在网络缓慢时重试）。
        没有任何防抖机制来处理这种情况。
     2. 支付 webhook 可能会触发多次，而处理程序每次都会创建一个订单。
        这里没有幂等性键。

     原因 #2 是危险的：它可能会导致扣款和发货两次。

     有三种修复方法，大致按稳健性排序：
     - 在订单创建端点上使用幂等性键（可同时处理两种原因）
     - 通过 payment-intent id 对 webhook 进行去重（仅处理 #2）
     - 客户端侧防抖（仅处理 #1，掩盖了真正的 bug）

     鉴于你的代码已经存储了 payment-intent id，
     使用幂等性键的方法是一个小改动，却能带来最大的收益。
     要我把它细化为具体的范围吗？

你: 是的，我们来用幂等性键。

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

AI: 已创建 openspec/changes/add-order-idempotency-key/，其中包含基于刚才发现的内容制定的
     提案和增量规范。准备开始实施。

注意发生了什么。起点是“出问题了，而且我很害怕去碰它”。二十秒的探索将这个模糊的问题转化为了命名的根本原因、三个排序后的选项、一个基于现有代码的建议，以及一个精确的变更。随后的提案之所以精准，是因为思考工作已经完成。

移交给 propose ​

探索不会归档到任何内容中。当你准备好时，只需启动一个变更，AI 就会将对话中的上下文带入工件中。

text
explore  ──►  propose  ──►  apply  ──►  archive
 (思考)     (同意)       (构建)     (记录)

你可以用自然语言说（“让我们把它变成一个变更”），或者直接运行 /opsx:propose <name>。无论哪种方式，你刚刚进行的探索都将成为提案的基础，而不是被丢弃的聊天记录。

如果你使用扩展的命令集，探索也可以移交给 /opsx:new，以便逐步创建工件。请参阅 工作流。

良好探索的技巧 ​

  • 带上问题，而不是解决方案。 “登录感觉很慢”会给 AI 留出调查的空间。“添加 Redis 缓存”会让你提前承诺到一个尚未测试的答案上。
  • 大声说出利弊。 “每个选项的缺点是什么？”会得到更诚实的比较。
  • 让它先阅读。 最好的探索始于 AI 实际查看你的代码，而不是猜测。如果有帮助，请指向相关区域。
  • 放弃是可以的。 如果探索表明这个想法不值得做，那也是一种胜利。你低成本地学到了这一点。
  • 在变更过程中再次探索。 在 /opsx:apply 期间卡住了？你可以退一步探索子问题，然后返回。

诚实的权衡 ​

你获得的： 探索在最便宜的时机捕捉错误的方向，此时任何工件都尚未存在。在不熟悉的代码中，它尤其强大，因为 AI 阅读和总结系统的能力可以节省你一下午的挖掘时间。

你付出的： 一点耐心。探索是一种对话，所以它比发出 /opsx:propose 并碰运气要慢。对于你已经真正理解的工作，这一步完全是开销，你应该跳过它。

经验法则：任务越模糊，探索的收益越大。任务越清晰，你越可以直接跳到提议阶段。

下一步 ​