尧图网站建设 
agentic-awesome-skills 的 clean-code-guard 代码审查清单为 AI 生成代码建立结构化、可复现、可追溯的 Review 流程【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读当用户要求审查、审计、批判或评分代码而不是编写代码时clean-code-guard技能提供了一份结构化的走查清单review-checklist把一次笼统的帮我看看这段代码转化为按命名、注释、SOLID、DRY/KISS/YAGNI、AI 失败模式五个维度逐节推进、每条结论都带代码引用与具体修复方案的分级审查报告。本文基于该技能在仓库中的实现 review-checklist.md 与配套参考文件完整展开清单的每一处细节——从审查报告的强制输出模板、严重级别定义到 refactor/rewrite 预检、五段走查顺序、finding 的命名修复标准与结论被质疑时的处置方式——并逐条映射到仓库内 SKILL.md 与各 references/ 参考文件的源码级依据。读完你将掌握一套可以直接套用的 AI 代码审查方法论既能审查别人或模型写出的代码也能把同一条规则用于自己交付前的自检。说明该技能在仓库中存在两份镜像实现——plugins/agentic-awesome-skills-claude/skills/clean-code-guard 与 plugins/agentic-awesome-skills/skills/clean-code-guard下文路径统一以 claude 镜像为准两份内容一致。一、Review 模式的定位三种运行模式之一clean-code-guard不是一个审查专用技能而是一个三模式技能审查只是其中一种。根据 SKILL.md 的定义Guard-pass 模式推荐代码生成、编辑、重构或修复之后对照 Always-applied imperatives 检查 diff 或目标文件在提交/合并前修正违规项Live 模式显式用户在冒险编辑之前显式调用该技能在编写过程中就应用同样的规则交付前再跑一遍自检Review 模式触发式用户要求 review、audit、critique 或 rate 代码时对照 references/review-checklist.md 走查目标文件产出结构化 findings 报告除非被明确要求否则不编辑代码。三种模式共享同一套规则体系区别只在触发时机与产出物审查模式产出的是报告而 guard-pass 与 live 模式产出的是修复。本文聚焦 Review 模式即清单文件本身。二、审查报告的强制输出模板清单开篇就给出了一个必须逐字使用的输出模板目的是让每条 finding 都能被快速分诊triage。模板如下# Code review: file or scope ## Summary 2–3 sentence verdict: ship / needs work / rewrite Counts: N critical, M important, K nits (must equal the findings listed below) ## Critical findings must-fix before merge; omit this heading if none - file:line — tag: whats wrong [quoted code or behavior]. Fix: concrete change. continuation line only when the fix is code-sized ## Important findings should fix but not blocking; omit if none - ... ## Nits style, naming, minor structure; max 3, each with a fix; omit if none - ... ## Whats good 0–3 genuine, specific positives; omit on a clean review — do not manufacture praise ## Coverage One line per section: the findings it produced, or clean (walked it, found nothing). A blank section is an unbacked claim, not a pass — fill it before delivering. - Section A (naming functions): findings, or clean - Section B (comments formatting): findings, or clean - Section C (SOLID): findings, or clean - Section D (DRY/KISS/YAGNI): findings, or clean - Section E (AI failure modes): findings, or clean模板有三个容易踩坑的硬性约束Summary 中的计数必须与正文 listing 的条目数严格相等。写3 critical, 2 important却只列了 4 条报告即失效。Whats good只写 0–3 条真实的、具体的正面评价干净审查时直接省略该节——禁止为凑数而制造表扬。这一点与审查不是恭维的原则一致没有事实依据的正面评价同样是不可信的。Coverage 节必须逐节自报每一节要么列出它产出的 findings要么写clean已走查、无所获。空着不填的 section 等于没有依据的声明不允许交付。严重级别定义Critical关键安全、正确性、数据丢失、被吞掉的异常swallowed exceptions、硬编码的成功返回。Important重要带有维护成本的设计缺陷——SOLID 违规、过早抽象、参数爆炸、通用命名。Nit瑕疵风格问题、循环外的单字母变量名、公共 API 缺失文档契约。一条 finding 的成立条件清单强调每条 finding 必须携带被引用代码的原文quoted code或可观察行为以及一个具名的修复方案named fix。两者缺一即不算 finding直接丢弃。报告只统计成立的 finding永远不输出估计的质量评分、X% 更干净或可维护性指数——因为没有基线存在任何这样的数字都是编造的。这直接呼应 SKILL.md 中永远不要估计质量分数或百分比的自检要求。三、预检这次审查是 Refactor 还是 Rewrite在进入逐节走查之前必须先对审查类型做出分类因为它决定了行为变更behavior change是否在审查范围内Refactor review重构审查用户希望代码更干净而不是不一样。可观察行为必须不变——同样的输入、同样的输出、同样的异常、同样的副作用。如果建议会改变行为必须单独标记为一条Behavior change — confirm with author的 finding且不得与重构建议捆绑。清单引用了 Fowler《重构》的定义不改变可观察行为的前提下对软件内部结构的修改。Code-review for correctness正确性审查用户希望你找 bug。行为变更在范围内且若影响契约应标记为 Critical。如果无法判断用户想要哪一种先问再写报告。四、走查顺序Walk Order五个 Section 的完整检查点审查按固定顺序逐节推进每节都可拉取对应参考文件获取原则出处与更细规则。清单中的相对链接如naming-and-functions.md在仓库中对应 references/naming-and-functions.md 等文件走查时按需读取。Section A — 命名与函数依据 references/naming-and-functions.md对应 Clean Code 第 2、3 章执行 5 项检查扫描全部标识符标记通用命名data、result、item、temp、value、obj、info、helper、manager、utils以及没有限定词的handle_*、process_*、do_*。限定词版本的raw_csv_bytes、parsed_invoice是可接受的。对每个函数检查行数 ≤20参数 ≤4只做一件事单一抽象层级任一违反即标记。标记布尔标志参数boolean flag arguments——应拆分为两个函数参考参考文件中render(invoice, asHtml)拆成renderInvoiceHtml/renderInvoicePdf的示例。标记既返回值又模糊地改变可观察状态的函数CQS 违规——参考参考文件中save(record) - boolean的反例调用方无法区分布尔值含义应拆为save(record)与recordExists(recordId) - boolean。标记 getter 风格或 predicate 风格的函数却产生副作用——查询函数不得变更状态。参考文件还补充了自检清单所有名字能否不靠注释回答这代表什么能否再提取一个名字不重复正文的函数能说明正在做多件事是否有混合抽象层级参数 4 的提取配置对象等等。Section B — 注释与格式依据 references/comments-and-formatting.mdClean Code 第 4、5 章执行 5 项检查标记每一处复述代码的注释——// increment counter by one上方的counter 1零信息量还制造了两处维护点。注释只解释why从不解释what。标记注释掉的代码块——版本控制里都有注释掉的代码是毒药。标记步骤编号、First...、Then...脚手架注释——这是 LLM 产物的常见痕迹每一步都应该是带名字的函数调用名字本身就提供了结构。标记只复述签名的 docstring无契约内容——例如// Adds a and b and returns the result.。有价值的 docstring 记录契约可传什么、可返回什么、抛什么错误、有什么非显而易见的副作用参考参考文件中charge(paymentSourceId, amountCents)的契约式注释示例。标记与所在文件风格不一致之处——大小写、引号、导入顺序。文件用 snake_case 就不要引入 camelCase项目已有 HTTP 客户端、数据库封装或日志助手就复用而不是再引入一个。Section C — SOLID依据 references/solid.md逐项核对五原则(SRP) 任何类的方法服务于两个无关利益相关方注意 SRP 的正确表述是一个模块只对一个 actor 负责Martin 2014不是类只做一件事——一个 12 方法、只对数据访问层负责的InvoiceRepository满足 SRP一个 3 方法却混合 HTTP 调用、模板渲染、数据库写入的类不满足。(OCP) 是否存在随代码库增长而膨胀的类型标签条件/switch 分发添加新变体需要编辑现有函数就应改为 registry 或 strategy——参考参考文件中export()的if kind pdf链改为exporters { pdf: toPdf, ... }查表的示例。(LSP) 是否存在未实现/不支持操作失败、强化前置条件或弱化后置条件的子类LSP 是行为契约而非签名兼容前置条件在子类型中只能弱化后置条件与不变量只能强化。参考文件给出了经典的 Rectangle/Square 反例。(ISP) 是否存在具体客户端只用到其中一部分方法的接口胖接口造成传递耦合——参考参考文件中UserService的 create/read/update/delete/email/notify/audit/export 八方法接口审计方只需audit却传递依赖了 email 与 export 子系统。(DIP) 高层模块是否导入低层具体实现抽象是否与具体实现同包抽象应住在客户端的包里——参考参考文件中 billing 包内定义UserRepository抽象、sql 包实现并依赖它的示例依赖箭头是sql → billing而非billing → sql。参考文件还总结了 AI 生成代码破坏 SOLID 的典型模式单文件 god-moduleSRPDIPOCP、类型标签分发链OCP、子类中的 unsupported-operation 桩LSPISP、模块加载期导入具体 SDKDIP、mega-Service 接口ISPSRP、静默强化前置条件LSP、破坏不变量的一次性子类LSP、抽象所有权倒置DIP。Section D — DRY、KISS、YAGNI依据 references/dry-kiss-yagni.md执行 4 项检查(DRY) ≥5 行的重复块。但必须先确认是知识重复而非长得像——两个编码不同规则、看似相同的函数不构成 DRY 违规一条规则同时在代码 数据库 schema 文档中出现才是。参考文件的经验法则Rule of 3第一次见重复不提取第三次才提取此时才看清共享知识的真实形态。(DRY-Metz) 错误抽象共享函数中累积了 per-caller 分支和特例标志。按 Sandi Metz《The Wrong Abstraction》的处置先 re-inline 回各调用方 → 删除死分支 → 诚实保留一段时间重复 → 只有真正的共享知识显现后再重新抽象。重复远比错误抽象便宜。(KISS) 圈复杂度 10 或嵌套深度 5 的函数从分支与循环估算即可不需要精确度量。参考文件补充了可操作化标准认知复杂度目标 7新代码/上限 15圈复杂度 11–20 中度风险、21–50 高风险、50 不可测嵌套深度 ≤5函数长度参考值 50–60 行并需与复杂度上限配对使用。(YAGNI) 从未被调用的可选参数、只有一条路径的配置标志、只有一个实现的抽象、为可替换性而包装的库。参考文件列出了 Fowler 的四种成本构建、延迟、携带、修复与 AI 特有 YAGNI 陷阱无调用方的配置标志、两个已知用例的插件系统、只有一个调用方的通用 helper、从未传参的可选参数、投机性 async/批处理/缓存、单实现接口。Section E — AI 失败模式杠杆率最高的一节这是清单中权重最高的一节共 15 项检查全部以 references/ai-failure-modes.md 为依据——该文件按模式 / 来源 / 反例 / 规则四段式记录了 15 种 LLM 系统性产出坏代码的方式。清单检查点如下吞掉且不恢复的 catch-all 错误处理器—— Critical。参考文件模式 1LLM 因训练奖励机制而害怕异常倾向用宽泛 catch 返回 null/empty 掩盖真实故障——数据库宕机与用户没有邮箱变得无法区分。信任边界内部为类型/值做防御性守卫——系统已排除的情况、又在边界内部的守卫属于冗余边界上对外部/不可信输入的校验不是防御性守卫不标记。参考文件模式 2arXiv 2409.19182orderItems is null检查在契约已声明其为集合时永不触发。过早抽象——只有一个实现的 interface/factory。参考文件模式 3单一PaymentProcessor 抽象接口 工厂是纯仪式。注释污染——逐行复述、步骤编号脚手架、复述签名的文档注释。参考文件模式 4。重复本仓库 helper 中已有逻辑。参考文件模式 5GitClear 20255 行复制块 2021–2024 年间增长 8 倍。需要核实的 import 或库方法是否存在于已安装版本。参考文件模式 6Spracklen et al., USENIX Security 2516 模型平均包幻觉率 19.6%。通用命名与 Section A 交叉核对。参考文件模式 7。混合关注点的长函数与 Section A 交叉核对。参考文件模式 8GitClear 显示 AI 辅助提交中函数从 142 行增至 267 行、圈复杂度 4.2→8.1。5 参数函数未用配置对象与 Section A 交叉核对。参考文件模式 9。与所在文件风格不一致与 Section B 交叉核对。参考文件模式 10。死代码、未用 import、不可达分支、半成品实现。参考文件模式 11。生产代码中的硬编码成功返回、mock 夹具、假值—— Critical。参考文件模式 12getUserBalance(userId): return 1000 // TODO: actual provider call是函数体即虚构正确做法是raise NotImplemented(...)显式失败。禁止为使测试通过而禁用/跳过/修改测试。看起来像从相似函数复制粘贴的代码off-by-one、错误的 null 语义。参考文件模式 13看似正确的公式、范围或 null 语义错误根因是误解规格。对策是在写代码前先在注释里枚举用例empty / one / even / odd / null逐例验证。投机性可配置性——无调用方的标志、env var、可选参数。参考文件模式 14只有一个调用方却带formatpdf, templatenull, localeen...七个参数的renderInvoice。删除了边界校验或契约依赖的清理路径finally/close/defer/context-manager的简化——这是行为变更而非清理 —— Critical。参考文件还给出跨切面观察15 种模式中的 9 种1、2、3、9、12、14、15及 8、11 的部分同源于一个根因——模型偏向于产出更多代码、更多参数、更多守卫、更多抽象治疗方法是克制而非知识。写每一行之前问今天、按规格这行需要吗不需要就不写。五、每条 finding 的处置命名修复是准入门槛清单对 finding 的处理标准只有一个词Nameable可命名——必须能命名一个修复一个具体的代码变更或一个具体的结构性动作。可命名是门槛可写代码不是。举两个正反例不成立无命名替代丢弃This error handling could perhaps be more specific.成立L42 except Exceptionswallows the DB error → catchOperationalError, let the rest propagate.成立L88–140 processOrdermixes validation, pricing, persistence → extractvalidate()andprice().每条成立的 finding 都必须包含违规代码引用文件 行号、命名的原则或 references/ 中的 AI 失败模式、修复方案代码小则给代码否则给具名结构性动作、严重级别Critical / Important / Nit。六、当审查结论被质疑时引用来源、记录例外如果用户对某条 finding 提出异议引用相关 references/ 文件中的来源。清单的规则可追溯到一手出处——Uncle Bob、Fowler、Hunt Thomas、McCabe、Metz——以及 2024–2026 年发表的 LLM 代码生成研究完整书目见 references/sources.md。若用户有情境化理由覆盖规则将其记录为内联注释注释需命名原则、给出理由、写明回访触发条件revisit trigger。示例// clean-code exception: 4-arg ceiling — config DTO, all fields required at construction; revisit when an optional field appears.前缀仅为示意不是强制标签。回访触发条件的重要性在后续审查中一个格式良好的例外标记会把该 finding 降级为Documented exception不再重复标记但没有回访触发条件的标记本身就是一个 finding——没有出口的例外只是递延的债务。命名原则不要命名规则编号——编号对未来的读者毫无意义。七、这份审查不做的事边界声明清单在结尾明确划定了 Review 模式的职责边界防止审查被误用为万金油不运行 linter 或格式化工具——那是工具层的事不执行代码、不跑测试——发现测试缺失应作为 finding 提出No tests for the newchargepath — recommend adding.而不是代跑不强制语言特定风格Black、Prettier、PHPCS——除非用户明确要求否则遵循项目自身的风格工具。SKILL.md 的兼容性说明也印证了这一点该技能是便携式指令技能不需要 MCP 服务器、网络、API key、shell 或本地可执行文件它补充的是判断层judgement layer而机械验证交给项目自己的工具。八、从审查到自检同一套规则的双向复用Review 模式与 guard-pass 模式的规则同源区别只是方向相反审查把规则施加于既有代码自检把规则施加于即将交付的 diff。合并 SKILL.md 的交付前自检与清单可以得到一份通用的八项检查逐条对照 24 条 Always-applied imperatives 检查 diff修复每条违规新函数行数 ≤20参数 ≤4复杂度 ≤10名字揭示意图新注释解释why吗解释what就删掉新错误处理捕获的错误类型具体吗处理器除了静默返回还做了什么新抽象接口、工厂、基类、registry今天有第二个具体用户吗没有就内联读了你编辑的文件和至少一个邻居文件吗风格匹配吗有硬编码ok返回或夹具数据吗有就替换为真实实现或显式 unsupported 失败如果是重构可观察行为变了吗变了就是混入了 bug 修复拆分出来问用户。审查走查完毕后的收尾同样有格式要求逐条列出file[:line] — what changed最后以一行收束——clean-code-guard: N fixed, M flagged for author或clean-code-guard: clean无事可报时。这与清单只报成立的 finding、不报编造的评分是同一原则的两种表达。结语把质量判断从灵感变成流程clean-code-guard审查清单的价值不在于发明新原则——它的全部规则都可追溯到 Clean Code、SOLID、Fowler、Sandi Metz、McCabe 等经典来源——而在于把审查从凭感觉挑毛病变成逐节走查、逐条举证、逐项计数、逐条命名修复的可复现流程。对 AI 生成代码而言Section E 的 15 项 AI 失败模式检查吞异常、假成功返回、防御性守卫、包幻觉、注释污染、复制粘贴式推导……补充了经典原则覆盖不到的高杠杆维度而无引用与修复即非 finding无基线不评分数无回访触发条件的例外本身就是 finding这三条纪律则保证了报告本身经得起作者的反驳与后续轮次的复查。审查结束后把同一套标准装回 guard-pass 模式就能在代码进入审查之前先替它挡住大部分问题。如需深入建议按此顺序阅读仓库内参考文件references/ai-failure-modes.md最高杠杆审查者优先→ references/review-checklist.md本文所依主清单→ references/solid.md、references/dry-kiss-yagni.md、references/naming-and-functions.md、references/comments-and-formatting.md出处索引见 references/sources.md。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agentic-awesome-skills 的 clean-code-guard 代码审查清单：为 AI 生成代码建立结构化、可复现、可追溯的 Review 流程
agentic-awesome-skills 的 clean-code-guard 代码审查清单为 AI 生成代码建立结构化、可复现、可追溯的 Review 流程【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读当用户要求审查、审计、批判或评分代码而不是编写代码时clean-code-guard技能提供了一份结构化的走查清单review-checklist把一次笼统的帮我看看这段代码转化为按命名、注释、SOLID、DRY/KISS/YAGNI、AI 失败模式五个维度逐节推进、每条结论都带代码引用与具体修复方案的分级审查报告。本文基于该技能在仓库中的实现 review-checklist.md 与配套参考文件完整展开清单的每一处细节——从审查报告的强制输出模板、严重级别定义到 refactor/rewrite 预检、五段走查顺序、finding 的命名修复标准与结论被质疑时的处置方式——并逐条映射到仓库内 SKILL.md 与各 references/ 参考文件的源码级依据。读完你将掌握一套可以直接套用的 AI 代码审查方法论既能审查别人或模型写出的代码也能把同一条规则用于自己交付前的自检。说明该技能在仓库中存在两份镜像实现——plugins/agentic-awesome-skills-claude/skills/clean-code-guard 与 plugins/agentic-awesome-skills/skills/clean-code-guard下文路径统一以 claude 镜像为准两份内容一致。一、Review 模式的定位三种运行模式之一clean-code-guard不是一个审查专用技能而是一个三模式技能审查只是其中一种。根据 SKILL.md 的定义Guard-pass 模式推荐代码生成、编辑、重构或修复之后对照 Always-applied imperatives 检查 diff 或目标文件在提交/合并前修正违规项Live 模式显式用户在冒险编辑之前显式调用该技能在编写过程中就应用同样的规则交付前再跑一遍自检Review 模式触发式用户要求 review、audit、critique 或 rate 代码时对照 references/review-checklist.md 走查目标文件产出结构化 findings 报告除非被明确要求否则不编辑代码。三种模式共享同一套规则体系区别只在触发时机与产出物审查模式产出的是报告而 guard-pass 与 live 模式产出的是修复。本文聚焦 Review 模式即清单文件本身。二、审查报告的强制输出模板清单开篇就给出了一个必须逐字使用的输出模板目的是让每条 finding 都能被快速分诊triage。模板如下# Code review: file or scope ## Summary 2–3 sentence verdict: ship / needs work / rewrite Counts: N critical, M important, K nits (must equal the findings listed below) ## Critical findings must-fix before merge; omit this heading if none - file:line — tag: whats wrong [quoted code or behavior]. Fix: concrete change. continuation line only when the fix is code-sized ## Important findings should fix but not blocking; omit if none - ... ## Nits style, naming, minor structure; max 3, each with a fix; omit if none - ... ## Whats good 0–3 genuine, specific positives; omit on a clean review — do not manufacture praise ## Coverage One line per section: the findings it produced, or clean (walked it, found nothing). A blank section is an unbacked claim, not a pass — fill it before delivering. - Section A (naming functions): findings, or clean - Section B (comments formatting): findings, or clean - Section C (SOLID): findings, or clean - Section D (DRY/KISS/YAGNI): findings, or clean - Section E (AI failure modes): findings, or clean模板有三个容易踩坑的硬性约束Summary 中的计数必须与正文 listing 的条目数严格相等。写3 critical, 2 important却只列了 4 条报告即失效。Whats good只写 0–3 条真实的、具体的正面评价干净审查时直接省略该节——禁止为凑数而制造表扬。这一点与审查不是恭维的原则一致没有事实依据的正面评价同样是不可信的。Coverage 节必须逐节自报每一节要么列出它产出的 findings要么写clean已走查、无所获。空着不填的 section 等于没有依据的声明不允许交付。严重级别定义Critical关键安全、正确性、数据丢失、被吞掉的异常swallowed exceptions、硬编码的成功返回。Important重要带有维护成本的设计缺陷——SOLID 违规、过早抽象、参数爆炸、通用命名。Nit瑕疵风格问题、循环外的单字母变量名、公共 API 缺失文档契约。一条 finding 的成立条件清单强调每条 finding 必须携带被引用代码的原文quoted code或可观察行为以及一个具名的修复方案named fix。两者缺一即不算 finding直接丢弃。报告只统计成立的 finding永远不输出估计的质量评分、X% 更干净或可维护性指数——因为没有基线存在任何这样的数字都是编造的。这直接呼应 SKILL.md 中永远不要估计质量分数或百分比的自检要求。三、预检这次审查是 Refactor 还是 Rewrite在进入逐节走查之前必须先对审查类型做出分类因为它决定了行为变更behavior change是否在审查范围内Refactor review重构审查用户希望代码更干净而不是不一样。可观察行为必须不变——同样的输入、同样的输出、同样的异常、同样的副作用。如果建议会改变行为必须单独标记为一条Behavior change — confirm with author的 finding且不得与重构建议捆绑。清单引用了 Fowler《重构》的定义不改变可观察行为的前提下对软件内部结构的修改。Code-review for correctness正确性审查用户希望你找 bug。行为变更在范围内且若影响契约应标记为 Critical。如果无法判断用户想要哪一种先问再写报告。四、走查顺序Walk Order五个 Section 的完整检查点审查按固定顺序逐节推进每节都可拉取对应参考文件获取原则出处与更细规则。清单中的相对链接如naming-and-functions.md在仓库中对应 references/naming-and-functions.md 等文件走查时按需读取。Section A — 命名与函数依据 references/naming-and-functions.md对应 Clean Code 第 2、3 章执行 5 项检查扫描全部标识符标记通用命名data、result、item、temp、value、obj、info、helper、manager、utils以及没有限定词的handle_*、process_*、do_*。限定词版本的raw_csv_bytes、parsed_invoice是可接受的。对每个函数检查行数 ≤20参数 ≤4只做一件事单一抽象层级任一违反即标记。标记布尔标志参数boolean flag arguments——应拆分为两个函数参考参考文件中render(invoice, asHtml)拆成renderInvoiceHtml/renderInvoicePdf的示例。标记既返回值又模糊地改变可观察状态的函数CQS 违规——参考参考文件中save(record) - boolean的反例调用方无法区分布尔值含义应拆为save(record)与recordExists(recordId) - boolean。标记 getter 风格或 predicate 风格的函数却产生副作用——查询函数不得变更状态。参考文件还补充了自检清单所有名字能否不靠注释回答这代表什么能否再提取一个名字不重复正文的函数能说明正在做多件事是否有混合抽象层级参数 4 的提取配置对象等等。Section B — 注释与格式依据 references/comments-and-formatting.mdClean Code 第 4、5 章执行 5 项检查标记每一处复述代码的注释——// increment counter by one上方的counter 1零信息量还制造了两处维护点。注释只解释why从不解释what。标记注释掉的代码块——版本控制里都有注释掉的代码是毒药。标记步骤编号、First...、Then...脚手架注释——这是 LLM 产物的常见痕迹每一步都应该是带名字的函数调用名字本身就提供了结构。标记只复述签名的 docstring无契约内容——例如// Adds a and b and returns the result.。有价值的 docstring 记录契约可传什么、可返回什么、抛什么错误、有什么非显而易见的副作用参考参考文件中charge(paymentSourceId, amountCents)的契约式注释示例。标记与所在文件风格不一致之处——大小写、引号、导入顺序。文件用 snake_case 就不要引入 camelCase项目已有 HTTP 客户端、数据库封装或日志助手就复用而不是再引入一个。Section C — SOLID依据 references/solid.md逐项核对五原则(SRP) 任何类的方法服务于两个无关利益相关方注意 SRP 的正确表述是一个模块只对一个 actor 负责Martin 2014不是类只做一件事——一个 12 方法、只对数据访问层负责的InvoiceRepository满足 SRP一个 3 方法却混合 HTTP 调用、模板渲染、数据库写入的类不满足。(OCP) 是否存在随代码库增长而膨胀的类型标签条件/switch 分发添加新变体需要编辑现有函数就应改为 registry 或 strategy——参考参考文件中export()的if kind pdf链改为exporters { pdf: toPdf, ... }查表的示例。(LSP) 是否存在未实现/不支持操作失败、强化前置条件或弱化后置条件的子类LSP 是行为契约而非签名兼容前置条件在子类型中只能弱化后置条件与不变量只能强化。参考文件给出了经典的 Rectangle/Square 反例。(ISP) 是否存在具体客户端只用到其中一部分方法的接口胖接口造成传递耦合——参考参考文件中UserService的 create/read/update/delete/email/notify/audit/export 八方法接口审计方只需audit却传递依赖了 email 与 export 子系统。(DIP) 高层模块是否导入低层具体实现抽象是否与具体实现同包抽象应住在客户端的包里——参考参考文件中 billing 包内定义UserRepository抽象、sql 包实现并依赖它的示例依赖箭头是sql → billing而非billing → sql。参考文件还总结了 AI 生成代码破坏 SOLID 的典型模式单文件 god-moduleSRPDIPOCP、类型标签分发链OCP、子类中的 unsupported-operation 桩LSPISP、模块加载期导入具体 SDKDIP、mega-Service 接口ISPSRP、静默强化前置条件LSP、破坏不变量的一次性子类LSP、抽象所有权倒置DIP。Section D — DRY、KISS、YAGNI依据 references/dry-kiss-yagni.md执行 4 项检查(DRY) ≥5 行的重复块。但必须先确认是知识重复而非长得像——两个编码不同规则、看似相同的函数不构成 DRY 违规一条规则同时在代码 数据库 schema 文档中出现才是。参考文件的经验法则Rule of 3第一次见重复不提取第三次才提取此时才看清共享知识的真实形态。(DRY-Metz) 错误抽象共享函数中累积了 per-caller 分支和特例标志。按 Sandi Metz《The Wrong Abstraction》的处置先 re-inline 回各调用方 → 删除死分支 → 诚实保留一段时间重复 → 只有真正的共享知识显现后再重新抽象。重复远比错误抽象便宜。(KISS) 圈复杂度 10 或嵌套深度 5 的函数从分支与循环估算即可不需要精确度量。参考文件补充了可操作化标准认知复杂度目标 7新代码/上限 15圈复杂度 11–20 中度风险、21–50 高风险、50 不可测嵌套深度 ≤5函数长度参考值 50–60 行并需与复杂度上限配对使用。(YAGNI) 从未被调用的可选参数、只有一条路径的配置标志、只有一个实现的抽象、为可替换性而包装的库。参考文件列出了 Fowler 的四种成本构建、延迟、携带、修复与 AI 特有 YAGNI 陷阱无调用方的配置标志、两个已知用例的插件系统、只有一个调用方的通用 helper、从未传参的可选参数、投机性 async/批处理/缓存、单实现接口。Section E — AI 失败模式杠杆率最高的一节这是清单中权重最高的一节共 15 项检查全部以 references/ai-failure-modes.md 为依据——该文件按模式 / 来源 / 反例 / 规则四段式记录了 15 种 LLM 系统性产出坏代码的方式。清单检查点如下吞掉且不恢复的 catch-all 错误处理器—— Critical。参考文件模式 1LLM 因训练奖励机制而害怕异常倾向用宽泛 catch 返回 null/empty 掩盖真实故障——数据库宕机与用户没有邮箱变得无法区分。信任边界内部为类型/值做防御性守卫——系统已排除的情况、又在边界内部的守卫属于冗余边界上对外部/不可信输入的校验不是防御性守卫不标记。参考文件模式 2arXiv 2409.19182orderItems is null检查在契约已声明其为集合时永不触发。过早抽象——只有一个实现的 interface/factory。参考文件模式 3单一PaymentProcessor 抽象接口 工厂是纯仪式。注释污染——逐行复述、步骤编号脚手架、复述签名的文档注释。参考文件模式 4。重复本仓库 helper 中已有逻辑。参考文件模式 5GitClear 20255 行复制块 2021–2024 年间增长 8 倍。需要核实的 import 或库方法是否存在于已安装版本。参考文件模式 6Spracklen et al., USENIX Security 2516 模型平均包幻觉率 19.6%。通用命名与 Section A 交叉核对。参考文件模式 7。混合关注点的长函数与 Section A 交叉核对。参考文件模式 8GitClear 显示 AI 辅助提交中函数从 142 行增至 267 行、圈复杂度 4.2→8.1。5 参数函数未用配置对象与 Section A 交叉核对。参考文件模式 9。与所在文件风格不一致与 Section B 交叉核对。参考文件模式 10。死代码、未用 import、不可达分支、半成品实现。参考文件模式 11。生产代码中的硬编码成功返回、mock 夹具、假值—— Critical。参考文件模式 12getUserBalance(userId): return 1000 // TODO: actual provider call是函数体即虚构正确做法是raise NotImplemented(...)显式失败。禁止为使测试通过而禁用/跳过/修改测试。看起来像从相似函数复制粘贴的代码off-by-one、错误的 null 语义。参考文件模式 13看似正确的公式、范围或 null 语义错误根因是误解规格。对策是在写代码前先在注释里枚举用例empty / one / even / odd / null逐例验证。投机性可配置性——无调用方的标志、env var、可选参数。参考文件模式 14只有一个调用方却带formatpdf, templatenull, localeen...七个参数的renderInvoice。删除了边界校验或契约依赖的清理路径finally/close/defer/context-manager的简化——这是行为变更而非清理 —— Critical。参考文件还给出跨切面观察15 种模式中的 9 种1、2、3、9、12、14、15及 8、11 的部分同源于一个根因——模型偏向于产出更多代码、更多参数、更多守卫、更多抽象治疗方法是克制而非知识。写每一行之前问今天、按规格这行需要吗不需要就不写。五、每条 finding 的处置命名修复是准入门槛清单对 finding 的处理标准只有一个词Nameable可命名——必须能命名一个修复一个具体的代码变更或一个具体的结构性动作。可命名是门槛可写代码不是。举两个正反例不成立无命名替代丢弃This error handling could perhaps be more specific.成立L42 except Exceptionswallows the DB error → catchOperationalError, let the rest propagate.成立L88–140 processOrdermixes validation, pricing, persistence → extractvalidate()andprice().每条成立的 finding 都必须包含违规代码引用文件 行号、命名的原则或 references/ 中的 AI 失败模式、修复方案代码小则给代码否则给具名结构性动作、严重级别Critical / Important / Nit。六、当审查结论被质疑时引用来源、记录例外如果用户对某条 finding 提出异议引用相关 references/ 文件中的来源。清单的规则可追溯到一手出处——Uncle Bob、Fowler、Hunt Thomas、McCabe、Metz——以及 2024–2026 年发表的 LLM 代码生成研究完整书目见 references/sources.md。若用户有情境化理由覆盖规则将其记录为内联注释注释需命名原则、给出理由、写明回访触发条件revisit trigger。示例// clean-code exception: 4-arg ceiling — config DTO, all fields required at construction; revisit when an optional field appears.前缀仅为示意不是强制标签。回访触发条件的重要性在后续审查中一个格式良好的例外标记会把该 finding 降级为Documented exception不再重复标记但没有回访触发条件的标记本身就是一个 finding——没有出口的例外只是递延的债务。命名原则不要命名规则编号——编号对未来的读者毫无意义。七、这份审查不做的事边界声明清单在结尾明确划定了 Review 模式的职责边界防止审查被误用为万金油不运行 linter 或格式化工具——那是工具层的事不执行代码、不跑测试——发现测试缺失应作为 finding 提出No tests for the newchargepath — recommend adding.而不是代跑不强制语言特定风格Black、Prettier、PHPCS——除非用户明确要求否则遵循项目自身的风格工具。SKILL.md 的兼容性说明也印证了这一点该技能是便携式指令技能不需要 MCP 服务器、网络、API key、shell 或本地可执行文件它补充的是判断层judgement layer而机械验证交给项目自己的工具。八、从审查到自检同一套规则的双向复用Review 模式与 guard-pass 模式的规则同源区别只是方向相反审查把规则施加于既有代码自检把规则施加于即将交付的 diff。合并 SKILL.md 的交付前自检与清单可以得到一份通用的八项检查逐条对照 24 条 Always-applied imperatives 检查 diff修复每条违规新函数行数 ≤20参数 ≤4复杂度 ≤10名字揭示意图新注释解释why吗解释what就删掉新错误处理捕获的错误类型具体吗处理器除了静默返回还做了什么新抽象接口、工厂、基类、registry今天有第二个具体用户吗没有就内联读了你编辑的文件和至少一个邻居文件吗风格匹配吗有硬编码ok返回或夹具数据吗有就替换为真实实现或显式 unsupported 失败如果是重构可观察行为变了吗变了就是混入了 bug 修复拆分出来问用户。审查走查完毕后的收尾同样有格式要求逐条列出file[:line] — what changed最后以一行收束——clean-code-guard: N fixed, M flagged for author或clean-code-guard: clean无事可报时。这与清单只报成立的 finding、不报编造的评分是同一原则的两种表达。结语把质量判断从灵感变成流程clean-code-guard审查清单的价值不在于发明新原则——它的全部规则都可追溯到 Clean Code、SOLID、Fowler、Sandi Metz、McCabe 等经典来源——而在于把审查从凭感觉挑毛病变成逐节走查、逐条举证、逐项计数、逐条命名修复的可复现流程。对 AI 生成代码而言Section E 的 15 项 AI 失败模式检查吞异常、假成功返回、防御性守卫、包幻觉、注释污染、复制粘贴式推导……补充了经典原则覆盖不到的高杠杆维度而无引用与修复即非 finding无基线不评分数无回访触发条件的例外本身就是 finding这三条纪律则保证了报告本身经得起作者的反驳与后续轮次的复查。审查结束后把同一套标准装回 guard-pass 模式就能在代码进入审查之前先替它挡住大部分问题。如需深入建议按此顺序阅读仓库内参考文件references/ai-failure-modes.md最高杠杆审查者优先→ references/review-checklist.md本文所依主清单→ references/solid.md、references/dry-kiss-yagni.md、references/naming-and-functions.md、references/comments-and-formatting.md出处索引见 references/sources.md。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考