用 skill 维护老项目：排查、修复、迭代

"Onboard me to this codebase"
→ 跑完整四阶段，导览输出在对话里，CLAUDE.md 写进项目根目录

"Generate a CLAUDE.md for this project"
→ 只跑第 1–3 阶段，只产出 CLAUDE.md，不写导览

"Update the CLAUDE.md with current project conventions"
→ 先读现有文件，跑第 1–3 阶段，合并，标出新增了什么

• 用 Glob / Grep 扫，不要对每个文件调 Read——只在有歧义时才选择性读文件。
• 代码和配置冲突时，信代码。
• 尊重已有的 CLAUDE.md——增强，不替换。
• 导览要"2 分钟能扫完"。
• 不确定的地方标出来，不要猜。
• 反模式：CLAUDE.md 超过 100 行 · 把每个依赖都列出来 · 解释一眼就懂的目录名 · 抄 README。

它产出的那份 CLAUDE.md 打开数一下行数——超过 100 行，就是它在往里塞代码里本来就看得见的东西（第 §03 那两条判断标准）。然后从它的结论里挑 3 条去核对，比如它说"认证在 src/middleware/auth.ts"，你就去那个文件看一眼。

拿到文档后做一件事：找出里面至少 3 条"你不知道、而且是靠读代码才能得出"的结论，去代码里核实。如果通篇都是你本来就知道的东西，说明这次倒推的深度不够，把范围收窄到某一个模块再要一次。

• 拿术语表挑刺：你说的词和 CONTEXT.md 里定义的不一致，它当场指出来——"你的术语表把 'cancellation' 定义为 X，但你似乎指的是 Y。是哪个？"
• 把模糊说法磨尖：你说"account"，它会问"你指的是 Customer 还是 User？这是两个不同的东西"。
• 用具体场景压测：故意构造边界场景，逼你把概念之间的边界说清楚。
• 和代码交叉核对：你描述的行为和代码对不上时，它会把矛盾摆出来——"你的代码是整单取消，但你刚说支持部分取消。哪个是对的？"
• 当场更新 CONTEXT.md，不攒着批量写。

另外一条纪律值得注意：CONTEXT.md 里不许有任何实现细节——它只是术语表，不是规格、不是草稿本。

三条缺任何一条，就不建 ADR。 这个门槛是它防"文档泛滥"的机制——ADR 一多就没人看了。

最好的时机是你终于从某个老同事嘴里问出"当年为什么要这么写"的那一刻——趁热让它把这句话落成一个 ADR。这类知识不写下来，就随人一起走掉了。

做法：把那段对话原样讲给它听（"我们当年用双写而不是事务，是因为要兼容一个已经不存在的旧系统"），它会按三个条件判断该不该建、该建在哪、怎么命名（docs/adr/0001-event-sourced-orders.md 这种格式）。

它要求每次改动后按原则自评，报告当前得分，以及达到 10 分需要做的具体步骤。这是本文所有 skill 里最"可验收"的一个——你不需要判断它做得对不对，你只需要看它给自己打了几分、以及差在哪。

它把这个叫 "遗留代码的两难"：安全地改需要有测试，但装上测试又需要先改代码。它的解法是把顺序钉死：

它给这个顺序配了一句解释，值得记住："编程就是一次只做一件事的艺术"——因为每一步都能被单独验证。反过来，行为改动和结构改动混在一个步骤里，出问题时就再也分不清是谁造成的。

如果那块地方今天真的测不了，它的建议不是"那就别写测试了"，而是不要把新逻辑编进那坨没测试的东西里：

Wrap（包裹）是另一个手法：把老函数改个名收起来（pay() → rawPay()），然后重建一个同名的 pay() 当外壳，在调用前后加新行为（审计日志之类的）。适合有多个调用点、或者那个类已经太臃肿的时候。

按侵入性从小到大：提取接口 · 把构造函数参数化 · 把方法参数化 · 提取并覆写工厂方法/取值方法 · 引入实例委托 · 适配参数 · 把方法拆成独立对象 · 子类化并覆写方法。

它的选择规则是：永远挑"能解开当前问题的最小侵入手法"。 其中两个最常用——

• 把构造函数参数化（它是主力手法）：给它加一个参数并提供一个生产环境默认值，现有调用点一个字都不用改就能编译通过。
• 提取接口（它是最安全的动作）：因为"加一个接口"这件事本身不可能改变行为。

反过来，它点名了接缝死掉的地方：构造器里干实事、全局变量、静态变量、写死的 I/O。以及一个判断：一个没有"启用点"的接缝是没用的——所谓启用点，就是"在这里决定用哪个实现"的那个位置。

最能说明问题的是"把构造函数参数化"这个最常用的手法。注意改完之后，生产代码的行为一个字没变：

// 改之前：这个函数没法单独测，因为它一跑就去连真数据库
function getOrderTotal(orderId) {
  const db = new RealDatabase(process.env.DATABASE_URL)
  return db.query('...')
}

// 改之后：多了一个参数，这个参数就是"接缝"
// 测试里可以传一个假的 db，生产代码里走默认值，行为完全不变
function getOrderTotal(orderId, db = defaultDb) {
  return db.query('...')
}

它对这个手法的评价是"主力手法"，原因就是那句：现有调用点一个字都不用改就能编译通过——所以它属于"保守且机械"的那一类前置改动。

• 效应草图：给每个变量、每个方法画一个气泡，谁影响谁就画一个箭头，一直追到所有"泄漏点"。目的是找到收窄点——那个"少量测试就能覆盖大片行为"的窄口。
• 特征草图：看一个巨大的类里面，方法和字段是怎么聚成几团的——团与团之间通常就是天然的拆分边界。
• 草稿式重构：在一条件上随便重构，目的只是为了看懂，然后整条扔掉。"洞见会留下来，代码不会。"

它的判断是：遗留代码工作的瓶颈是"理解"，不是"打字"。

它的触发词里包含这些原话：legacy code、no tests、untested codebase、how do I test this、seams、characterization tests、golden master、sprout method、afraid to change this code、monster method、inherited a messy codebase。所以你可以直接说：

"这块代码没有测试，我不敢改。用 working-with-legacy-code 的方法带我做：
 先告诉我改动点和测试点分别在哪、要打通什么依赖。"

# 它跑完之后，追问这一句：
"按这个 skill 的标准给这次改动打分，并列出达到 10 分还差哪几步。"

一条边界要知道：它明确把"改造已经有测试的代码"路由给另一个 skill（refactoring-patterns），把"日常代码质量"路由给 clean-code。 这是好事——说明它知道自己管哪一段。

第 1 步那些命令，你可以自己先跑一遍看看规模（不改任何东西）：

# JS / TS：没被用到的文件、导出、依赖（覆盖面最广，先用它）
npx knip --reporter compact

# 只查没用到的 npm 依赖
npx depcheck

# Python：没被用到的代码
# --min-confidence 是"置信度门槛"：调高只报更确定的，调低会有一堆误判
vulture src/ --min-confidence 80

先跑一遍、看一眼数量，再决定要不要让它动手。 如果 SAFE 档有 300 项，别一次跑完——分批，每批之后停下来看一眼 diff。

这个 skill 只管"确定没人用的"。它会顺带做一点重复代码的合并（第 5 步），但那是最浅的一层——它不会替你判断"这两段重复该不该合并"。

而 AI 时代最典型的债务恰恰是后一种：那四份 calcTotal 全都在被引用，静态工具对它们完全无感。要处理那一层，得回到 working-with-legacy-code 的流程，一个个判断。

"跑一遍 refactor-clean，只处理安全档的项目，每删一个都跑测试。"

# 想更保守，可以自己加限制：
"跳过所有组件和路由，只删工具函数和测试辅助函数。"

很多人卡在"我不知道它应该返回什么，所以写不了测试"。这个配方精妙的地方就是它不需要你知道：

// order.test.js —— 表征测试：记录的是"现在是这样"，不是"应该是这样"
import { describe, it, expect } from 'vitest'
import { calcTotalV2 } from './order.js'

describe('calcTotalV2 —— 现状记录，不是需求', () => {
  it('空订单返回 -1（是的，返回 -1，不是 0）', () => {
    // 这个 -1 是现状。看起来像 bug，但先钉住，单独开一张单子去修。
    expect(calcTotalV2([])).toBe(-1)
  })
})

如果这个函数输出的是一份报表或者一大坨 JSON，没法逐字段断言，就用黄金标准测试（也叫 approval testing、快照测试）：第一次跑把完整输出原样存成文件 → 人工看一遍确认"对，这就是现在的样子"（这步不能省）→ 提交进仓库 → 以后每次都和它比。

新手最容易做错的一件事：以为"补测试"就是"给这个模块补一套完整测试"。不是。只覆盖你这次要动的那些分支。

理由很实际：给整个模块补完整测试要花两周，而你的任务是三天内加一个优惠券功能。要两周的测试你根本不会写，于是你会跳过安全带直接上手——那才是最危险的结果。

1. 在能触及 bug 的接缝上写一个失败的测试（单元 / 集成 / 端到端都行）
2. 对跑着的开发服务器写 curl / HTTP 脚本
3. 用固定的输入跑一次 CLI，把标准输出和"已知正确"的快照做 diff
4. 无头浏览器脚本（Playwright / Puppeteer）驱动界面，断言 DOM / 控制台 / 网络
5. 重放一次抓到的请求：把真实的网络请求、载荷或事件日志存到磁盘，单独喂进那条代码路径
6. 临时脚手架：起一个最小子系统（一个服务、依赖全 mock），用一次函数调用跑通 bug 路径
7. 属性测试 / 模糊测试循环：如果 bug 是"有时输出不对"，跑 1000 个随机输入找失败模式
8. 二分查找脚手架：bug 是在两个已知状态之间出现的，就自动化"在状态 X 启动、检查、重复"，这样你能直接 git bisect run
9. 差分循环：同一个输入分别走旧版本和新版本，diff 输出
10. 人来点的最后手段：如果必须有人点，就写脚本去驱动人，让回路仍然是有结构的

然后它要求你把这个回路当产品打磨：能不能更快？能不能让信号更锋利（断言具体症状，而不是"没崩"）？能不能更确定（把时间钉住、把随机数种子固定、隔离文件系统、冻结网络）？——"一个 30 秒的抖动回路比没有回路好不了多少；一个 2 秒的确定性回路是调试超能力。"

"线上偶发：提交订单时大约 5% 的概率金额算成 0。复现不出来。诊断一下。"
→ 它会先去造能变红的回路，而不是先猜原因

"这两个月这个接口的 P95 从 120ms 涨到 400ms，找不到是哪次改动引入的。"
→ 走性能支线：先建基线测量，再二分

• 先红后绿。 先写失败的测试，然后只写刚好让它通过的代码。不要预判未来的测试，不要加投机性的功能。
• 一次一个切片。 一个接缝、一个测试、一个最小实现。
• 重构不属于这个循环。 它属于评审阶段（那个 skill 叫 code-review），不属于红 → 绿的实现循环。

第三条是这两篇文章的接缝：tdd 管"写新代码"，working-with-legacy-code 管"改没测试的旧代码"，code-review 管"改完之后"。 三个 skill 的地盘几乎不重叠。

就算你的仓库什么都没写，标准轴也总会带上这份来自 Fowler《重构》第三章的固定清单。两条约束是：仓库写了的规矩永远优先于这份基线（仓库认可某种做法时，就把对应的味道压掉）；以及每一条永远是判断题（它写的是"可能的 Feature Envy"，不是硬性违规），工具已经能查的项直接跳过。

/code-review                    # 它会问你要固定点
"review since main"             # 对比 main 的 merge-base
"review since HEAD~5"
"review since a3f9c21"          # 某个具体 commit

它内部用的是三点语法 git diff <固定点>...HEAD——对比的是合并基点，这样不会把主干上的无关变化算进来。而且它会先确认固定点能解析、diff 不为空，再开两个子 agent——"一个错误的引用或空 diff 应该在这里就失败，而不是在两个并行子 agent 里面失败"。

1. 探索——扫代码库，找架构摩擦点。
2. 把候选摆成一份可视化 HTML 报告——让你能看，而不是读一长串文字。
3. 拷问循环——你挑一个，它就带你把它问穿。

注意它给的是"候选清单和排序依据"，不是命令。 而且它有一个前置条件：disable-model-invocation: true，也就是说 AI 不会自己启动它，你必须敲名字。

不是第一次接项目的时候——那时候你连哪里疼都不知道。正确的时机是：你已经走通了三四条路，手里有测试、有地图、有业务文档，然后问"下一步该系统性地挖哪里"。

一个搭配用法：先跑 /improve-codebase-architecture 拿到候选清单，把它挑中的那一条交给 working-with-legacy-code 去实际执行——一个负责"挖哪里"，一个负责"怎么安全地挖"。

因为老项目清理最大的失败模式是"一次做太多"——一个几百文件的 diff，没人能审，你自己也不敢合。这两个 skill 把"一次做太多"变成了结构性的不可能：每张票是一个垂直切片，能单独交付、单独撤销。

而它们产出的票据长这样（这是它自带的模板）：

# <NN>: <票据标题>

## Parent          # 属于哪张父票
## What to build  # 要做出什么
## Acceptance criteria  # 验收标准
## Blocked by      # 被哪几张票阻塞

"Blocked by"这一栏是老项目里最有价值的部分——它把"先补测试才能改这块"这种依赖关系显式写下来了，而不是留在你脑子里。

# 先聊清楚要做什么（可以先用 improve-codebase-architecture 挑出目标）
/to-spec          # 综合刚才聊的，出一份规格
/to-tickets       # 把规格拆成带阻塞关系的票据

两个 skill 都需要一个前置配置：问题追踪系统的接入（它们的 SKILL.md 里写着，如果 docs/agents/issue-tracker.md 不存在，会让你先跑一个初始化命令）。也就是说它们需要知道你用什么记任务——GitHub Issues、Linear、还是别的。本地也支持：每个票据一个文件、阻塞关系写成文字。

它的原话："一个 PR 就是一个附带了代码的 issue"——用同一套角色、同一套状态、同一台状态机，只有少数几处标了"对 PR 而言"的差异。

/triage              # 先摆出"有哪些需要关注"
/triage #42          # 分诊具体某一个（issue 或 PR 都行）

它内置了一份"信息不足"的模板，所以它不会硬猜——缺信息时会照模板去问。它还支持恢复上一次的分诊会话。

老项目里它最有用的一步是"写成 agent-ready 的简报"：把一个含混的 issue 变成一份 AI 能直接执行的说明。这正好接上第 5 节那个"四要素任务模板"——分诊负责把话说清楚，working-with-legacy-code 负责安全地做。