Agent Skills 中文课非官方
课程目录

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(不做)

三件事让它区别于「随手打标签」:

  1. 先验证,再分类。bug 票按报告者的步骤亲手复现一次;外部 PR 检出代码、跑一遍相关测试。验证过的事实连同代码路径写进简报,ready-for-agent 的票才真的「agent 可认领」——这和 to-tickets 的工单是同一个标准。
  2. 每条 AI 评论开头挂免责声明:「This was generated by AI during triage.」——triage 期间发出的所有评论与工单都要带。
  3. 被拒的想法留档。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)——那个技能给共同语言,这个技能找手术位置。两步走:

  1. 扫描,但先定范围(YAGNI)。加深是为「未来的改动」买单,所以给最近常改的地方加权:走一遍 git log 找热区,而不是全仓库无差别扫。对每个嫌疑模块上删除测试(deletion test):删掉它,复杂度是集中还是只是挪走?「集中」才是它真在扛复杂度的信号。
  2. 报告 + 访谈。候选写成自包含 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 原文):

  1. 工单不是列表,是任务图。票之间的 blocking 关系构成图,所以任何时刻都有一批可开工的 frontier——一个实现子代理完工,frontier 前移,就点火下一批。这和 to-tickets 声明依赖的方式、wayfinder 的 frontier 是同一套词汇。
  2. 实现子代理各占一个 worktree。每个子代理在自己的工作树里干活:开工前确认自己的分支基于集成分支(不是就重置过去);内部调用 tdd 建票;完工前把集成分支的最新尖端合进自己分支,保证回来时都是快进合并。子代理之间不传话,只传上下文指针(spec、工单、笔记、commit)——信息靠指针够到,不靠复述。
  3. 合并交给合并子代理,审查统一收口。谁完工谁被并进集成分支;全部完工后,在集成分支上跑一次 /code-review,发现的问题交给单个实现子代理一次修完。默认不开 PR(除非你的 tracker 以 PR 关单、或你开口要)——产出物就是那条集成分支。
  4. 没有 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/triageready-for-agent + agent 简报
疑难 bug / 性能回归,根因不明/diagnosing-bugs修复 + 回归测试 + 结论进 commit
仓库越来越难改、难测,agent 越来越难导航/improve-codebase-architecture加深机会报告 → 访谈 → 工单
一段只有人能做的手工流程(凭证 / 后台 / 迁移)/wizard一次性 bash 向导
一整个 spec 十几张票,想一次跑完/implement-spec集成分支上全部工单落地 + code-review

可打印的全景路由表见全局地图。

练一练:情境路由(混编 tdd / codebase-design 判定词)

得分 0 / 7

  1. 1. 一个 spec 拆出了十几张工单,你不想一张张敲 /implement,而想让它一口气全部落地。该用哪个?

  2. 2. 一张 bug 票缺复现步骤,triage 已请报告者补充,正在等他回复。此刻这张票停在哪个状态?

  3. 3. 一张 bug 票看起来很真,准备推向 ready-for-agent。哪个动作让 agent 简报的质量远胜口说无凭?

  4. 4. 接到一个偶发 bug,最想立刻翻代码找原因。按 diagnosing-bugs 的纪律,此刻手里缺的是?

  5. 5. bug 修好了,想写回归测试锁住它,却发现现有接缝太浅:单个测试触发不了真实的调用链。按规矩,这算什么?

  6. 6. 怀疑某个模块是浅模块,用哪个测试下判断?

  7. 7. 哪个情境才轮到 /wizard 出场?

已答 0 / 7 题。

合上页面,回忆一遍

  1. diagnosing-bugs 的红信号要同时满足哪四个词?
  2. 没有红信号之前,哪个动作被明令禁止?
  3. triage 里,报告者回复之后,needs-info 的票回到哪个状态?
  4. implement-spec 的产出落在一条什么分支上?工单在那里被当成什么来组织?
  5. 删除测试的「好信号」是哪两个字?
  6. wizard 的准入判据,一句话是什么?

隔天不看答案再自问一遍,第 3、7 天各再轮一次——检索本身才长记忆。

首读材料

本课最值得通读的原文:engineering/diagnosing-bugs/SKILL.md——五个 SKILL.md 里最厚的一份,十条「造回路」的手法值得逐条读。想补理念底座,读 Make codebases AI agents love:代码库质量如何决定 agent 输出质量。

卡住了怎么办。 「triage 的票和 to-tickets 的工单差在哪」「回归测试的 seam 怎么判」这类困惑,先查词典与全局地图, 然后带进你自己的实战里验证;是课件讲得不清楚的,到仓库 issue 区提出来。