保持健康:不让仓库腐烂的五个保养技能

为什么需要保养:agent 会放大仓库的质量

这套体系的设计前提(0001 的心法):agent 是一群没有记忆的工人。由此有一个不那么显眼的推论——agent 只看你给它看的仓库,而它读到的质量,决定它产出的质量。工单池堆满说不清的票、合并冲突拖着不解、文档与代码悄悄脱节,agent 读到的就是这些,产出的也是这些。(来源:Make codebases AI agents love)

Upkeep 模块的五个技能因此不服务于任何具体特性——它们保养的是流程的两样原料本身:工单池与代码库。

五个保养技能全景

技能	保养什么	触发方式	一句话记法
/triage	工单池:让每张票说得清	user-invoked	进料口的质检员
/diagnosing-bugs	代码库:疑难 bug 的根因	model-invoked	先造红信号,再谈原因
/resolving-merge-conflicts	代码库:合并中的冲突	model-invoked	读懂两个意图,再判谁让路
/improve-codebase-architecture	代码库:模块的深浅	user-invoked	找浅模块,做加深手术
/wizard	人:只有人能做的步骤	model-invoked	人肉流程的脚手架

触发方式的完整二分表见 0001。本模块记一条规律:triage 和 improve-codebase-architecture 是 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 被锁死。

三、/resolving-merge-conflicts:读懂两个意图

五步:看清合并/rebase 的当前状态 → 找每处冲突的 primary source(读 commit、PR、原 issue,弄懂两侧各自为什么改)→ 逐块解决 → 跑项目的自动检查(typecheck → tests → format,修掉合并弄坏的东西)→ 完成合并/rebase。

原则:尽量保留双方意图;确实互斥时,按本次合并的目标选边,并把权衡记录下来;不发明新行为。两条铁律:总是解决,绝不 --abort。冲突的本质是两个合理的意图在同一行相遇——先读懂两边,才轮到判谁让路。(来源:本地插件 engineering/resolving-merge-conflicts/SKILL.md)

四、/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 访谈回路,把加深方案问成型。新概念随手进 CONTEXT.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 的标准领地,哪怕流程只有三步。你自己的仓库里,凡是「得登录别人的后台」的活,都长这个样子。

十秒路由:保养情境进哪个技能

情境	技能	出口
工单池堆了没看过的 issue / 外部 PR	/triage	ready-for-agent + agent 简报
疑难 bug / 性能回归,根因不明	/diagnosing-bugs	修复 + 回归测试 + 结论进 commit
合并 / rebase 被冲突挡住	/resolving-merge-conflicts	双方意图都保住的干净合并
仓库越来越难改、难测,agent 越来越难导航	/improve-codebase-architecture	加深机会报告 → 访谈 → 工单
一段只有人能做的手工流程(凭证 / 后台 / 迁移)	/wizard	一次性 bash 向导

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

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

得分 0 / 7

1. 1. 合并 main 时撞出冲突,两侧改动都不是你写的,当时为什么改已经说不清。该用哪个技能进场?

   /code-review/resolving-merge-conflicts/diagnosing-bugs/triage

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

   needs-infoneeds-triagewontfixready-for-human

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

   把标题改写成一条祈使句给 issue 补上两个类目标签先亲手复现一次报告的 bug在评论区先贴出 AI 免责声明

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

   一条能让 bug 变红的一条命令信号一份覆盖全部代码路径的详尽日志一轮按优先级排好序的假设清单一份把根因钉死的架构调研报告

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

   换条更浅的接缝凑合写,聊胜于无这本身就是发现:记录它,别硬凑测试在测试里手工复刻出整条调用链先跳过测试,靠人工点检兜底

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

   命名测试:模块名能否一眼看懂职责行数测试:实现是否比接口长出太多覆盖测试:它有没有足够的测试覆盖删除测试:删掉它,复杂度是集中还是摊开

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

   要 agent 改一个本地配置文件要脚本每天凌晨自动清理旧日志要人在第三方后台点出密钥,再填进 CI要三个子代理并行实现三张工单

已答 0 / 7 题。

合上页面,回忆一遍

1. diagnosing-bugs 的红信号要同时满足哪四个词?
2. 没有红信号之前,哪个动作被明令禁止?
3. triage 里,报告者回复之后,needs-info 的票回到哪个状态?
4. 解冲突的两条铁律是什么?
5. 删除测试的「好信号」是哪两个字?
6. wizard 的准入判据,一句话是什么?

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

首读材料

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