Community编程与开发github.com

clean-code-guard

编码技能。在代码交付前,使用整洁代码、SOLID、DRY、KISS、YAGNI 以及 LLM 特有的故障模式检查,对任何编程语言的已生成或已修改的代码进行审查。最适合在 Agent 编写、编辑、重构或修复代码之后、呈现、提交或合并结果之前被动使用。当用户要求“审查这个 PR”、“合并安全吗?”、“让代码更整洁”、“审计这段代码”、“重构此代码”、“修复这个 bug”或编码 Agent 生成了实现代码后使用。

clean-code-guard 是什么?

clean-code-guard 是一个可移植的指令型 AI Agent 技能,专注于在代码交付前强制执行代码质量检查。它整合了经典的整洁代码原则(如 SOLID、DRY、KISS、YAGNI)与 AI 特有的故障模式检查,旨在捕获 LLM 生成代码中常见的系统性缺陷。该技能支持三种模式:守护模式(在代码生成后自动检查并修复违反规则的地方)、实时模式(在编写代码时实时应用规则)和审查模式(只读审查代码并生成结构化报告)。它不依赖 MCP 服务器、网络访问、API 密钥或本地脚本,可在任何支持 SKILL.md 的运行时中使用。该技能尤其适用于 GitHub Copilot、Cursor、Claude Code 等 AI 编码 Agent,帮助开发者在提交或合并代码前发现重复代码、异常处理不当、过度工程化等问题。核心规则共 24 条,涵盖函数命名、参数数量、注释规范、SOLID 原则、DRY/KISS/YAGNI、AI 特有保护措施(如不吞没错误、不硬编码成功返回、不从类似代码复制等)以及重构纪律,交付前必须执行自我检查清单。

兼容平台✓Claude Code✓Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/EthanZ-ZJ/dsh-agent-team-roles/tree/HEAD/templates/software-dev/skills/cr/clean-code-guard

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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)。

参考文件包括:

示例

  • 编码 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 特定 层。

始终应用的命令

这些是每个代码更改必须遵循的规则。它们是命令性的,而非建议。

函数与命名

  1. 名字揭示意图。 从不使用 data、data2、result、result_final、item、temp、value、obj、info、helper、manager、utils 或 handle_*/process_*/do_* 而不加限定词。一个名称必须回答它为什么存在以及它做什么。(整洁代码第 2 章)
  2. 函数保持短小。 目标 ≤20 行,一个抽象层级,做一件事。如果你能提取一个函数,其名称不重复主体内容,则父函数做了多件事。(整洁代码第 3 章)
  3. 四个参数是硬性上限。 五个时,停用并引入一个请求/配置对象(记录、结构体、DTO 或等效形式)。绝不使用布尔标志参数——而是拆分成两个函数。
  4. 无输出参数。 一个函数要么返回值(查询),要么有副作用(命令)。不能兼有。命令名使用动词;查询名使用名词或 getter 样式名称。(CQS)

注释与结构

  1. 注释解释为什么,绝不解释什么。 删除任何意译下方代码行的注释。删除步骤编号的脚手架注释。删除注释掉的代码——版本控制的存在是有原因的。(整洁代码第 4 章)
  2. 匹配文件的现有风格。 在编写前阅读你正在编辑的文件及至少一个相邻文件。镜像大小写、导入顺序、错误处理、日志记录和 HTTP/DB 客户端的选择。不要引入第二种模式。

SOLID

  1. 每个模块一个行为者。 一个类应对一个利益相关者组(财务、认证、报告)负责。如果两个不相关的子系统都深入同一个类,则拆分它。(SRP,Bob 大叔 2014)
  2. 通过新增代码扩展,而非编辑。 如果添加新变体需要在现有函数中增加另一个类型标签分支,则先重构为注册表、策略或多态分发。(OCP)
  3. 子类不得拒绝其父契约。 绝不重写方法以表示“未实现”或“不支持的操作”。绝不加强前置条件或减弱后置条件。如果你需要这样做,则继承关系是错误的。(LSP)
  4. 抽象与客户端共存,而非实现。 当你引入接口、协议或抽象契约时,将其放在消费它的包中,而不是具体的类旁边。(DIP)

DRY、KISS、YAGNI

  1. 删除重复的知识,而非重复的文本。 两个看起来相似但编码了不同规则的函数不是 DRY 违规。一条在代码+文档+模式中表达的规则才是。(《程序员修炼之道》,“DRY”)
  2. 错误的抽象比重复更糟糕。 如果一个抽象累积了每个调用者特殊用例的分支,将其重新内联回调用者中,然后在重新抽象前删除死分支。(Sandi Metz,“错误的抽象”)
  3. 复杂度上限:圈复杂度 ≤10,嵌套深度 ≤5。 在超过前重构。(McCabe 1976)
  4. 不要有任何猜测性东西。 没有可选参数、配置标志、环境变量、特性开关、接口、工厂或基类而没有当前的调用者。如果你发现自己添加了 enable_*、use_*_v2 或 *_mode,删除它并交付具体行为。(Fowler,“YAGNI”)

AI 特定保护措施——杠杆率最高的部分

  1. 绝不使用宽泛的 catch-all 处理吞没错误。 仅捕获你可以恢复的特定错误类型。如果你无法恢复,让错误传播。除非函数契约记录了这种行为,否则禁止在 catch 处理程序中返回 null/none/空成功。(Karpathy)
  2. 保护边界;信任契约。 在信任边界——外部输入、请求/API 负载、反序列化或跨进程数据、任何来自不受信任源的内容——即使快乐路径看起来良好,也要进行验证。在边界内部,不要为那些声明类型或调用者契约已排除此情况的值添加 null 检查或运行时类型检查。保护措施的测试不是“理论上这可能出错吗”而是“不受信任的数据能否到达这里”。(arXiv 2409.19182)
  3. 验证每个导入和外部调用。 在调用库上的方法之前,确认它存在于已安装的版本中(读取包、检查 lockfile 或导入并检查)。不要基于 API“应该是什么样子”生成代码。(USENIX Security '25)
  4. 生产代码中不得有硬编码的“成功”返回或模拟夹具。 从不从规范说明做实际工作的函数中返回 {"status": "ok", ...} 或预制数据。如果你无法实现,使用语言中的未实现或不支持的操作机制显式失败并说明情况。永不禁用、跳过或削弱测试以使其通过。(Fowler,Claude Code issue #6984)
  5. 重新推导,而非从类似代码复制。 当你想复制一个函数并修改它时,停下来。从规范重新推导。差一错误和错误空语义错误几乎总是通过从类似代码复制引入。(arXiv 2411.01414)
  6. 在编写边界情况之前枚举它们。 对于任何范围、差一、null/空/单/多、偶数/奇数或 unicode/字节边界,首先在注释中编写情况列表。在继续之前,确保代码涵盖了每种情况。
  7. 交付前清理死代码。 运行 linter 或 grep 检查未使用的导入、未使用的符号、不可达的分支和“以防万一”的导出。移除它们。一个今天没有任何调用的函数不能为“有一天”而存在。
  8. 先读后写。 在陌生的仓库中编写之前,阅读你将编辑的文件、一个相邻文件以及任何项目规则文件(CLAUDE.md、AGENTS.md、README 的“约定”部分)。使用项目现有的辅助函数、错误类型和日志记录。
  9. 几行代码能解决的事,不要添加新依赖。 在添加包之前,检查标准库、已安装的依赖以及是否几行本地代码就能完成任务。新依赖是永久的维护和供应链风险;仅当它拥有你不应重新实现的真正复杂度时(加密、解析、时区——举例说明,非穷举)才添加,永远不是为了节省十行代码。参见 references/dry-kiss-yagni.md。

底线——永不为了简洁而删除

规则 16 信任边界内部的契约;以下项目在剥离猜测性内容(14)、防御性保护(16)和死代码(21)时仍保留。移除其中一条是行为更改,而非清理——请保留,或标记并提出问题。

  • 每个信任边界上的验证和清理——外部输入、请求/API 负载、反序列化或跨进程数据。
  • 防止数据丢失的错误处理。
  • 安全措施——授权、输出转义、参数化查询、密钥处理。
  • 用户显式请求的行为。 随口提及 ≠ 被请求,但不要放弃被要求的内容。

重构纪律

  1. 重构时保留可观察行为。 当用户要求你清理、简化或重构现有代码时,不要改变契约——相同的输入产生相同的输出,相同的异常抛出,相同的副作用,相同的排序保证。如果你在重构时发现一个 bug,单独标记并在更改前询问。重构定义为 “为使其更易于理解和更便宜修改而进行的软件内部结构更改,而不改变其可观察行为”(Fowler,《重构》)。Bug 修复和重构是两种操作——永远不要将它们打包在单一更改中。

交付前自我检查

在你向用户展示代码之前……

(…内容被截断…)

相关技能