转为规范

它的作用¶

to-spec 会将你刚刚进行的对话转化为一个 规格，并将其作为单个问题发布到你的问题跟踪器中。

它不会盘问你。当你使用它时，决定已经做出。因此，它会综合已知信息（来自对话线程、代码库、你的 GLOSSARY.md 和 ADR），而不会开启新一轮提问。规格记录你已经做出的决定。它不是做出新决定的地方。

何时使用¶

你通过输入 /to-spec 来调用它；代理 不会自行使用它。

当构建太大、无法在一个代理 会话 中完成，必须拆分到多个会话时，使用它。这就是全部触发条件：

前置条件¶

to-spec 会将规格发布为一个问题，因此 setup-matt-pocock-skills 必须先为当前仓库配置一个跟踪器和分诊标签词汇表。两种跟踪器都可以：像 GitHub 这样的真实跟踪器，或 .scratch/ 下的本地 Markdown 文件，后者无需额外配置即可工作。

规格是决策记录¶

规格之所以存在，是因为上下文窗口会结束。你在 拷问 期间确定了许多事情：解决方案的形态、你争论后做出的选择，以及你刻意拒绝的内容。所有这些都存在于你即将清除的一段对话中。规格会保留它。

因此，规格不验证或决定任何事。它用项目自身的词汇记录你已经做出的决定，这样新的会话就能接手工作，而无需你再解释一遍。如果规格陈述了你从未说过的内容，那就是缺陷。

接缝先于描述¶

在写入任何内容之前，to-spec 会勾勒出功能将被测试的 接缝，并与你确认。它优先选择现有接缝而非新建接缝，并尽可能选择最高的接缝。对于一次变更，理想的接缝数量是一个。

其他技能之后会使用这些已同意的接缝。tdd 只在你事先同意的接缝上工作。code-review 会对照规格审查差异，因此任何未经同意的接缝都会作为审查发现出现。这两个关联都通过本文档实现。这就是为什么你应该在这里认真对待接缝讨论，而不是留到实现阶段。

常见问题¶

/to-prd 去哪了？ 它就是这项技能，在 v1.1 中重命名了。“规格”现在是全程使用的唯一术语，旧的 to-prd slug 已不再有效，因此请在新名称下重新安装。旧词汇被 规格 和 工单 这一对术语取代。规格是目的地，也是固定它的决策。工单 是到达那里的步骤。如果你改变方向，删除未完成的工单并保留规格。

为什么规格会获得 ready-for-agent 标签？我不想让代理基于它实现。 该标签表示“无需进一步分诊”：文档已足够完整，可供代理据此工作。它标记的是一个输入，而不是一张工作单。但轮询 ready-for-agent 的 AFK 代理看不到这种区别。它们会试图在一次运行中构建整个规格，而不是领取工单切片。这是该技能被报告最多的问题。在情况改变之前，请在你的 AFK 代理提示中明确排除父规格，或在 /to-tickets 运行后移除该标签。

为什么不直接从拷问跳到 /to-tickets，而跳过规格？ 通常你应该这样做。规格只在多会话工作中才值得这一步。它的价值在于工单是一次性的，而规格不是。每个工单都按一个全新上下文窗口的大小来划分，然后被删除或关闭，而规格保留下来，作为记录其背后推理的唯一地方。对于单会话变更，这不会给你带来任何好处，反而要为一个额外的综合步骤付出代价，而 模型 可能会在其中漂移。从拷问直接到 /implement。

我刚完成一张 wayfinder 地图。我该给它什么？ 给它主地图问题，/to-spec #<map_issue>，而不是各个决策工单。wayfinder 产生的是分散在地图上的决策，而不是交付物。to-spec 将它们合并成一份你可以据此构建的文档。如果你把地图直接送入 /implement，就会丢失这一步。

规格是给我审查的，还是只给代理用的？ 主要是给代理用的，读起来也确实如此：完整、密集，并且充满引用。阅读接缝和范围外部分。在这两个地方，一个错误决策现在发现的成本最低，之后发现的成本最高。人们确实会抱怨阅读全部内容，而且没有摘要模式。但如果规格让你感到意外，说明拷问太浅了；规格并不是太长。

一旦工单开始，我是让规格保持冻结，还是让代理重写它？ 没有任何机制让它保持同步。实际上，它是你当时所知内容的快照，而实现第一次教会你某些东西时，它就会过时。在工作发布后，把它当作一次性内容。你的 GLOSSARY.md 和 ADR 才是旨在长期保留的文件。如果你在实现过程中学到了应该长期保留的东西，请把它放在那里，而不是放在被编辑过的规格中。

我的工作是一次重构或模块边界调整，而不是新功能。这个模板适合吗？ 不太适合，这是已知限制。模板大量依赖用户故事，而用户故事并不适合架构工作。你最终会围绕那些本质上关于接口和不变量的决策，写出没人要求的故事。请改用 implementation-decisions 和 testing-decisions 部分。通过 grill-with-docs 将持久的架构决策记录为 ADR，而不是写在规格说明中。

它会检查 tracker 中的相关工作，或引用它遵循的 ADR 吗？ 两者都不会。它会读取并遵循其所触及领域的 ADR，但不会链接它们。它也不会在写入前搜索 tracker 中重叠的 issue，因此规格说明可能重复别人已经提交的工作，而且没有任何警告。如果该领域比较繁忙，请先自己搜索 tracker。

/to-tickets 无法读取我的规格说明：它一直被截断。 tracker issue 可能无法完整返回非常大的规格说明，也没有本地副本可替代使用。要修复这个问题，不要在 /to-spec 和 /to-tickets 之间执行 clear 或 compact。在同一个窗口中运行它们，这样 /to-tickets 就无需再次获取规格说明。

如果它正在正常工作¶

• 它开始写入，而不是向你提出新一轮问题。
• 它在写入前向你展示接缝，并尽可能少地提出建议。
• 它使用你项目中的名词，而不是通用的产品管理套话。
• 你记得自己做出了其中的每一个决策。它没有为了填充某个部分而编造任何东西。
• 范围外部分列出了真实事项。你拒绝的事项通常是一页中最有用的内容。

它适合在哪里¶

to-spec 是主构建链中的一个步骤，但只适用于其中的多会话分支：

grill-with-docs → to-spec → to-tickets → implement → code-review → retro

上游，grill-with-docs 做出本技能仅记录的决策，而一份完成的 wayfinder 地图会在此处接入该链。下游，to-tickets 将规格说明切分为曳光弹工单，供 implement 构建。当你不确定哪个技能或流程适合时，ask-matt 会为你路由。