在代码交付前用 Clean Code/SOLID/DRY…

当 AI 或人写完、改完、重构完非平凡生产代码后，在展示、提交或合并前做一次质量守卫检查。

适用场景

解决思路

1. 选择模式：guard-pass 模式（默认，对 diff 或目标文件跑规则并修复后再交付）、live 模式（用户显式在写代码前调用，边写边应用规则并在交付前自检）、review 模式（用户要求 review/audit/critique/rate 时，走 references/review-checklist.md 产出结构化发现报告，未经要求不改代码）。
2. 命中不熟悉的规则、用户质疑规则、处于 review 模式、或代码触及特定原则（如子类化看 references/solid.md，去重看 references/dry-kiss-yagni.md）时，读取对应 references/ 文件；AI agent 优先读 references/ai-failure-modes.md。
3. 命名必须揭示意图：禁止使用 data、data2、result、result_final、item、temp、value、obj、info、helper、manager、utils 或无修饰的 handle_*/process_*/do_*，名字要回答为何存在、做什么。
4. 函数保持小：目标 ≤20 行、单一抽象层级、只做一件事；若能抽出不重复函数体的名字，说明父函数做了不止一件事。
5. 参数硬上限 4 个：到 5 个就引入 request/config 对象（record、struct、DTO 等）；禁止布尔标志参数，拆成两个函数。
6. 禁止输出参数：函数要么返回值（query），要么有副作用（command），不能两者兼有；command 名用动词，query 名用名词或 getter 风格。
7. 注释只解释 why，绝不解释 what：删除复述下一行的注释、步骤编号脚手架注释、被注释掉的代码（版本控制已存在）。
8. 匹配文件既有风格：写前读被编辑文件及至少一个相邻文件，镜像大小写、import 顺序、错误处理、日志、HTTP/DB 客户端选择，不引入第二种模式。
9. SRP：一个模块只对一个 actor 负责；若两个不相关子系统都伸手进同一个类，拆分它。
10. OCP：通过新增代码扩展而非修改；若新增变体需要在既有函数里再加一个 type-tag 分支，先重构为 registry、strategy 或多态分发。
11. LSP：子类不得拒绝父类契约；不得用 override 表示 not implemented/unsupported operation，不得在 override 中加强前置条件或削弱后置条件，否则继承关系就是错的。
12. DIP：抽象与客户端同住，不挨着实现；引入 interface、protocol 或抽象契约时，放在消费它的包里，而非具体类旁边。
13. DRY：删除重复的知识，而非重复的文本；长得像但编码不同规则的两个函数不算 DRY 违规，同一规则出现在代码+文档+schema 中才算。
14. 错误抽象比重复更糟：若抽象已为每个调用者的特例积累分支，先把它 re-inline 回调用者，删掉死分支，再重新抽象。
15. 复杂度上限：圈复杂度 ≤10，嵌套深度 ≤5，超过前先重构。
16. 禁止任何投机性设计：没有当下调用者的可选参数、config flag、env var、feature toggle、interface、factory、base class 一律不加；出现 enable_*、use_*_v2、*_mode 就删掉，直接交付具体行为。
17. 绝不用宽泛 catch-all 吞错误：只捕获你能恢复的具体错误类型，不能恢复就让它传播；除非函数契约明确记载，否则禁止在 catch 中返回 null/none/空成功。
18. 守边界、信契约：在信任边界（外部输入、请求/API payload、反序列化或跨进程数据、任何不可信来源）必须校验，即使 happy path 看起来没问题；边界内部不要为声明类型或调用方契约已排除的情况加 null 检查或运行时类型检查；判断是否加 guard 的标准不是“理论上会不会错”，而是“不可信数据能否到达这里”。
19. 验证每个 import 和外部调用：调用库方法前确认它在已安装版本中存在（读包、查 lockfile，或 import 后 inspect），不要凭 API“应该长什么样”生成代码。
20. 生产代码中禁止硬编码“成功”返回或 mock fixture：规格说明做真实工作的函数不得返回 {"status": "ok", ...} 或罐头数据；无法实现就用语言的 unimplemented/unsupported-operation 机制显式失败并说明；绝不禁用、跳过或削弱测试来让它通过。
21. 重新推导，不要从相似代码复制：想复制函数再改时停下，从规格重新推导；off-by-one 和错误 null 语义的 bug 几乎都从 copy-from-similar 进入。
22. 写边界用例前先枚举：对任何范围、off-by-one、null/empty/one/many、奇偶、unicode/字节边界，先在注释里写出用例清单，再在代码中逐一覆盖。
23. 交付前清除死代码：跑 linter 或 grep 检查未用 import、未用符号、不可达分支和“以防万一”的导出并删除；今天没人调用的函数不能为“某天”而活。
24. 写前先读：在不熟悉的仓库写代码前，读将编辑的文件、一个相邻文件，以及任何项目规则文件（CLAUDE.md、AGENTS.md、README 的 conventions 段），使用项目既有的 helper、错误类型和日志。
25. 几行代码能覆盖的不要加新依赖：加包前先查标准库、已安装依赖、以及几行本地代码能否胜任；新依赖是永久的维护与供应链面，只在它承担你不该重写的真实复杂度（如密码学、解析、时区）时才加，绝不为省十行而加。
26. 底线不可为简化而砍：信任边界的校验与净化、防止数据丢失的错误处理、安全措施（授权、输出转义、参数化查询、密钥处理）、用户明确要求的行为——删掉其中任何一项都是行为变更而非清理，要么保留，要么标记并询问。
27. 重构纪律：用户要求清理、简化或重构既有代码时，保持可观察行为不变——相同输入产生相同输出、相同异常、相同副作用、相同顺序保证；重构中若发现 bug，单独标记并在改动前询问；bug 修复与重构是两种操作，绝不捆绑在同一次改动中。
28. 交付前自检：逐条走 imperatives 1–24 并修复所有违规；新函数检查行数 ≤20、参数 ≤4、复杂度 ≤10、命名揭示意图；新注释问是否解释 why，解释 what 就删；新错误处理检查捕获类型是否具体、handler 是否不只是静默返回；新抽象（interface、factory、base class、registry）问今天是否有第二个具体使用者，没有就 inline；确认读过被编辑文件及至少一个相邻文件且风格匹配；确认没有硬编码 "ok" 返回或 fixture 数据，有则替换为真实实现或显式 unimplemented/unsupported-operation 失败；若是重构，确认未改变可观察行为，改了就是捆绑了 bug 修复，拆出来并询问用户。
29. 自检后向用户展示守卫已运行（guard-pass 与 live 模式；review 模式走自己的发现格式）：逐条列出修复为 `<file>[:<line>] — <what changed>`（行号不稳定则省略），最后一行收尾 `clean-code-guard: <N> fixed, <M> flagged for author`，无触发则 `clean-code-guard: clean`；只报告实际做过的改动，绝不估算质量分数或百分比。
30. 用户质疑规则时，引用对应 references/ 文件中的来源名，仅在需要 URL 时用 references/sources.md；若用户有上下文相关的覆盖理由（如 config DTO 的构造函数确实需要 8 个参数），在代码注释中记录被覆盖的原则、原因和 revisit trigger；没有 revisit trigger 的例外注释本身就是下次检查的发现项。
31. 排障：任务偏概念而非产码时不应用本技能，直接回答概念；review 模式若开始只产出风格反馈，改用 references/review-checklist.md 并优先行为 bug、脆弱性和可维护性风险；规则与项目显式约定冲突时遵循项目约定，仅在会让未来维护者意外时记录例外；觉得技能太宽泛时先用 frontmatter 排除项，不要往这个通用守卫技能里加运行时特定规则。

适用边界 · 注意事项

• 事实性/概念性问题、CI/工具配置、git 工作流、运行/调试测试、纯架构讨论、散文写作、数据分析，以及测试代码 review（改用 test-guard）。
• 不要用它替代项目 linter、formatter、类型检查器或测试运行器——机械验证用项目自带工具，本技能只管代码质量与 review 的判断层。
• review 模式下未经要求不要编辑代码。