lean

lean —— AI 协作的产出纪律

是什么

agent 写注释、文档、测试、新轮子的那一刻适用的判据集。上位原则在 axiom 第三部（删除是最高级别的优化、概念税、AI 协同纪律），本 skill 是它们的操作投影，不重述原则。

不是什么：结构治理是 butler；一次性深打磨是 overhaul；经验提炼方法是 experience-to-spec；交付验收是 review。

0. 为什么存在

生成是零成本的，维护不是。人写注释有体力摩擦、有评审摩擦，天然节俭；agent 两样都没有，于是「顺手写」成了默认——顺手的长注释、顺手的详尽文档、顺手的全覆盖测试、顺手的新工具函数。每一样单独看都无害，堆起来就是「越开发越慢」。

四条病根（都已被实证）：生成零成本导致 over-produce 默认；会话局部性导致看不见仓库已有的轮子；取悦偏差让「看起来完整」压过「真的需要」；规则真空让职业节俭习惯没有传导到 agent 的通道。本 skill 就是那条通道。

总判据：会话收尾时问——本次新增的注释、文档段、测试、函数，若整体回滚，哪个具体的疑问或缺陷会回来？说不出名字的，就是没挣到位置。

1. 注释

只写代码说不出的约束：取值依据、边界理由、不变量、外部契约的坑。

推导：注释的读者是六个月后没有上下文的维护者。复述代码的注释在这个读者面前价值为零，还会随代码演进漂移成谎言；谎言注释比没有注释更坏，因为它会被当真。

判据：

• 删掉这条注释，读者会在哪个具体场景犯错？说不出场景 → 删
• 出现「之前 / 不再 / 现在 / 修复后 / v0.x」→ 历史归 git 与 CHANGELOG，注释只留当前约束
• 注释动词与代码行为矛盾（注释写「吞掉」而代码 raise）是缺陷级问题：改注释或改代码，不许并存
• 例外：用历史反差讲清约束由来（「下限是刻意的：3–4 连是人话」）算约束说明，不算历史叙事——判据是它删掉后读者会不会调错参数

2. 文档

一个事实一个权威；文档写「为什么、边界、判据在哪」，不写「过程怎么走到这里」。

推导：文档按天腐化，过程叙事是腐化最快的内容——它描述已经结束的状态转移，对「现在是什么」零贡献，却会被读者当成现状。修复故事沉淀在设计文档里，是这个时代最典型的文档债。

判据：

• 每一段问：这个事实的权威是本段吗？不是 → 改成链，不抄
• 修复故事（早先是 A、发现 B、现在修成 C）→ ADR 记为什么，CHANGELOG 记变了什么，设计文档只留 C
• 元话语（「值得注意的是」「综上所述」「我们需要认识到」）与排比段 → 删；文档话术与代码注释同一个预算
• 立新文档前问：一年后谁读它、读哪一节？答不出 → 不立，写进既有权威的一节

3. 测试

测试是判据不是覆盖：只为真断过的地方与不变量立测试，断言只断在乎的性质。

推导：测试的维护成本随条数线性增长，防缺陷价值却边际递减；脆断言在每次合法重构时收税；没被打红过的判据可能根本没牙。审计一个 857 条的成熟套件：可直言删除的不到 0.5%——「测试太多」几乎从来不是真问题，「测试写得死、跑得慢、没牙」才是。

判据：

• 新增一条测试前问：删掉它，什么具体缺陷会溜进来？说不出 → 不写
• 断言写性质不写快照：子集、差量、下限优先；钉死完整字符串/完整列表 = 给下次合法改动埋雷
• 新判据要故意改坏一次实现、确认它变红，否则不算存在
• flaky 修两次不平 → 删或隔离；不诚实的红比不设防更坏，它教会所有人忽略红灯
• 慢不在条数在结构：真集成、外部进程、真模型类测试打 marker 分层，日常反馈走快档，门禁全量语义不变

4. 轮子

写新工具函数或新抽象之前，先搜仓库与依赖里已有的；三现才抽象。

推导：会话是局部的，agent 不知道仓库已有轮子——重造的轮子与原轮子必然漂移（同一个 ffmpeg 样板五处手写，错误尾长各自为政，而带取消与超时的共享版就在隔壁）。但反方向同样是债：为单一调用方提前抽象是错误抽象，改起来比重写更贵。两头都要防。

判据：

• 新函数/新类落笔前，先 rg 仓库名与依赖清单，一分钟；找到就复用，哪怕签名差一点也比新造好
• 抽象的准入：已有两个真实调用方、第三个在路上；两处相似 → 先允许重复存在
• 抽的时候取最保守的形状做接口，别按最新那处的需求扩

5. 负熵提交

碰过的文件比来时干净一点；但一次提交只做一件事。

推导：债不是某个大决定留下的，是千万次「先不清了」攒出来的；反过来，顺手大改会污染 diff，让审查与回滚失效。

判据：

• 本次 diff 触及的文件里看到死代码、说谎注释、双胞胎函数 → 顺手清，计入本次提交
• diff 之外的文件 → 不动，记成新任务；「先不清理」与「顺手清理无关文件」都禁止
• 收尾自查本次新增行数：注释几行、文档几行、测试几条、代码几行——各自报出对应挣得位置的理由

6. 债雷达与瘦身 pass

主动扫债只在两个时机：交付前、接手陌生模块时。瘦身的安全边界是删叙述不删判据。

推导：高频全仓扫描本身是仪式债；从不主动扫，债又只在事故后才可见。两个时机是成本与可见性的交点。

判据：

• 扫描输出必须是可核对的数（问题注释 N 条/千行、最大文件、重复簇、门禁耗时），不是感受；先量化再动手
• 修剪红线：变异验证过的判据测试、事故背书的 fixture、归档区——一律不动
• 结构级重组（拆大文件、合并模块）交给 overhaul；需要恢复点的治理动作交给 butler

分工

场景	归属
写注释/文档/测试/新函数的那一刻	lean（本 skill）
项目结构、文档生命周期、变更安全	butler
一次性全仓深打磨	overhaul（引用本 skill 的判据做修剪）
把新踩的坑升格成规则	experience-to-spec（本 skill 的更新走它）
单次交付验收	review

规范依据

本规范依据 apps/skills/axiom/axiom.md 第零部·二（提炼方法）、第三部·三（变更与演化）、第三部·九（协作与知识）、第三部·十（简洁的最终定义）制定。提炼来源与置信度见 CREATION-LOG.md。