第三篇 · 做出东西 / 第 8 章

从规格到上线

规格写完了，为什么还是做不完？ 因为从一份文档到别人能打开的网址，中间还隔着拆票、实现、审查和上线。

预计阅读

30 分钟

前置

第 7 章

关键词

工单、实现、审查、上线

读完这一章，你能

• 把一份规格拆成 5 张纵向工单，每张都写得出“做完的可观察结果”；
• 一次只实现一张工单，并换一个干净会话对照规格和验收清单做审查；
• 按上线前检查清单，把项目放到一个别人能打开的网址上。

午饭登记 · 当前状态：有 spec，还没拆票

先做判断：你要不要拆票

在讲怎么做之前，先说一件更省事的事：你可能根本不需要做这一步。

拆票，就是把一份规格拆成若干张工单（ticket）。 一张工单是一件可以单独完成、单独验收的小活。

这条对你尤其重要。因为按第 1 章的建议， 你的第一个项目应该小到根本用不上拆票—— 一个页面、一件事，一轮对话就做完了。

那什么时候才该拆？用一个很实际的判断标准：

换句话说：拆票的本质，是把一件“一次装不下”的活， 切成若干个“一次装得下”的小活。它是为上下文窗口服务的，不是为项目管理服务的。

阶段五 · 拆票

这一步对应 /to-tickets。它把规格拆成一组工单。

关键不在于“拆”，而在于按什么方向拆。 官方的答案是：每张工单必须是曳光弹（tracer bullet）。

官方给的拆解规则一共五条，非常具体：

1. 每一片必须纵向，不能横向

   一条窄但完整的路径穿过每一层——界面、接口、数据库、测试。 是纵向，不是某一层的一片。

2. 做完一片，必须能单独演示或验证

   这是判断你有没有切对的最好标准： “这一片做完，我能演示什么？”答不出来，就说明你切横了。

3. 每一片的大小，要刚好装进一个全新的上下文窗口

   为什么？因为来捡这张工单的，是一个从没见过你规格的新会话。 它得能一口气做完。

4. 该重构的先重构，排在最前面

   官方借了一句特别好记的话：“先把改动变容易，再做那个容易的改动。” 这个动作有个正式的名字叫 prefactoring（预先重构）—— 它不是“顺便整理一下代码”，而是为了后面那几张工单能顺利做，先付的一笔定金。

5. 工单正文里，不许写文件路径和行号

   理由和规格里那条一样：路径会腐烂，行为不会。 写“改 src/db/schema.ts:42”，几天后那行号就不是那个意思了； 写“订单表增加一个状态字段”，永远是对的。

   唯一的例外是原型阶段已经产出的代码片段—— 那种本来就该直接搬过去用。

午饭登记怎么拆：5 张纵向工单

把第 7 章那份 spec.md 拿出来，按“每张都能单独演示”的标准切，得到 5 张票。 注意每张票的“做完的可观察结果”都是你能亲手做一遍的动作。

为什么不能按层切

你可能会想：那我按“先做数据库、再做接口、再做界面”的顺序拆，不是很自然吗？

这正是最典型的错误切法。官方给了一个真实案例来说明代价：

为什么按层切会这么惨，看图就明白了：

唯一的例外

有一种改动天然没法纵向切：一次机械的全局替换（比如改一个列名）， 它的影响范围会扇出到整个代码库，一次性打断上千个调用点—— 没有任何纵向切片能让代码保持可运行。

这种情况官方给了一个专门的名字和打法，叫 expand–contract（先扩后收）：

1. Expand（扩）

   把新写法加在旧写法旁边。什么都不坏。

2. Migrate（迁）

   调用点分批迁移。因为旧写法还在，每一批做完代码都还是好的。

3. Contract（收）

   确认没有调用者了，再删掉旧写法。

这个模式零基础的你可能一时用不上，但它的思路值得记住： 当一件事没法一步做完，就先让新旧并存，再一点点搬过去。

阻塞关系与并行

每张工单还要声明一件事：它被谁挡着（blocking edges）。

这件事的价值远超你的想象。因为有了这张依赖图，就自然出现了两个东西：

阶段六 · 实现

这一步对应 /implement。它的定位非常清楚，清楚得近乎偏执。

它从不重开计划。 没有访谈、没有澄清轮、不会提议换一个做法。

上游谈定的一切就是它的输入，这个技能的全部工作，就是把它变成一个提交。

这正是它区别于“在新会话里说一句『把这个做了』”的地方—— 后者会很乐意在动手的同时，顺手把这件事重新设计一遍。

一次运行，五个节拍

1. 读懂这张工单，弄清要在哪些接缝（seam）上测试。

   接缝就是你从外面能观察、能挂测试的那个边界，比如“提交表单”这个动作。 它不关心表单内部怎么实现，只关心“点提交之后发生了什么”。

2. 在预先约定好的接缝上驱动测试，一次一个“红—绿”循环
3. 频繁做类型检查，边做边跑单个测试文件
4. 结尾跑一次完整的测试套件
5. 跑审查，然后提交到当前分支

进阶：红—绿循环到底在做什么 以后再看

“红—绿”到底是哪两件事

红 = 先写一个会失败的测试。这时功能还没做，测试跑起来当然是红的—— 你要亲眼看到它红一次，才能确认这个测试真的在测东西。

绿 = 只写刚好让它通过的最少代码。不多写一行。 多写的那些没有测试盯着，等于没验过。

然后是最反直觉的一点：这个循环里没有第三个字。

大多数讲测试驱动开发的材料都写作“红—绿—重构”，三步一体。 这套方法偏偏把“重构”拿掉了——整理结构归 阶段七 · 审查（含验收）去管。

理由是：一边修东西、一边改结构，这两件事会互相掩盖。 测试红了，你分不清是功能没做对，还是刚才那次结构调整弄坏了什么。

完整的技能档案（包括官方点名的三种测试坏味道）见 技能档案 · 四个底层原语。

一次调用，只做一张工单。做完就开一个新会话做下一张—— 因为每张工单都是自包含的，上一张的对话是可以扔掉的。

它最弱的一个关节，官方自己承认

两个会让你困惑的行为

阶段七 · 审查（含验收）

最后一步不是“让 AI 说没问题”，而是先验收，再审查。 验收看行为，审查看代码与规格；两件事都做完，这一阶段才算通过。

先验收：把清单亲手点一遍

拿出 spec.md 里的用户故事，一条一条点。 每条只回答“看到 / 没看到”，不回答“应该没问题”。

再审查：换一个干净的眼睛

验收通过不代表代码没问题。你需要一个没有参与实现的新会话， 拿规格和清单来挑错——同一个上下文审自己，只是确认偏误。

进阶：双轴审查、子代理与 12 个坏味道 以后再看

它为什么要分两个轴

它审查的不是“这次改动好不好”，而是同时沿两个轴审查：

为什么非要分开？因为一份改动完全可能通过一个轴、却挂掉另一个轴：

标准过，规格挂

它遵守了每一条编码规范，但实现的是错的东西。

→ 代码很漂亮，功能不是你要的。

规格过，标准挂

它完全按需求做了，但破坏了项目的约定。

→ 功能对了，代码库被弄乱了。

这一句是整章的设计精髓

“分开报告，是为了阻止一个轴掩盖另一个轴。”

正因如此，它明令不许合并、不许重新排序， 结尾只给“每个轴各自最糟的问题”，拒绝跨轴选出一个总冠军。

这里的子代理（subagent），是主会话派出去、带自己独立上下文的另一个 AI 实例。 它看不到主会话的推理，所以能减少“顺着自己刚才的思路找理由”的偏差。

标准轴的兜底：12 个坏味道

就算你的项目什么文档都没写，标准轴也不会空转——它会用一份通用清单兜底， 来自 Fowler 的《重构》，12 个“代码坏味道”。其中几个零基础也能看懂：

坏味道	什么感觉
神秘的名字	名字看不出它是干嘛的
重复的代码	同一段逻辑出现在好几个地方
依恋情结	一个函数老是伸手去掏别人的数据
数据泥团	那几个字段总是手拉手一起出现
夸夸其谈的通用性	为“以后可能要用”加了抽象，可现在根本用不上
中间人	一个类基本上只是在往下转发

两条约束很重要

一是“仓库说了算”：你项目自己的规范永远优先。 如果规范里明说了某种写法，就不该被坏味道清单标记。

二是“永远是判断题”：每个坏味道都是带标签的启发式—— 报告写的是“可能有依恋情结”，绝不是硬性错误。

还有两条来自实践者的经验，值得一并知道：

• 要换一个干净的会话来审。 最好的说法来自一位读者：“同一个上下文审自己不是审查， 是用一个斜杠命令包装起来的确认偏误。”
• 不要指望它“审到干净”。 每次跑都能发现新问题，因为修复本身会制造新的表面。 把一次审查当成线索清单，处理掉背后有明确规则的， 然后就停——它不会收敛。

一个已知的失控情况

它会派两个子代理去审。而那两个子代理没有被禁止再次调用审查技能， 于是它们可能各自再派一批……有报告记录到一次跑出了 50 多个代理。

如果你让它无人值守地跑，盯一下代理数量。

一个会把你搞糊涂的撞名

Claude Code 自带一个叫 /code-review 的命令。 它和这一节讲的不是同一个东西，做的事也不一样：

	Claude Code 自带的	这个库的
看什么	这次改动（diff）里有没有 bug	规格符合性 + 仓库规范
问的问题	“这段代码写错了吗”	“做的是不是当初要的那件事”

装了这个库之后，两个同名命令会打架。谁赢，取决于你当初怎么装的 （见上一章的装法）：

路线 A · 插件装的

所有技能被挂在 mattpocock-skills: 前缀下面。 内建的那个在无前缀的短名字上就够不着了，冲突不明显。

路线 B · skills.sh 装的

本地文件赢。也就是这个库的 /code-review 会遮蔽掉内建的那个。

有个更干脆的解法

有实践者干脆把 Claude Code 的内建技能整个删掉—— 冲突就不存在了，而且还能省下相当一块上下文 （内建技能也占你那 15 万 token 的工作台）。

如果你只是偶尔用，不折腾也行。但至少要知道有两个同名命令， 别在看到一个只挑 bug 的报告时，以为是自己装错了。

最小上线：放到别人能打开的网址上

审查通过、验收清单全过，最后一步才是上线。 上线不是新的阶段，它是阶段七 · 审查（含验收）通过后的动作。 这一节只讲最小可用版本，不讲运维。

先选托管方式：只看两个问题

午饭登记有后端和数据库，属于第二种。选平台时只看四件事： 能不能跑你的程序、有没有数据库、能不能配环境变量、出错时能不能看日志。 产品名不重要；具体怎么比，见 进阶：架构与选型。

域名和 HTTPS，各一段人话

域名（domain）是网址里你买下来的那一段，比如 lunch.example.com。 它通过 DNS（把名字翻译成服务器地址的系统）指向你的服务器。 刚开始用平台送的免费子域名就行，等真的有人天天用了，再买自己的域名。

HTTPS 是浏览器地址栏里的小锁：它把用户和网站之间的内容加密， 别人中途截获也看不懂。现在的托管平台基本都能一键开启； 找不到就搜平台的“HTTPS / 证书”设置。没有小锁，不要让人填真实姓名。

上线前检查清单

密钥是 API Key（调用服务时用的通行证）、数据库密码这类不能公开的字符串； 环境变量是放在服务器上、不写进代码的配置值，比如数据库地址和密码。

上下文纪律

整套流水线有一条硬性约束，违反了会出真问题。

然后，阶段之间是相反的：

官方还给了一个量的感觉：模型保持推理锐利的窗口， 在目前最强的模型上大约是 15 万 token。 如果在拆完票之前就接近这个量，不要在退化里硬撑， 找个阶段边界处理一下再继续。

这些其实就是第 4 章讲的工作台和变笨区， 只不过在这里被固化成了流程的一部分。

技能的两层结构 以后再看

最后讲一个设计上的巧妙之处，它保证了你不会“点一个按钮触发一串黑箱”。

所有技能按谁能触发它分成两类：

还有一个反直觉的推论：实现技能是用户调用型的， 也就是说别的技能也调不动它。 所以当文档里说“然后每张工单跑一次实现”，那是写给你看的指令，不是 agent 会自己去做的事。

三句话带走

1. 拆票按纵向：每张票穿过页面、接口、数据、验收，做完就能单独演示。
2. 实现一次一张票、开新会话；做完换一个干净会话，先验收再审查。
3. 上线不是新阶段，是阶段七 · 审查（含验收）通过后的动作：按清单查密钥、环境变量、备份和日志。

自测：三个问题

一张“先做数据库表”的工单为什么不合格？

它是横向切片，只碰数据层，做完不能单独演示，验收标准还得伸手到别的工单。 应该改成“提交一条午饭记录，并在当天列表里看到它”——这条路径同时穿过页面、接口和数据。

实现完成后，为什么要换一个新会话做审查？

同一个上下文里，AI 会顺着自己刚才的思路找理由，这是确认偏误。 新会话没有参与实现，只拿规格和验收清单来对照，才更容易发现“做错了但做得很好”的情况。

上线前最低要检查哪三件事？

密钥不在前端、验收清单全过、错误能看到（日志里有记录）。 如果项目有数据库，还要确认有备份；这些检查每一条都能在五分钟内做完。

动手 10 分钟

把午饭登记的 spec.md 拆成 5 张工单，每张只写两行：

1. 做什么：一句话。
2. 做完后我能看到什么：一句能亲手验证的话。

写完检查一遍：有没有哪张票的验收要等下一张票？ 有就说明切横了，重切；没有，就挑票 1，按它的验收标准做一次最小实现。

如果你看到 X，大概率是 Y

• 先建数据库表、再写接口、最后做页面 → 横向切片，返工。改成一条能单独演示的纵向路径。
• 让一个会话连着做完 5 张票 → 上下文变笨，后一张的改动会覆盖前一张。一次一张，开新会话。
• 在同一个项目目录并行开几个会话 → 它们共享索引和 HEAD，提交会打架。要并行就开独立目录。
• 审查时只说“帮我看看有没有问题” → 没给规格和验收清单，它只能挑风格。把它当审查员，不是当保洁。
• 上线前把密钥写进前端代码 → 打开网页源代码就能看到。密钥只放服务器环境变量。
• 部署完就发链接 → 没看日志，出错只能猜。先自己走一遍，再看日志确认。