课程目录
Lesson 0005 · 工程技能
保养与批量施工:工程模块的五个技能
主流程默认进料是干净的:spec 有共识、工单说得清、代码改得动。工程(Engineering,v1.3 前叫 Upkeep)模块的五个技能守着流程的两端——四个保养工单池与代码库不腐烂:/triage、/diagnosing-bugs、/improve-codebase-architecture、/wizard;一个批量施工:整个 spec 一次并行跑完(/implement-spec)。
本课目标:学完你能做什么。 主流程与 Shaping 管的是「往前走」;这课管的是「不烂掉」和「一次干完」。学完的检验:给出任何一个工程情境——烂票、疑症、腐化、人肉流程、整包施工——10 秒内说出该用五个技能里的哪一个,并说出它的核心动作。
v1.3 变化说明(老读者从这里补课)。
其一,本章由 Upkeep 更名 Engineering:作者对它的定位扩成「保养代码库与工单池,并为流程生成工作」。其二,/resolving-merge-conflicts 被移除,没有替代:冲突处理被视为 harness 层的活,现在的 agent 自己会解,不再需要专门技能——「先找 primary source、读懂两个意图再让路、绝不 abort」的思路仍然值得沿用,只是不再是一个技能了。其三,/implement-spec 加入本章:一整个 spec 一次并行施工。其四,文件 CONTEXT.md 全面更名为 GLOSSARY.md(见 0002)。
为什么需要这一章:agent 会放大仓库的质量
这套体系的设计前提(0001 的心法):agent 是一群没有记忆的工人。由此有一个不那么显眼的推论——agent 只看你给它看的仓库,而它读到的质量,决定它产出的质量。工单池堆满说不清的票、文档与代码悄悄脱节,agent 读到的就是这些,产出的也是这些。(来源:Make codebases AI agents love)
工程模块的五个技能因此围绕流程的两端:四个不服务于任何具体特性——保养的是流程的两样原料本身,工单池与代码库;一个(interleaving 进主流程的批量档)让「一整个 spec」可以一次并行施工。
五个工程技能全景
| 技能 | 管什么 | 触发方式 | 一句话记法 |
|---|---|---|---|
/triage | 工单池:让每张票说得清 | user-invoked | 进料口的质检员 |
/diagnosing-bugs | 代码库:疑难 bug 的根因 | model-invoked | 先造红信号,再谈原因 |
/improve-codebase-architecture | 代码库:模块的深浅 | user-invoked | 找浅模块,做加深手术 |
/wizard | 人:只有人能做的步骤 | model-invoked | 人肉流程的脚手架 |
/implement-spec | 施工:整个 spec 一次跑完 | user-invoked | 工单当任务图,worktree 并行 |
触发方式的完整二分表见 0001。本模块记一条规律:triage、improve-codebase-architecture 和 implement-spec 是 user-invoked——模型永远不会自作主张动你的工单池、给你的仓库开刀、替你开整条施工线;其余两个是 model-invoked,你说「debug 这个」「帮我配个 CI secrets」,它们就来了。
一、/triage:工单池的质检员
工单池是主流程的进料口——to-tickets 拆出的工单、使用者报来的 issue、外部 PR 都堆在这里。triage 让它不堆烂票,核心是一台小状态机:
- 两个类目角色:
bug(东西坏了)/enhancement(要新东西) - 五个状态角色:
needs-triage(评估中)→needs-info(等报告者补充)/ready-for-agent(说明充分,agent 可直接认领)/ready-for-human(得人来做)/wontfix(不做)
三件事让它区别于「随手打标签」:
- 先验证,再分类。bug 票按报告者的步骤亲手复现一次;外部 PR 检出代码、跑一遍相关测试。验证过的事实连同代码路径写进简报,
ready-for-agent的票才真的「agent 可认领」——这和 to-tickets 的工单是同一个标准。 - 每条 AI 评论开头挂免责声明:「This was generated by AI during triage.」——triage 期间发出的所有评论与工单都要带。
- 被拒的想法留档。enhancement 被拒时写入
.out-of-scope/知识库并在评论里链接过去,防止将来的 triage 把同一个想法重新捞一遍。
状态流转只记两处易混点:needs-info 在报告者回复后回到 needs-triage 重新评估;维护者可以随时越过流程直接定状态,但异常流转要先询问。(来源:本地插件 engineering/triage/SKILL.md)
二、/diagnosing-bugs:先造红信号,再谈原因
六个阶段:建回路 → 复现并最小化 → 列假设 → 插桩 → 修复 + 回归测试 → 清理。六步里只有第一步是「技能本身」,原文说得直接:Build the right feedback loop, and the bug is 90% fixed.(中译:建对反馈回路,bug 就修好了九成。)
Phase 1 的完成判据:手里有一条一条命令能触发的信号,并且已经真的跑过至少一次。它必须同时满足四个词:
- red-capable:能为此 bug 变红——断言的是使用者描述的那个症状,不是「没报错」
- deterministic:每次跑结论相同;偶发 bug 的目标不是干净复现,而是提高复现率(50% 的 flake 可调试,1% 不行)
- fast:秒级,不是分钟级
- agent-runnable:无人值守可跑
一条硬纪律压在所有步骤之前:没有红信号,不许进入假设。「先翻代码建个理论」正是这个技能要防止的失败——没有回路,盯着代码看多久都救不了。
后面几步各记一个动作:假设一次列 3–5 条、每条可证伪、排好序再动手(单假设会锚定在第一个像样的想法上);插桩一次只改一个变量,调试日志挂唯一前缀(如 [DEBUG-a4f2]),收尾一次 grep 清干净;修复落地后,把最终证明正确的那个假设写进 commit message,让下一个调试的人学到。(来源:本地插件 engineering/diagnosing-bugs/SKILL.md)
回归测试还有一条与 tdd 同源的判定词:测试要落在正确的 seam 上——真实 bug 在调用点发生的位置。如果现有接缝太浅、测试触发不了真实调用链,没有正确的 seam 本身就是发现:记录它,架构在阻止这个 bug 被锁死。
修完还有一步新路由(v1.3):ask-matt 现在会把「修完 bug」引向 /retro——复盘这个 bug 为什么能溜进来,把教训变成仓库的自动检查,而不只是这一次修好了。retro 是主流程第六步,详见那里的讲解。(来源:本地插件 engineering/ask-matt/SKILL.md)
呼应 0002 的两个关联机制: 其一,tdd 的红-绿循环与这里的红信号是同一个判定词——tdd 的红来自「还没实现的正确行为」,诊断的红来自「已经存在的错误行为」,先红后修的次序相同。其二,「正确的 seam」用的正是 codebase-design 的深浅词汇:单测触发不了真实调用链 = 接缝太浅,与「一个 adapter = 假想 seam,两个 = 真 seam」是同一套判断。
三、/improve-codebase-architecture:找浅模块,做加深手术
目标词是 deepening(加深):把浅模块变成深模块,为了可测试性与 AI 可导航性。它与 codebase-design 用同一套词汇(module、interface、depth、seam、adapter、leverage、locality)——那个技能给共同语言,这个技能找手术位置。两步走:
- 扫描,但先定范围(YAGNI)。加深是为「未来的改动」买单,所以给最近常改的地方加权:走一遍 git log 找热区,而不是全仓库无差别扫。对每个嫌疑模块上删除测试(deletion test):删掉它,复杂度是集中还是只是挪走?「集中」才是它真在扛复杂度的信号。
- 报告 + 访谈。候选写成自包含 HTML 报告放进系统临时目录(不落仓库),每个候选带 before/after 图与推荐强度(Strong / Worth exploring / Speculative);你挑一个,它转入 grilling 访谈回路,把加深方案问成型。新概念随手进 GLOSSARY.md;被否决且理由承重的候选,提议立 ADR,防止将来的扫描把同一方案重新端上来。(来源:本地插件 engineering/improve-codebase-architecture/SKILL.md)
四、/wizard:只有人能做的步骤,交给脚本陪着走
配 CI secrets、在陌生的第三方后台找开关、做一次性数据迁移——这些步骤 agent 替不了:要点浏览器、要人眼核对、要身份。wizard 把它们写成一个 bash 脚本:打开对应网址、逐屏说明点什么抄什么、收下值写到该去的地方(.env、GitHub secrets)、每步确认、显示还剩几步。三条边界:
- 准入判据一句话:只有 agent 自己做不了的步骤才用。agent 能自己改的配置文件,不值得一个 wizard。
- 默认即弃:为一次运行而建,完工即删;想留成可重复的安装路径,才提交进仓库。
- 不发明步骤:不确定后台的路径长什么样,就问人或查文档——原文禁止编造可能不存在的操作。(来源:本地插件 engineering/wizard/SKILL.md)
案例:本站诞生记。 上线排障时发过一枚 Vercel token,用完需要在后台手动 Revoke:登录、找到 token、点删除,每一步都得人来做——这正是 wizard 的标准领地,哪怕流程只有三步。你自己的仓库里,凡是「得登录别人的后台」的活,都长这个样子。
五、/implement-spec:一整个 spec,一次并行施工
主流程上的 /implement 一次吃一张工单;spec 一拆十几张票,逐张敲既慢又丢全局。/implement-spec(v1.3)是它的批量档:把整个 spec 一次跑完,目标是全部工单落在一条**集成分支(integration branch)**上。四个机制(SKILL.md 原文):
- 工单不是列表,是任务图。票之间的 blocking 关系构成图,所以任何时刻都有一批可开工的 frontier——一个实现子代理完工,frontier 前移,就点火下一批。这和 to-tickets 声明依赖的方式、wayfinder 的 frontier 是同一套词汇。
- 实现子代理各占一个 worktree。每个子代理在自己的工作树里干活:开工前确认自己的分支基于集成分支(不是就重置过去);内部调用 tdd 建票;完工前把集成分支的最新尖端合进自己分支,保证回来时都是快进合并。子代理之间不传话,只传上下文指针(spec、工单、笔记、commit)——信息靠指针够到,不靠复述。
- 合并交给合并子代理,审查统一收口。谁完工谁被并进集成分支;全部完工后,在集成分支上跑一次
/code-review,发现的问题交给单个实现子代理一次修完。默认不开 PR(除非你的 tracker 以 PR 关单、或你开口要)——产出物就是那条集成分支。 - 没有 tracker,先跑 setup。它不默认 GitHub:没配置 issue tracker 就让你先跑
/setup-matt-pocock-skills。
两条作者自认的边界,值得抄在心上:这条 agent 流水线不比确定性脚本省心(「The agent loop is worse than a deterministic loop」)——票的依赖是纯线性、动作高度机械时,写个脚本跑更稳;它真正的价值是 AFK 工作的入门形态。此外所有工作落在大分支上,worktree 只是把撞车推迟到合并时刻——收尾那次 code-review 是唯一的关口。(来源:本地插件 engineering/implement-spec/SKILL.md 与 Skills changelog v1.3)
十秒路由:工程情境进哪个技能
| 情境 | 技能 | 出口 |
|---|---|---|
| 工单池堆了没看过的 issue / 外部 PR | /triage | ready-for-agent + agent 简报 |
| 疑难 bug / 性能回归,根因不明 | /diagnosing-bugs | 修复 + 回归测试 + 结论进 commit |
| 仓库越来越难改、难测,agent 越来越难导航 | /improve-codebase-architecture | 加深机会报告 → 访谈 → 工单 |
| 一段只有人能做的手工流程(凭证 / 后台 / 迁移) | /wizard | 一次性 bash 向导 |
| 一整个 spec 十几张票,想一次跑完 | /implement-spec | 集成分支上全部工单落地 + code-review |
可打印的全景路由表见全局地图。
练一练:情境路由(混编 tdd / codebase-design 判定词)
得分 0 / 7
1. 一个 spec 拆出了十几张工单,你不想一张张敲 /implement,而想让它一口气全部落地。该用哪个?
2. 一张 bug 票缺复现步骤,triage 已请报告者补充,正在等他回复。此刻这张票停在哪个状态?
3. 一张 bug 票看起来很真,准备推向 ready-for-agent。哪个动作让 agent 简报的质量远胜口说无凭?
4. 接到一个偶发 bug,最想立刻翻代码找原因。按 diagnosing-bugs 的纪律,此刻手里缺的是?
5. bug 修好了,想写回归测试锁住它,却发现现有接缝太浅:单个测试触发不了真实的调用链。按规矩,这算什么?
6. 怀疑某个模块是浅模块,用哪个测试下判断?
7. 哪个情境才轮到 /wizard 出场?
已答 0 / 7 题。
合上页面,回忆一遍
- diagnosing-bugs 的红信号要同时满足哪四个词?
- 没有红信号之前,哪个动作被明令禁止?
- triage 里,报告者回复之后,
needs-info的票回到哪个状态? - implement-spec 的产出落在一条什么分支上?工单在那里被当成什么来组织?
- 删除测试的「好信号」是哪两个字?
- wizard 的准入判据,一句话是什么?
隔天不看答案再自问一遍,第 3、7 天各再轮一次——检索本身才长记忆。
首读材料
本课最值得通读的原文:engineering/diagnosing-bugs/SKILL.md——五个 SKILL.md 里最厚的一份,十条「造回路」的手法值得逐条读。想补理念底座,读 Make codebases AI agents love:代码库质量如何决定 agent 输出质量。
卡住了怎么办。 「triage 的票和 to-tickets 的工单差在哪」「回归测试的 seam 怎么判」这类困惑,先查词典与全局地图, 然后带进你自己的实战里验证;是课件讲得不清楚的,到仓库 issue 区提出来。