Lesson 0011 · Engineering · 只有人能启动（user-invoked）· 流程课

implement：主流程的施工段，从票到 commit

想象这个场景：需求文档（spec）已经发到了工单系统，to-tickets 把活拆成了几张 端到端的工作票，每张票都标清楚了谁挡着谁。你挑了一张没有任何挡路者的票， 新开一个干净的会话，把这张票带进去，敲下 /implement。 接下来发生的事，全部写在一个只有五行正文的文件里：照着票把活干完、能用 /tdd 就用 /tdd、按固定节奏跑验证、收尾跑 /code-review、把成果 commit 到当前分支。 这节课把这五行逐句拆开：每一句在调用谁、会改仓库里的什么、 上游必须给它准备好什么、行为不对时该去改哪个文件的哪一段。

1. 它在整个系统里站在哪

0001 把 22 个已发布 skill 分成三层：配置层（跑一次性的初始设置）、编排层 （你手动启动的完整流程，内部拼装纪律层的基本功）、纪律层（被反复调用的基本功）。 implement 在编排层，而且是主流程（main flow： 一个想法从进门到交付的那条默认路径）上的施工段。 它的人读文档把位置写得很死：主链是 grill-with-docs → to-spec → to-tickets → implement → code-review， implement 是「靠近末尾的构建步骤，就在 review 之前」。

文档里还有一句定性格言，值得背下来：「It is the hands, not the head」 ——它是手，不是脑。规格（spec）已经定稿、接缝（seam，第 5 节细讲）已经约好， implement 负责执行那个计划，而不是重新打开它。 「决定做什么」这件事在上游已经想完了；implement 发现自己在想「到底该不该做这个」， 说明上游欠了债，该退回去补，而不是在施工段现场决策。

同时它也是 0001 讲过的设计规矩「入口薄、纪律厚」的教科书例子： implement 的正文故意只有五行（和 grill-me、 grill-with-docs 同一类写法），真正厚的纪律全部住在它调用的 tdd 和 code-review 里。想改行为时， 先打开被它调用的那个厚文件——这条原则会贯穿本课第 11 节的微调表。

地图：0001 系统地图（三层分法、主流程、「入口薄、纪律厚」）· 定位置：docs/engineering/implement.md（主链引文、「hands not the head」）· 上游的一课：0003 grilling

2. 调用方式：为什么只能你来敲

implement 是 user-invoked 的：只有人能启动它，AI 不会、也不被允许自己伸手。 这不是一句口头约定，而是两道写在文件里的锁：

• 第一道锁在 SKILL.md 的 frontmatter（文件头部那段元数据）： disable-model-invocation: true——模型被禁止把 implement 当作 「看着合适就自己上」的候选。
• 第二道锁在同目录的 agents/openai.yaml： policy.allow_implicit_invocation: false——不允许隐式调用， 也就是不允许 agent 在没有明确指令的情况下替你启动它。

人读文档把话说得很直白：「You invoke this by typing /implement — the agent won't reach for it on its own.」（你敲 /implement 来启动它； agent 不会自己去够它。）

典型的启动姿势（来自 ask-matt 的主流程描述）：多会话构建时，每张票 各开一个新会话，把那张票带进去再敲 /implement； 需求小到一张票装得下时，也可以在 grill / spec 之后直接在同一个会话里敲。 两种姿势的区别只在上下文，不在 skill 本身——五行正文一视同仁。

两道锁：skills/engineering/implement/SKILL.md 的 frontmatter · skills/engineering/implement/agents/openai.yaml · 「agent won't reach for it」：docs/engineering/implement.md 的 When to reach for it 一节 · 启动姿势：ask-matt/SKILL.md 主流程第 3 步

3. 五行正文，逐句解剖

implement/SKILL.md 去掉 frontmatter 之后，全部正文就是五行。 它短到可以整段背下来，但每一行都挂着一套厚纪律。逐句解剖：

两个读原文时才注意得到的细节：

• 第 2 行的「where possible」是原词，不是本课加的。 它留了一个例外的口子——确实存在没有可测接缝的机械改动——但整套系统的默认姿态是 test-first（测试先行）：ask-matt 描述 implement 时说的是「driving /tdd internally — one red-green slice at a time」（内部驱动 tdd，一次一个红绿切片）。 把例外当常态，等于把第 2 行删了。
• 五行之外什么都没有：没有分支策略、没有发 PR、没有改写工单系统、 没有面试、没有报告。你想要其中任何一样，都得去别处找（第 8、11 节会逐项交代）。 读薄入口的第一课就是：它没写的事，不要默认它会做。

五行原文：skills/engineering/implement/SKILL.md（全文 15 行，含 frontmatter）· 「one red-green slice at a time」：ask-matt/SKILL.md 主流程第 3 步

4. 开工条件：什么算可以 implement 的输入

第 1 行说输入是「a spec or set of tickets」。在整条系统里，能合法喂给 implement 的东西有四条来路，外加一个例外：

反过来说，下面几种状态不该敲 /implement：

• 手里只有一个模糊想法——先走 /grill-with-docs 把想法问清楚（0003 的面试流程）。
• 有 wayfinder 的决策地图但没折叠成 spec——ask-matt 明说，直接 implement 会「throws the linked detail away」（把地图里链接好的细节扔掉）。
• spec 里没约定接缝——implement 的第 2 行要求接缝是 pre-agreed 的；没有接缝可落，测试就没地方写（下一节细讲）。
• 票还被人挡着——frontier 之外的票，做了也白做，依赖它的、它依赖的都还没就位。

四种输入：to-tickets/SKILL.md（frontier、blocking edges、结尾一行）· ask-matt/SKILL.md（triage 的 on-ramp、wayfinder 的交接）· 跳过 tickets 的情形：0001 系统地图的弹性组合一节

5. 接缝从哪来：pre-agreed 的含义

第 2 行的后半句「at pre-agreed seams」是整个 implement 的承重墙。先回顾定义 （0005 已经精确定义过）：seam（接缝）是不用改那处代码、就能改变行为的位置， 也就是模块接口所在的位置——测试就落在接缝上，永远不捅进内部。 「pre-agreed」（事先约好的）意味着：接缝不是 implement 在施工中途发明的， 而是上游定好、被带进来的。

这条约定链跨了三个 skill，值得逐环看：

1. to-spec 画接缝草图。它的第 2 步：在写 spec 正文之前， 先勾出要在这个功能上测试的接缝——优先复用已有接缝、能用多高的接缝就用多高的 （越靠外的接口越耐用）、新接缝越少越好（理想数量是一个）， 然后和你确认这些接缝符合预期。接缝从此就是 spec 的一部分。
2. tdd 守住接缝。它的纪律写得很硬：「Test only at pre-agreed seams」 ——写任何测试之前，先把要测的接缝写下来并跟你确认； 没有确认过的接缝，一个测试也不写。接缝还决定了测试投入的落点： 你不可能什么都测，事先约接缝就是让测试火力落在关键路径和复杂逻辑上。
3. implement 只管使用。人读文档的原话：「It doesn't invent seams mid-build; it uses the ones already picked.」（它不在构建中途发明接缝； 它使用已经选好的那些。）并且解释了为什么这能让实现保持诚实： 测试瞄准的是耐用的东西，所以接缝底下的代码可以挪动， 而测试不用跟着挪。

画接缝：to-spec/SKILL.md 第 2 步 · 守接缝：tdd/SKILL.md 的 Seams 一节 · 「doesn't invent seams mid-build」：docs/engineering/implement.md 的 Pre-agreed seams 一节 · 词汇出处：Lesson 0005 codebase-design

6. 内部循环：prose 调用 tdd

第 2 行的「Use /tdd」是一个 prose 调用（散文调用）： skill 之间的依赖用一句自然语言表达（「Run the /tdd skill」这类写法）， 而不是用文件路径深链——0001 讲过这条仓库级的依赖规则。 它能成立，是因为 tdd 是 model-invoked 的：agent 读到这句话，就会把 tdd/SKILL.md 的全文加载进来，按它的纪律干活。 所以 implement 在施工期的真实行为，= 五行正文 + tdd 全文。 后者才是「厚」的部分。

implement 从 tdd 那里继承来的施工纪律，一次循环长这样：

一个红绿循环（red-green cycle）
  │
  ├─ Red：在约定好的那条接缝上，先写一个会失败的测试
  │        （测试通过公共接口观察行为，不碰内部实现）
  │
  ├─ Green：只写刚好够让它通过的最小实现
  │        （不预判未来的测试，不加投机性的功能）
  │
  └─ 下一个切片（slice）：一条接缝、一个测试、一个最小实现，循环往复
           每个测试都是一颗曳光弹（tracer bullet），根据上一轮学到的东西调整

• Red before green（先红后绿）。先写失败的测试，再写刚好够过的实现。 tdd 明文禁止反过来，也禁止「顺手把将来的功能先写了」。
• One slice at a time（一次一个切片）。每个循环只碰一条接缝、 一个测试、一个最小实现。tdd 把「先写完全部测试再写全部实现」列为反模式 （horizontal slicing，水平切片：按层切，测的全是想象中的形状）， 要求换成垂直切片（vertical slice：一刀穿透所有层，端到端可验证）。
• Refactoring is not part of the loop（重构不属于红绿循环）。 想重构？忍住，那是 review 阶段的事——tdd 明文把重构指给了 code-review。这就是为什么 implement 的收尾必须是 review（第 8 节）： 施工期欠下的整理账，在那里统一清算。
• 对齐项目语言。tdd 要求探索代码库时先读 CONTEXT.md （如果存在），让测试命名和接口用词跟项目的领域语言一致，并尊重要动的区域里的 ADR（架构决策记录）。也就是说 implement 会读这两个文件， 但它自己不写（第 11 节的副作用表会用到这一点）。

tdd 还有两个 sibling 文件，implement 间接继承：tests.md （好测试与坏测试的对照样例——好测试测「用户能用有效购物车结账」这种行为， 坏测试测「checkout 调用了 paymentService.process」这种内部细节）和 mocking.md（只在系统边界 mock：外部 API、数据库、时间、文件系统； 不 mock 自己的类和内部协作者）。这些纪律的全文都在 tdd 目录里， 所以「测试写得不对」永远去改那边，而不是改 implement 的第 2 行—— 第 11 节的微调表还会回到这个分工。

继承的纪律：tdd/SKILL.md（Rules of the loop、Seams、Anti-patterns）· 样例与 mock 边界：tdd/tests.md、tdd/mocking.md · prose 调用规则：0001 系统地图的依赖规则一节

7. 验证节奏：typecheck 常跑、单文件常跑、全量一次

第 3 行是 implement 正文里唯一一条不转包给别人的规定： 「Run typechecking regularly, single test files regularly, and the full test suite once at the end.」三档验证，各跑各的频率：

人读文档用一句话概括了这个设计意图：「it keeps the loop tight」——让循环保持紧。 施工期的每一秒都在红绿循环里，反馈越便宜，循环转得越快； 全量套件跑得慢，塞进循环里只会把循环拖垮，所以它只在收尾出现一次。

两个作者级的读法：

• 「regularly」没有给数字。它不是「每 N 分钟」或「每个 commit」， 而是把频率判断留给了执行中的 agent——节奏感是纪律，不是公式。 如果你观察到 agent 整个下午一次类型检查都没跑、或者每改一行就全量跑一遍， 要拧的就是这一行原文（第 11 节）。
• 全量「once at the end」的位置有讲究：它在第 4 行的 code-review 之前。 也就是说 review 看到的这堆改动，是已经通过过一次全量验收的改动—— review 的职责是双轴审查（下一节），不是替你抓红灯。

三档原文：implement/SKILL.md 第 3 行 · 「keeps the loop tight」：docs/engineering/implement.md 的 Pre-agreed seams 一节末尾

8. 收尾：code-review 双轴审查，然后 commit

第 4、5 两行是 implement 的闭幕式，顺序固定：先审查，后提交。 ask-matt 的描述把这个顺序钉死了：implement「closes out by running /code-review, a two-axis review (Standards + Spec) of the diff, before committing」 （收尾时运行 code-review——对 diff 做 Standards + Spec 双轴审查——然后再提交）。

8.1 第 4 行：code-review 审什么

code-review 也是 model-invoked 的，所以第 4 行又是一个 prose 调用。 它对「当前分支上的这堆改动相对一个固定起点的 diff」做两条互相独立的轴：

• Standards 轴（规范轴）：这堆代码遵不遵守本仓库写下来的编码标准？ 仓库没写标准的部分，用一套固定的 Fowler 坏味基线兜底（重复代码、霰弹式修改、 投机性泛化等），而且基线永远是「判断题」不是「硬违规」。
• Spec 轴（需求轴）：这堆代码忠不忠实于发起它的那张票 / 那份 spec？ 它会抓三种东西：要求了但没做全的、做了但没被要求（scope creep，范围蔓延）、 看着做了但实现方向错的。

两条轴由两个并行的子代理分别跑，互不污染上下文，然后并排报告、 故意不合并排名——因为「符合所有规范但做错了东西」和「做对了东西但破坏了约定」 是两种不同的事故，不能让一条轴掩盖另一条。 对 implement 来说，Spec 轴的 spec 来源天然就是你开工时带进去的那张票或那份 spec—— 第 4 行把「做没做对」的终审权交给了它。 code-review 默认只产报告、不改代码；按报告修不修、怎么修， 是报告出来之后的事（0013 会讲透这条 skill）。

8.2 第 5 行：commit 到哪、不做什么

「Commit your work to the current branch.」——落地动作只有一个： 在当前分支上制造 commit。注意三个「没写」： 没写新建分支（所以开工前人在哪个分支，commit 就落在哪）， 没写发 PR，没写合并。0001 的副作用表里，implement 的「下一步」一栏写的是 「拿下一张没被挡住的票继续 implement；或人工合并、发 PR」——合并和发 PR 是 人的事，不是这个 skill 的动作。

双轴与子代理：code-review/SKILL.md（Why two axes、Process）· 顺序与「人工合并、发 PR」：ask-matt/SKILL.md 主流程第 3 步、0001 系统地图的副作用表 · 主链引文：docs/engineering/implement.md 的 Where it fits 一节

9. 会话卫生：一张票，一个干净会话

implement 是主流程上上下文纪律最苛刻的一站。ask-matt 专门有一节 「Context hygiene」（上下文卫生）讲这件事，规则分两半：

• 上游要腻在一起：grill → spec → tickets 这三步尽量放在 同一个不被打断的上下文窗口里，中途不 compact、不清空—— 因为面试、需求文档、拆票共享同一套推理，拆开就断了线。
• 施工要彼此干净：每一次 /implement 都新开会话， 只带那一张票进去——「clearing context between each one」（票与票之间清空上下文）。 别拖着之前聊了几万字的旧窗口进施工现场。

为什么票与票之间要清空？两个来自一手材料的理由：

1. 票就是为「一个干净窗口」设计的。to-tickets 的切片规则写明： 每张票的大小要「fit in a single fresh context window」（装得进一个全新的上下文窗口）。 票是自含的——标题、要交付的端到端行为、验收标准、被谁挡着——所以新会话只需要这张票， 不需要前面所有的闲聊。
2. 旧上下文是有成本的。ask-matt 给出「smart zone」的概念： 大约 120k token 以内模型推理依然锋利的区间。一个会话逼近这个区间时， 正确的动作是 /handoff（把对话压缩成一个 markdown 文件， 新开会话引用它继续），而不是在变钝的窗口里硬撑——0006 会专讲这座跨会话的桥。

例外也写在 ask-matt 里：需求小到一个会话能做完时（主流程第 3 步的 No 分支）， 可以在 grill / spec 之后「right here, in the same context window」直接敲 /implement——因为这种情况没有票与票的边界，卫生规则不适用。 判断标准不是「过了多久」，而是「是不是要开始下一张票」。

卫生规则：ask-matt/SKILL.md 的 Context hygiene 一节 · 票的尺寸规则：to-tickets/SKILL.md 的 vertical-slice-rules · 跨会话的桥：Lesson 0006 handoff

10. 依赖关系图：谁喂它、它拉谁、谁接它

                    上游（喂给它输入）
 grill-with-docs → to-spec ──spec──────────────┐
                       │                       │
                    to-tickets ──frontier 票───┤
                                               ▼
 triage ──agent-ready 的外来 issue ──────►  implement ──► commit（当前分支）
                                               │  │
 wayfinder ──（仅活真的小）────────────────────┘  │ prose 调用
                                                  ▼
                                    tdd（施工纪律：红绿循环、守接缝）
                                       │  读但不写：CONTEXT.md / ADR
                                       │  词汇地板：codebase-design
                                                  ▼
                                    code-review（Standards + Spec 双轴，只产报告）
                                                  ▼
                            下一张 frontier 票（新会话）/ 人工合并、发 PR

全图：0001 系统地图 · 路由：ask-matt/SKILL.md · 相邻课：0009 to-spec · 0010 to-tickets · 0012 tdd · 0013 code-review · 0014 triage · 0016 wayfinder

11. 副作用清单与微调入口

11.1 它会改什么、不会改什么

11.2 行为不对时，去改哪个文件的哪一段

总原则还是 0001 那条：入口薄、纪律厚——implement 正文只有五行， 想改行为先想清楚「这个行为到底住在哪个文件里」。症状对号入座：

微调总原则：0001 系统地图的设计规矩与典型症状 · 被调用的厚文件：tdd/SKILL.md、code-review/SKILL.md · 薄入口本体：implement/SKILL.md

12. 检索练习

先别往回翻表，凭记忆答。选项的长度刻意对齐，不会从版式泄题。答错的题号回到对应小节核对原文。

13. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/implement/SKILL.md —— 本课的主角：frontmatter 的两道锁之一 + 全部五行正文。全文件只有 15 行，值得逐字读。
• …/agents/openai.yaml —— 第二道锁：policy.allow_implicit_invocation: false。
• docs/engineering/implement.md —— 人读叙事版（aihero.dev/skills-implement）： 「hands not the head」、pre-agreed seams、主链位置。
• 被它调用的厚文件： tdd/SKILL.md（红绿循环、接缝纪律）、 code-review/SKILL.md（双轴审查）。
• 喂它的上游： to-spec/SKILL.md（第 2 步画接缝）、 to-tickets/SKILL.md（frontier、blocking edges）、 ask-matt/SKILL.md（主流程第 3 步、Context hygiene）。

推荐首先精读：implement/SKILL.md 本身—— 它是全仓库「入口薄、纪律厚」最极端的样本，15 行里藏着整套主流程的闭幕式。

速查页（本课同步）： reference/implement.html

导航： 上一课 0010 to-tickets（票是怎么拆出来、怎么发布到工单系统的）。 总览仍回 0001 系统地图。

建议下一课（0012）： 0012 tdd——implement 第 2 行拉进来的那台发动机。 本课你只看到了「红绿循环、守接缝、重构留给 review」的轮廓； 下一课把 tdd 的全文、tests.md 的好/坏测试样例、mocking.md 的边界纪律讲透。 之后 0013 code-review 接着讲闭幕式上的双轴审查。