1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | clean-code-guard |
| 作者/维护者 | Ahmed Nagdy（GitHub：amElnagdy，任职于 OnTheGoSystems） |
| 来源链接 | https://github.com/amElnagdy/guard-skills/tree/master/skills/clean-code-guard |
| 许可证 | MIT（GitHub API 实测，仓库 LICENSE 文件原文一致） |
| GitHub Stars | 1,076（GitHub API 实测，2026-07-21；该数字是 guard-skills 整个仓库（含 clean-code-guard 在内的 5 个关联技能）的合计，不代表 clean-code-guard 单项自身热度） |
| Forks | 126（同上，仓库合计） |
| 最新版本 | v1.0.0（GitHub tag，尚未发布正式 Release） |
| 安装方式 | 第三方 Skills CLI（npx skills add），支持按技能名与目标 Agent 分别安装 |
2. 功能介绍与亮点
clean-code-guard 是 guard-skills 技能包中面向通用编程语言的代码质量把关技能，在 AI 编码 agent 生成或修改代码之后自动介入复查，也可在编写过程中即时套用规则。
- 传统工程规范落地：函数不超过 20 行、参数不超过 4 个、避免“data”“handler”等模糊命名；注释只解释“为什么”，删除复述代码本身或被注释掉的死代码；单一职责、开闭原则、子类契约保持等 SOLID 要点；重复的是“知识”而非文本的 DRY 判断；圈复杂度上限 10。
- 专门针对 AI 生成代码的失效模式：明确禁止大而化之的
try/except吞掉异常、要求在信任边界处校验输入、要求在调用前核实所用的库/API 在已安装版本中确实存在（拦截“幻觉 API”）、禁止生产代码里出现硬编码的“成功”返回值或测试用的 mock/fixture、要求重新推导而非复制修改已有函数、交付前清除死代码。 - 三种触发模式：guard-pass（生成后复查并直接修正）、live（编写时即时套用规则、出手前自查）、review（用户主动要求审查，只输出结构化问题清单不改代码）。
- 结构化输出：guard-pass/live 模式下逐条列出
<文件>[:<行号>] — <改动>，结尾用clean-code-guard: N fixed, M flagged或clean-code-guard: clean收尾；review 模式产出带证据与优先级的结构化发现。 - 零执行体设计：仓库 README 明确声明该技能包“no executable scripts, network calls, MCP server dependencies, or credentials”，全部内容是可直接阅读审计的 Markdown 规则文件加轻量展示元数据，已逐文件核对文件树，确认无脚本、无二进制。
3. 适用场景
所属分类：工程效率与代码质量。适合用 Claude Code、Codex 等编码 agent 完成日常开发的初中级开发者——尤其是习惯让 agent 一次性生成较大段代码、自己难以逐行复核的场景；也适合小团队在没有专职代码评审人力时，用它作为 AI 产出代码合并前的自动质检关卡。
4. 跨 Agent 兼容性
clean-code-guard 通过第三方 Skills CLI（vercel-labs/skills）分发安装，该工具自身文档的“Supported Agents”列表逐一列出了各 Agent 的安装路径：
- Claude Code：✅ 原生支持，
--agent claude-code，安装至.claude/skills/ - Codex：✅ 原生支持，
--agent codex，安装至.agents/skills/（全局~/.codex/skills/） - OpenClaw：✅ 原生支持，
--agent openclaw，安装至skills/（全局~/.openclaw/skills/） - Hermes Agent：✅ 原生支持，
--agent hermes-agent，安装至.hermes/skills/（全局~/.hermes/skills/）
判断依据来自 Skills CLI 自身文档记录的分发机制，四个目标生态均有明确的官方安装路径。
5. 推荐理由
针对 AI 生成代码特有的失效模式（幻觉 API、异常吞噬、伪造成功返回）做二次把关，补上传统代码规范检查覆盖不到的盲区。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | guard-skills 整个仓库创建约 6.5 周内获 1,076 Star、126 Fork，增长速度不慢；但 clean-code-guard 作为其中一个子目录没有独立可查的讨论量，星标应记在整个技能包名下 |
| 可用性 | 9 | 通过 Skills CLI 一条命令即可安装到指定 Agent，README 给出完整的按技能名安装、按 Agent 安装、更新与卸载说明；最近一次提交在 2026-07-04，距今约 2.5 周，维护尚属活跃；五个关联技能中 clean-code-guard 覆盖面最广、不依赖特定平台 |
| 安全性 | 9 | 见下方安全检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令及权限范围 | 无——技能本体不含任何可执行脚本，仅为 Markdown 规则文件加轻量 agents/openai.yaml 展示元数据；已逐文件核对仓库文件树确认 |
| ② 运行时是否联网外发数据 | 无——未发现网络请求代码，仓库自述明确声明不含 network calls |
| ③ API key/凭据存储方式 | 不需要任何凭据 |
| ④ 可疑指令/Prompt Injection 迹象 | 已逐条通读 clean-code-guard 的 SKILL.md 原文，均为常规评审规则表述，未发现要求越权操作、外发数据或篡改流程的可疑指令 |
| ⑤ 作者/组织信誉 | 作者 Ahmed Nagdy 任职于 OnTheGoSystems（WPML 多语言插件的开发公司），GitHub 账号自 2014 年活跃、505 名关注者；仓库存在真实外部贡献者提交的 issue/PR |
| ⑥ License | MIT，清晰明确 |
| ⑦ 最近维护时间 | 最近一次提交 2026-07-04，距今约 2.5 周 |
综合评分（三项均值）：8.0
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与 clean-code-guard 的差异 |
|---|---|---|
| code-review-and-quality（addyosmani/agent-skills） | 面向任意编程语言的通用五维（正确性/可读性/架构/安全/性能）代码评审技能 | 覆盖面更全面但不专门针对 LLM 生成代码的失效模式；clean-code-guard 把“幻觉 API”“异常吞噬”“伪造成功返回”等 AI 特有问题列为最高优先级检查项 |
| code-review-skill（awesome-skills） | 针对 React 19 / Vue 3 / Rust / TypeScript 等具体技术栈的代码评审技能 | 深耕特定框架的最佳实践，技术栈绑定强；clean-code-guard 语言无关，通用性更高，但换来的是框架级细节不如栈专属工具深 |
| differential-review（trailofbits/skills） | 调用另一模型对代码变更做跨模型交叉复核 | 解决的是“同一处代码用不同模型互相校验”，与具体检查规则无关；clean-code-guard 解决的是“单次评审该看哪些具体条目”，两者思路不同、可叠加使用 |
8. 用户评价
- @the_osps（X 平台，经 GitHub 项目趋势聚合站 trendshift.io 收录展示）：评价具体指出该技能“catches LLM code smells, over-abstraction, and hallucinated APIs”，与其 AI 失效模式检查的核心定位一致。
9. 其他补充
同仓库还包含面向测试代码的 test-guard、面向文档的 docs-guard，以及分别针对 WordPress、WooCommerce 生态的 wp-guard、woo-guard——检测到对应技术栈时可搭配启用，形成完整的生成后质检链条。
10. 安装使用方式
# 浏览包内全部技能
npx skills add amElnagdy/guard-skills --list
# 只安装 clean-code-guard
npx skills add amElnagdy/guard-skills --skill clean-code-guard
# 安装到指定 Agent
npx skills add amElnagdy/guard-skills --skill clean-code-guard --agent claude-code
npx skills add amElnagdy/guard-skills --skill clean-code-guard --agent codex
# 全局安装
npx skills add amElnagdy/guard-skills --skill clean-code-guard --global安装后无需重启，在对话中让 agent“用 clean-code-guard 检查这段代码”即可触发复查；也可以在编写风险较高的代码前显式调用，让规则在编写过程中即时生效（live 模式）。技能以复制形式安装，仓库更新后需手动执行 npx skills update clean-code-guard 刷新。
11. 注意事项
- 星标与讨论热度是 guard-skills 整个仓库（5 个关联技能）的合计数字，非 clean-code-guard 单项的独立热度
- 项目历史约 6.5 周，由个人开发者独立维护，长期维护记录尚短
- 安装依赖 Node.js 环境运行 Skills CLI（
npx），技能运行时本身不需要网络或凭据 - 规则集覆盖 Python/JS/PHP 等主流语言的通用模式，特定语言的编译器级静态检查（如类型系统错误）仍需专用 linter 配合，clean-code-guard 不替代它们