to-spec：别让共识只留在对话里

上期我们用 grill-me 把“改造首页”这件事拷问了一遍，最后它列出一份共识小结：博客当主角、订阅放两处、大图锁最新长文。问题是，这份共识只存在于那段对话里 - 你换个会话、或者第二天再开一个 agent，它对这些一无所知，你又得从头解释一遍。对齐好的东西不落下来，等于没对齐。

这篇接着上期，聊 Matt Pocock 仓库里的另一个 skill - to-spec。它把刚聊清楚的东西，写成一份 spec，发到你的任务系统。我会聊聊它做什么、原理是什么、用它之前要配什么，再接着“改造首页”真跑一遍。这篇偏开发一点，面向用 AI 做真实项目的人。期望对大家有帮助。

它做什么：不问你，只写下来

to-spec 和 grill-me 正好相反。grill-me 是问你 - 一个问题一个问题把需求搞清楚；to-spec 不问，它假设对齐已经做完了，只负责把已知的东西合成成一份 spec，也就是规范文档，你可能管它叫 PRD。

它先扫一遍代码库，用你项目自己的术语写，写完发到任务系统。如果你用 GitHub，那就是创建一个 issue，再打上一个 ready-for-agent 标签 - 意思是：这份东西，可以交给 agent 直接实现了。

值得一提的是它的归类。Matt 把 grill-me 放在 productivity 目录，把 to-spec 放在了 engineering 目录 - 这是一个更偏工程开发的 skill。

spec 里装了什么

一份 to-spec 的 spec，是固定几段：问题是什么、方案是什么、一长串 user story 穷尽这个功能要支持的行为、已经定下的实现决策、测试决策，还有明确的“不做什么”。

拿 user story 举个例。改造首页里有一条共识是：大图别顶早读日报。写进 spec，它就成了一条明确、能验收的行为 - 作为作者，当我只发了早读、没发长文，首页大图要保持上一篇长文，不被日报顶掉。它不是一句含糊的“首页要好看”，而是一条能拿去测、能对着验收的话。

还有一条设计值得说：它不写具体文件路径、不贴代码片段。因为这些东西过时最快 - 今天写死一个路径，明天一重构就错了。spec 记的是决策，不是实现细节。

最见功夫：接缝和深模块

真正让它不只是“把话整理一遍”的，是写 spec 之前那一步 - 它会先想：这个功能，要在哪测？

它把这个位置叫接缝，也就是 seam。举个对照：假设有一段逻辑，散在界面组件里、和渲染缠在一起 - 这种情况你没法单独测它，要测就得把整个页面渲出来。反过来，如果把这段逻辑抽成一个小小的、独立的函数，输入是数据、输出是该展示什么 - 这就是一个接缝，也是一个“深模块”：接口很小，后面藏着全部逻辑，你对着这一个函数就能测。

to-spec 的规矩是：接缝优先用已有的、用最高的那个，理想情况下整条改动只留一个。为什么这在 agent 时代格外重要？因为好接口给测试一个耐久的靶子 - 接口稳住了，底下代码不管被 agent 改写多少遍，测试都不用动。这正是让 agent 大胆改代码、又不容易出事的关键。

用它之前：一次性配置

不过 to-spec 真要跑起来，还有一个一次性的前置。它要把 spec 发到你的任务系统，可它怎么知道你用的是 GitHub 还是别的、issue 该怎么建？这得先配一次。

配置也是仓库里的一个 skill，叫 setup-matt-pocock-skills。跑一次 /setup-matt-pocock-skills，它先扫一遍你的仓库，然后就几个决策，每个都先给推荐答案。我这个仓库的远端指向 GitHub，它就建议用 GitHub、走 gh 命令 - 我顺手验了一下 gh 能不能用，能列出、也能创建 issue，那就选 GitHub。triage 那个 skill 我没装，标签这一节它直接跳过；不是 monorepo，文档布局默认单上下文。最后它把配置写进 docs/agents/，还在 CLAUDE.md 里加一段说明。前面说的 ready-for-agent 标签、还有“发到任务系统”，to-spec 之所以知道该怎么做，靠的就是这份配置。这是跑一次的事。

装它、用它

装 to-spec 还是一行命令：

npx skills add mattpocock/skills --skill to-spec

用的时候，在对话里输入 /to-spec。和 grill-me 一样，它不会自己冒出来，得你对齐完、主动叫它。

我让它把改造首页写成 spec

还是接着上期那个“改造首页”。共识已经聊完了，我输入 /to-spec。

它没问我问题，而是先去翻代码。翻完发现两件事：首页现在把“选哪篇当大图、列哪几篇”这些逻辑，直接写在页面组件里、和渲染混在一起，没法单独测；而且整个仓库，一个测试都没有。

刚才讲的接缝，这下用上了。它提议：抽出一个纯函数，就叫 getHomepageContent，把“首页展示什么”全收进这一个接缝，页面只负责渲染它的返回值。我确认。然后它才开始写 spec：问题、方案、一串 user story，里头就有那条“大图要排除早读日报”；到测试这段，它写得很具体 - 测这个函数，喂它一组“最新几篇全是早读、更早一篇是长文”的输入，大图必须是那篇长文。

上期还只是聊天里的一份共识，现在成了任务系统上一份带验收标准、能交给 agent 直接实现的 spec。中间我一句都没有重新解释。

它在工程链里的位置

to-spec 不是孤立的，它是 Matt 一整条工程链里的一环：

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

先用 grill 把想法拷问清楚，to-spec 写成 spec，再用 to-tickets 把 spec 拆成一个个工单，交给 agent 实现、评审。所以下一篇，我打算接着这份 spec，聊 to-tickets - 怎么把它拆成 agent 能一个个接着做的工单。

你和 AI 对齐好的东西，别只留在脑子里、留在一段会话里。写成 spec、落到任务系统，它才不会随着上下文一起蒸发。

• to-spec 源码：https://github.com/mattpocock/skills/tree/main/skills/engineering/to-spec
• 上一篇：grill-me：让 AI 反过来拷问你