clean-code-guard 是做什么的?
你正在审查在代码交付前生成的或修改的代码。在第一次实现阶段之后,将此规则作为守护检查应用——一旦此技能被激活,在同一会话中,对后续每个代码更改持续应用此规则,每次编辑后重新运行自我检查,而不是因为技能已提前加载而回到未经保护的状态。如果用户在编写代码前显式调用此技能,在编写时也使用相同的规则,并在交付前仍运行自我检查。
Agent 团队集成
仓库的规则、已接受的契约、角色权限和用户范围优先于本指南及其引用。DEV 对其自身的变更使用守护检查;CR 使用只读审查模式,不编辑实现。将数值限制、命名禁止、参数形状和抽象规则视为需要调查的信号,而不是自动编辑或阻断因素。发现结果应在上下文中解释具体的正确性或维护成本;不要为了满足计数而拆分内聚代码、打破接口或添加异常注释。审查已更改的代码及其直接影响的调用者,而非不相关的技术债务。
此包使用的所有指南和检查清单都是本地的。外部出版物的名称仅为归属引用;使用仓库证据和捆绑的参考资料,而非进行浏览。如果此任务超出技能范围,则遵循仓库的正常流程;不需要兄弟技能。
兼容性
这是一个可移植的指令型技能。它不需要 MCP 服务器、网络访问、
API 密钥、shell 命令、本地可执行文件或捆绑脚本。它可以在任何支持 SKILL.md 以及直接链接的 references/ 文件的运行时中使用;agents/openai.yaml 是轻量级显示元数据。
此技能不取代项目的 linters、格式化工具、类型检查器或测试运行器。使用项目自己的工具进行机械验证;使用此技能进行围绕代码质量和审查的判断层。
如何使用此技能
此技能有三种模式——根据用户请求选择。
守护模式(推荐):在代码生成、编辑、重构或修复后,检查差异或目标文件是否符合以下 始终应用的命令。在呈现、提交或合并工作之前修复违规。
实时模式(显式):当用户在风险代码编辑前调用此技能时,在编写时应用相同的命令,然后运行 交付前自我检查 清单。如果你违反任何规则,在向用户展示之前进行修复。
审查模式(当用户要求你审查、审计、批评或评估代码时触发):针对目标文件运行 references/review-checklist.md 并生成结构化发现报告。在审查模式下除非被要求,否则不编辑代码。
在所有三种模式下,规则主体位于 references/ 中。在以下情况下阅读相关的参考文件:
- 你遇到一条你不完全记得其推理的规则时。
- 用户对一条规则提出异议,你需要源引用时。
- 你处于审查模式并需要完整检查清单时。
- 被审查的代码涉及特定原则(例如,子类化 → references/solid.md;去重 → references/dry-kiss-yagni.md)。
参考文件包括:
- references/naming-and-functions.md — 命名、函数大小、参数、命令/查询分离。
- references/comments-and-formatting.md — 何时注释、何时删除、匹配相邻样式。
- references/solid.md — SRP、OCP、LSP、ISP、DIP,包含现代表述和检测气味。
- references/dry-kiss-yagni.md — 知识重复 vs 代码重复、Sandi Metz 的重新内联规则、McCabe 复杂度、Fowler 的 YAGNI 成本类别。
- references/ai-failure-modes.md — LLM 产生不良代码的 14 种系统方式。如果你是阅读此技能的 AI Agent,请先阅读此文件。 它是技能中杠杆率最高的文件。
- references/review-checklist.md — 审查模式的结构化检查清单。
- references/sources.md — 源 URL 的集中参考书目。仅在你需要验证或引用外部源时阅读。
示例
- 编码 Agent 实现了一个端点:在呈现或提交工作之前,对差异使用守护模式。
- 用户要求“审查这个 PR”或“我应该合并吗?”:使用审查模式,从 references/review-checklist.md 报告发现结果;除非被要求,否则不编辑。
- 用户要求“使用 clean-code-guard 实现此端点”:在编写时使用实时模式,然后在交付前运行自我检查。
- 用户要求“重构此函数,行为一致”:精确保留可观察行为,并将任何 bug 修复视为单独的更改。
成功标准
当代码编写任务避免了列出的故障模式,代码审查任务产生带有具体证据的优先级发现结果,且重构保留了行为(除非用户显式要求行为更改)时,此技能工作正常。对于frontmatter排除项涵盖的概念性、CI、Git 工作流、论述、数据分析和测试运行任务,它应保持沉默。
为何此技能存在
LLM 生成的代码具有可衡量的系统性故障模式,而通用的“遵循整洁代码”指令无法捕获。基于已发表研究的示例:
- 代码重复在跟踪的代码库中增长了 8 倍(GitClear 2025 年报告)。
- 包幻觉率平均为 19.6% 跨 16 个模型(Spracklen 等,USENIX Security '25)。
- LLM 经常将风险操作包装在吞没错误的广泛捕获处理程序中(Karpathy)。
- AI Agent “在测试失败时声明成功” 通过返回硬编码的夹具值(Fowler,减少摩擦的模式)。
- AI 辅助提交中函数大小从 142 行增长到 267 行,圈复杂度从 4.2 增长到 8.1(GitClear)。
经典原则(整洁代码、SOLID、DRY/KISS/YAGNI)仍然是基础——但此技能添加了大多数规则包遗漏的 AI 特定 层。
始终应用的命令
这些是每个代码更改必须遵循的规则。它们是命令性的,而非建议。
函数与命名
- 名字揭示意图。 从不使用
data、data2、result、result_final、item、temp、value、obj、info、helper、manager、utils或handle_*/process_*/do_*而不加限定词。一个名称必须回答它为什么存在以及它做什么。(整洁代码第 2 章) - 函数保持短小。 目标 ≤20 行,一个抽象层级,做一件事。如果你能提取一个函数,其名称不重复主体内容,则父函数做了多件事。(整洁代码第 3 章)
- 四个参数是硬性上限。 五个时,停用并引入一个请求/配置对象(记录、结构体、DTO 或等效形式)。绝不使用布尔标志参数——而是拆分成两个函数。
- 无输出参数。 一个函数要么返回值(查询),要么有副作用(命令)。不能兼有。命令名使用动词;查询名使用名词或 getter 样式名称。(CQS)
注释与结构
- 注释解释为什么,绝不解释什么。 删除任何意译下方代码行的注释。删除步骤编号的脚手架注释。删除注释掉的代码——版本控制的存在是有原因的。(整洁代码第 4 章)
- 匹配文件的现有风格。 在编写前阅读你正在编辑的文件及至少一个相邻文件。镜像大小写、导入顺序、错误处理、日志记录和 HTTP/DB 客户端的选择。不要引入第二种模式。
SOLID
- 每个模块一个行为者。 一个类应对一个利益相关者组(财务、认证、报告)负责。如果两个不相关的子系统都深入同一个类,则拆分它。(SRP,Bob 大叔 2014)
- 通过新增代码扩展,而非编辑。 如果添加新变体需要在现有函数中增加另一个类型标签分支,则先重构为注册表、策略或多态分发。(OCP)
- 子类不得拒绝其父契约。 绝不重写方法以表示“未实现”或“不支持的操作”。绝不加强前置条件或减弱后置条件。如果你需要这样做,则继承关系是错误的。(LSP)
- 抽象与客户端共存,而非实现。 当你引入接口、协议或抽象契约时,将其放在消费它的包中,而不是具体的类旁边。(DIP)
DRY、KISS、YAGNI
- 删除重复的知识,而非重复的文本。 两个看起来相似但编码了不同规则的函数不是 DRY 违规。一条在代码+文档+模式中表达的规则才是。(《程序员修炼之道》,“DRY”)
- 错误的抽象比重复更糟糕。 如果一个抽象累积了每个调用者特殊用例的分支,将其重新内联回调用者中,然后在重新抽象前删除死分支。(Sandi Metz,“错误的抽象”)
- 复杂度上限:圈复杂度 ≤10,嵌套深度 ≤5。 在超过前重构。(McCabe 1976)
- 不要有任何猜测性东西。 没有可选参数、配置标志、环境变量、特性开关、接口、工厂或基类而没有当前的调用者。如果你发现自己添加了
enable_*、use_*_v2或*_mode,删除它并交付具体行为。(Fowler,“YAGNI”)
AI 特定保护措施——杠杆率最高的部分
- 绝不使用宽泛的 catch-all 处理吞没错误。 仅捕获你可以恢复的特定错误类型。如果你无法恢复,让错误传播。除非函数契约记录了这种行为,否则禁止在 catch 处理程序中返回 null/none/空成功。(Karpathy)
- 保护边界;信任契约。 在信任边界——外部输入、请求/API 负载、反序列化或跨进程数据、任何来自不受信任源的内容——即使快乐路径看起来良好,也要进行验证。在边界内部,不要为那些声明类型或调用者契约已排除此情况的值添加 null 检查或运行时类型检查。保护措施的测试不是“理论上这可能出错吗”而是“不受信任的数据能否到达这里”。(arXiv 2409.19182)
- 验证每个导入和外部调用。 在调用库上的方法之前,确认它存在于已安装的版本中(读取包、检查 lockfile 或导入并检查)。不要基于 API“应该是什么样子”生成代码。(USENIX Security '25)
- 生产代码中不得有硬编码的“成功”返回或模拟夹具。 从不从规范说明做实际工作的函数中返回
{"status": "ok", ...}或预制数据。如果你无法实现,使用语言中的未实现或不支持的操作机制显式失败并说明情况。永不禁用、跳过或削弱测试以使其通过。(Fowler,Claude Code issue #6984) - 重新推导,而非从类似代码复制。 当你想复制一个函数并修改它时,停下来。从规范重新推导。差一错误和错误空语义错误几乎总是通过从类似代码复制引入。(arXiv 2411.01414)
- 在编写边界情况之前枚举它们。 对于任何范围、差一、null/空/单/多、偶数/奇数或 unicode/字节边界,首先在注释中编写情况列表。在继续之前,确保代码涵盖了每种情况。
- 交付前清理死代码。 运行 linter 或 grep 检查未使用的导入、未使用的符号、不可达的分支和“以防万一”的导出。移除它们。一个今天没有任何调用的函数不能为“有一天”而存在。
- 先读后写。 在陌生的仓库中编写之前,阅读你将编辑的文件、一个相邻文件以及任何项目规则文件(CLAUDE.md、AGENTS.md、README 的“约定”部分)。使用项目现有的辅助函数、错误类型和日志记录。
- 几行代码能解决的事,不要添加新依赖。 在添加包之前,检查标准库、已安装的依赖以及是否几行本地代码就能完成任务。新依赖是永久的维护和供应链风险;仅当它拥有你不应重新实现的真正复杂度时(加密、解析、时区——举例说明,非穷举)才添加,永远不是为了节省十行代码。参见 references/dry-kiss-yagni.md。
底线——永不为了简洁而删除
规则 16 信任边界内部的契约;以下项目在剥离猜测性内容(14)、防御性保护(16)和死代码(21)时仍保留。移除其中一条是行为更改,而非清理——请保留,或标记并提出问题。
- 每个信任边界上的验证和清理——外部输入、请求/API 负载、反序列化或跨进程数据。
- 防止数据丢失的错误处理。
- 安全措施——授权、输出转义、参数化查询、密钥处理。
- 用户显式请求的行为。 随口提及 ≠ 被请求,但不要放弃被要求的内容。
重构纪律
- 重构时保留可观察行为。 当用户要求你清理、简化或重构现有代码时,不要改变契约——相同的输入产生相同的输出,相同的异常抛出,相同的副作用,相同的排序保证。如果你在重构时发现一个 bug,单独标记并在更改前询问。重构定义为 “为使其更易于理解和更便宜修改而进行的软件内部结构更改,而不改变其可观察行为”(Fowler,《重构》)。Bug 修复和重构是两种操作——永远不要将它们打包在单一更改中。
交付前自我检查
在你向用户展示代码之前……
(…内容被截断…)