clean-code-guard 参考文献图谱：agentic-awesome-skills 中代码质量守卫技能的论证基石与知识溯源

clean-code-guard 参考文献图谱agentic-awesome-skills 中代码质量守卫技能的论证基石与知识溯源【免费下载链接】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,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skillsclean-code-guard是 agentic-awesome-skills 仓库plugins/agentic-awesome-skills-claude 下内置的一个代码质量守卫技能在代码提交前对生成或修改的生产代码执行 Clean Code、SOLID、DRY、KISS、YAGNI 以及 LLM 特有失败模式的逐条核查。而 references/sources.md 正是这个技能全部规则的中央参考书目——26 条文献按经典代码整洁与设计LLM 代码生成研究度量与验证三大类组织为技能里的每一条命令式规则提供可溯源的一手论证。读完本文你将完整掌握这份书目的全貌每一条文献讲了什么、支撑了技能中的哪条规则、对应的源码位置在哪里并理解规则文件只写来源名称、sources.md 统一映射 URL这一引用机制的用意从而能在代码评审或规则争议中快速定位证据。sources.md 在技能体系中的定位在深入 26 条文献之前先厘清这份书目在技能中的角色。根据 SKILL.mdclean-code-guard的技能规则体全部存放在references/目录下共 7 个文件references/naming-and-functions.md —— 命名、函数规模、参数数量、命令/查询分离references/comments-and-formatting.md —— 何时写注释、何时删除、对齐邻居代码风格references/solid.md —— SRP、OCP、LSP、ISP、DIP 及各自的检测气味references/dry-kiss-yagni.md —— 知识重复与文本重复的区别、Sandi Metz 的重新内联规则、McCabe 复杂度、Fowler 的 YAGNI 成本分类references/ai-failure-modes.md —— LLM 产生坏代码的 15 种系统性方式技能中优先级最高的文件references/review-checklist.md —— 评审模式的结构化走查清单references/sources.md —— 中央参考书目本文主题。关键设计是其他参考文件在正文里只用来源名称如Fowler, Yagni、McCabe 1976、USENIX Security 25而不是内联 URL这样规则文本保持可读只有当需要验证或引用外部来源时才打开sources.md查找对应 URL。这一点在 SKILL.md 中有明确说明central bibliography for source URLs. Read it only when you need to verify or cite an external source中央书目仅当你需要验证或引用外部来源时阅读。sources.md将全部文献划分为三类下文逐一展开并把每条文献映射回它在仓库规则文件中的实际引用位置构成一张规则 ↔ 文献的溯源图谱。经典代码整洁与设计十条奠基性文献这一组文献是技能中经典原则层SKILL.md 中的规则 1–14 及 24的源头覆盖 Robert C. MartinUncle Bob的Clean Code与 SOLID 体系、Martin Fowler 的三篇短论、Hunt Thomas 的 DRY 定义以及 Sandi Metz 对过早抽象的批判。1. Clean Code 样章——命名与函数规则的直接来源Pearson 官方发布的Clean Code样章是 naming-and-functions.md 和 comments-and-formatting.md 的成文基础这两份文件分别对应书的第 2、3 章与第 4、5 章。它支撑了 SKILL.md 中最前端的几条硬性规则规则 1名称揭示意图禁止无修饰的data、result、item、temp、obj、helper、manager、utils、handle_*/process_*/do_*来源标注为Clean Code Ch. 2SKILL.md规则 2函数保持小目标 ≤20 行、单层抽象、只做一件事来源标注为Clean Code Ch. 3SKILL.md规则 5注释只解释 why删除逐行转述代码的注释、删除步骤编号脚手架注释、删除被注释掉的代码来源标注为Clean Code Ch. 4SKILL.md。在naming-and-functions.md中这一来源被扩展为 N1–N6 六条命名准则与 F1–F10 十条函数准则其中值得注意的细化包括N2 禁止匈牙利命名法与I接口前缀、N4 单字母变量仅允许出现在短循环作用域内、F1 中 Uncle Bob 更苛刻的 2–4 行目标、F3 的一层抽象定义不要在同一个函数里混入 HTTP 调用、SQL 查询、正则解析与业务规则这四层、F6 禁止布尔标志参数应拆分为两个函数。而在comments-and-formatting.md中它被细化为 C1 可接受注释清单法律头、意图、后果警告、带工单号的 TODO、契约式文档、放大说明与 C2 必删注释清单转述代码、噪音注释、横幅注释、闭合括号注释、归属日志、注释掉的代码、Step 1/Step 2脚手架。2. FowlerCommand Query Separation命令查询分离Martin Fowler 的 CQS 短文支撑了 SKILL.md规则 4No output arguments. A function either returns a value (query) or has a side effect (command). Never both.与naming-and-functions.md的 F7/F8 两条准则。F7 给出的反面例子是save(record) - boolean——调用者无法区分布尔值到底表示保存成功还是记录是否存在正确写法是拆成save(record)命令无返回值与recordExists(recordId)查询返回布尔。F8 进一步要求 getter 风格、finder 风格或谓词风格的函数不得产生可观察的状态突变。3. FowlerRefactoring——重构的权威定义Fowler 的《重构》一书为技能提供了两个关键锚点。其一是 SKILL.md规则 24引用的一手定义重构是改变软件内部结构、使其更易理解且修改成本更低、同时不改变其可观察行为的变更SKILL.md并由此派生bug 修复与重构是两种操作绝不打包进同一次变更的纪律review-checklist.md 的评审前置检查也复用了这一定义要求重构评审中任何改变行为的建议都必须单独标注为Behavior change — confirm with author。其二是 dry-kiss-yagni.md 中三的规则Rule of 3的底层原理——不要过早抽象这一原则出自《重构》的目录与重构实践。4. FowlerYAGNI——四类成本模型Fowler 的 bliki 短文《Yagni》2015 年 5 月是技能中 YAGNI 规则的唯一权威来源支撑 SKILL.md规则 14没有当今天调用方的可选参数、配置开关、环境变量、特性开关、接口、工厂或基类一律不要写发现enable_*、use_*_v2、*_mode就删掉并落地具体行为。dry-kiss-yagni.md 将该文的核心贡献提炼为Fowler 的四类成本构建成本Cost of build对最终无人使用的功能所做的前期分析、编码与测试延迟成本Cost of delay机会成本——本该做而未做的创收工作携带成本Cost of carry额外复杂度拖慢每一次后续修改与调试修复成本Cost of repair预设功能被证明是错误时拆除它并偿还其积累的技术债。这四类成本构成了dry-kiss-yagni.md中AI 特有 YAGNI 陷阱清单配置开关、双已知用例的插件系统、单调用方的通用助手、从不被传的可选参数、投机性异步/批处理/缓存、单实现的前置接口的理论依据。5. The Pragmatic ProgrammerDRY 的真义Pragmatic ProgrammerHunt Thomas官方 DRY 摘录为技能提供了 DRY 的权威定义在 dry-kiss-yagni.md 中原样引用Every piece of knowledge must have a single, unambiguous, authoritative representation within a system系统中的每条知识都必须有单一、无歧义、权威的表示。该文件随后明确纠正了最常见的误读不要有任何重复代码是错误的——DRY 说的是知识意图的重复而非文本的重复。两个长得像但编码了不同规则的函数不构成 DRY 违规一条规则同时出现在代码、数据库 schema 与文档中才是。这直接支撑 SKILL.md规则 11并衍生出四条值得标记的文本信号≥5 行的相同 token 序列、同一正则/SQL/URL 字面量出现 ≥3 处、同一魔法数/字符串在常量模块外出现 ≥3 次、同一校验分支跨同级模块重复。6. Sandi Metz错误抽象比重复更贵Sandi Metz 的博文《The Wrong Abstraction》2016 年 1 月是技能中反过早抽象论点最锋利的武器其核心断言duplication is far cheaper than the wrong abstraction重复远比错误抽象便宜被原样收录进 dry-kiss-yagni.md。它支撑了 SKILL.md规则 12错误抽象比重复更糟。若一个抽象为每个调用方的特例积累了分支先把它重新内联回调用方、删掉死分支再重新抽象并给出了四步补救流程重新内联 → 删除逐调用方的死分支 → 诚实容忍一段重复 → 直到真正共享的知识变得明显时才重新抽象。naming-and-functions.md的 F10 也反向引用了这条推论两个函数共享非平凡代码块时应抽取但何时不该抽——参见 Metz 的错误抽象警告。7–11. SOLID 五原则Uncle Bob 体系与四篇配套文献sources.md为 SOLID 收录了五条文献Uncle Bob 的《Principles of OOD》归档页五原则的总入口以及 SRP、OCP、LSP、DIP 四篇配套文献全部映射到 solid.md 与 SKILL.md 的规则 7–10SRP规则 7solid.md 采用 Uncle Bob 2014 年硬化后的定义——一个模块应只对一个、且仅一个 actor 负责老说法是一个类只应有一个变更理由。其常见误读被明确纠正SRP 是围绕利益相关者的聚合不是方法数量问题——一个只对数据访问层负责的 12 方法InvoiceRepository满足 SRP而一个混有 HTTP 调用、模板渲染和 DB 写入的 3 方法类不满足。OCP规则 8solid.md 溯源到 Bertrand Meyer 1988 年《面向对象软件构造》的原初表述并注明 Martin 将其重心转向多态抽象而非实现继承支撑新变体应通过新代码而非编辑到达的规则以及导出器改用注册表/查表而非类型标签 if 链的修复示例。LSP规则 9solid.md 完整引用 Liskov Wing 1994 年的形式化定义并给出行为的细化规则子类型只能弱化前置条件、强化后置条件与不变量、参数逆变返回协变配以经典的 Rectangle/Square 反例——结论是Square 在行为意义上不是 Rectangle组合而非继承。ISPsources.md 虽未为 ISP 单列 URL它归在 Principles of OOD 归档页下但 solid.md 仍给出了完整论述客户端不应被迫依赖其不使用的接口并以 audit logger 被迫依赖 email 与 export 子系统的 fat interface 为例。DIP规则 10solid.md 逐字引用 Martin 1996 年 C Report 论文的两条款高层不依赖低层、抽象不依赖细节并纠正DIP 就是使用 DI 容器的误读——DIP 是源码依赖的方向问题纯构造注入即可满足用了 Spring 也可能违反。SKILL.md 规则 10 据此要求抽象接口应放在消费它的包里而不是放在具体实现旁边。这五条文献共同支撑了 solid.md 中AI 生成代码如何典型地破坏 SOLID的八条映射God-module、类型标签派发链、unsupported-operation 桩、模块加载期的具体 SDK import、Mega-Service 接口、覆写时静默强化前置条件、破坏不变量的便利子类、抽象归属倒置。LLM 代码生成研究与现场报告十三条证据这是sources.md中最具时代特征的一组文献也是clean-code-guard区别于通用 clean-code 规则包的价值所在。它们被集中引用进 ai-failure-modes.md15 种 LLM 失败模式以及 SKILL.md 的Why this skill exists一节。SKILL.md 开篇即给出四条可量化的研究证据代码重复 2021–2024 年增长 8 倍、包幻觉率平均 19.6%、LLM 倾向用宽泛 catch-all 吞掉错误、AI agent 通过返回硬编码夹具值在测试失败时宣布成功。GitClear 2025重复代码 8 倍增长的定量基线GitClear《AI Copilot Code Quality 2025》是一份基于 2.11 亿行代码的纵向分析被 ai-failure-modes.md 称为目前关于 LLM 代码质量最强的量化结果2021–2024 年复制粘贴的 ≥5 行代码块增加8 倍复制/粘贴行占比从 8.3% 升至 12.3%重构占比从 25% 跌至不足 10%。同一报告还支撑了失败模式 8 的两个数字AI 辅助提交中文件平均规模从 142 行增至 267 行圈复杂度从 4.2 增至 8.1该数字同时出现在 SKILL.md。它对应 SKILL.md规则 19从相似代码复制再修改时停下来按规格重新推导和失败模式 5 的规则写函数前先搜索仓库中已有的相似实现≥5 行匹配就抽取或调用。USENIX Security 25包幻觉率 19.6%Spracklen 等人的《Package Hallucinations》USENIX Security 2025测试了 16 个模型平均包幻觉率19.6%商业模型约 5%开源模型约 21%支撑了 SKILL.md规则 17验证每一个 import 与外部调用调用库方法前确认它在所安装版本中真实存在读包、查 lockfile 或 import 后检查不要基于 API应该长什么样生成代码与失败模式 6。值得注意的技能内延伸是 SKILL.md 将该数字与AI 特有失败模式直接挂钩——幻觉不是偶发事故而是以接近 1/5 概率出现的系统性行为。AI-Generated Code Considered Harmful防御性守卫的病理arXiv 2409.19182 支撑了 SKILL.md规则 16与失败模式 2LLM 倾向于为类型系统或调用图已经排除的情形添加 null 检查、运行时类型检查与真值检查。技能给出的测试标准是——守卫不是问理论上是否可能出错而是问不可信数据能否到达这里在信任边界之内信任契约在边界之外外部输入、请求/API 载荷、反序列化或跨进程数据校验是必须的而非防御性冗余。规则 16 与失败模式 1 共享同一奖励信号机制解释训练时传播异常会惩罚模型模型因此学会抑制异常。A Deep Dive Into LLM Code Generation Mistakes语义错误分类学arXiv 2411.01414 对 LLM 代码生成错误提出 7 大类分类其中 4 类是非语法语义错误——这些是此前研究漏掉的部分根因是对规格的误解。它支撑了失败模式 11死代码、未用 import、半实现与失败模式 13貌似正确但公式/范围/null 语义略错的代码常来自从相似函数复制再修改并对应 SKILL.md规则 19与规则 20写任何边界情形前先在注释里枚举 case 清单cases: empty / one / even / odd / null。Simon Willison 的观察也被引用以说明为何貌似正确比幻觉更危险幻觉往往大声失败而 plausible-but-wrong 的语义代码会正常运行。Fowler减少 AI 辅助开发摩擦与宣布成功Fowler 的《Patterns for Reducing Friction in AI-Assisted Development》支撑了两个失败模式模式 3过早抽象来源标注为 Fowler 的 overeagerness添加未请求功能这一文档化的 AI 模式与模式 12declaring success despite failing tests 与 brute-force fixes。它同时出现在 SKILL.md支撑规则 18永远不要在规格要求做真实工作的函数里返回{status: ok, ...}或硬编码夹具做不到就显式失败并说明缺什么绝不为了通过测试而禁用、跳过或削弱测试。Claude Code issue #6984系统性 mock 数据偏差Anthropic Claude Code 的 issue #6984 标题为《Systematic Mock Data Generation Bias》支撑失败模式 12 与 SKILL.md规则 18后半段。它记录了 AI agent 系统性倾向以 mock 夹具替代真实实现的现象技能给出的修复范式是函数体写成raise NotImplemented(Wire to billing.getBalance() after auth is available)这类显式失败而不是返回虚构的return 1000。Karpathy 与异常抑制的奖励信号假说Karpathy 关于异常抑制的公开评论支撑了失败模式 1 与 SKILL.md规则 15绝不使用宽泛 catch-all 吞掉错误。只捕获你能够恢复的具体错误类型无法恢复就让错误传播。除非函数契约明确记载否则禁止从 catch 处理器返回 null/none/空成功。技能对根因的表述是训练期间的奖励信号导致模型害怕异常、倾向抑制异常——因此数据库宕机与用户没有邮箱变得不可区分ai-failure-modes.md。Code Needs Comments注释污染的证据arXiv 2402.13013《Code Needs Comments》支撑失败模式 4注释污染。技能引用的关键数据是LLM 生成的注释平均约 5 个描述性单词而作者写下的混合意图注释平均 19 词——即 LLM 注释回答是什么而非为什么。这与 SKILL.md规则 5和comments-and-formatting.md的 C1/C2 清单相互印证也回应了 HN 上的观察让 agentic 代码变丑最常见的原因就是过度使用注释。工具质量对比Copilot / CodeWhisperer / ChatGPTarXiv 2304.10778 对 Copilot、CodeWhisperer、ChatGPT 三类 AI 辅助代码生成工具进行了代码质量评估被 ai-failure-modes.md 引用以佐证失败模式 8长函数混杂多重关注点与模式 9参数爆炸并非单一工具特有而是 AI 辅助代码生成的整体现象。幻觉缓解的两条路径API 文档与分类学arXiv 2407.09726《On Mitigating Code LLM Hallucinations with API Documentation》与 arXiv 2409.20550《LLM Hallucinations in Practical Code Generation》共同支撑失败模式 6前者提供以 API 文档缓解幻觉的实证路径印证规则 17 中读包、查 lockfile的验证策略后者给出实用代码生成中幻觉的完整分类学。命名退化When Names Disappear 与 Neural Variable Name Repair两篇 2025 年底的 arXiv 论文共同支撑失败模式 7通用、无意图命名与 SKILL.md规则 1arXiv 2510.03178《When Names Disappear》论证语义名称在生成过程中充当锚点——名称消失时生成质量随之退化这解释了为何 LLM 代码会过量产出data、result、item这类占位名arXiv 2512.01141《Neural Variable Name Repair》把通用标识符列为名称修复模型的显式修复目标从侧面确认 LLM 代码过量产出通用名为系统性现象而非偶然。naming-and-functions.md的 N6 清单data、result、item、value、temp、obj、info、helper、manager、utils、handle_*/process_*/do_*正是为对抗这两篇论文描述的现象而设并允许带限定的版本raw_csv_bytes、parsed_invoice。Vibe Coding in Practice长函数的积累机制arXiv 2512.11922《Vibe Coding in Practice》记录了 AI 辅助的vibe coding如何通过架构不一致积累技术债其典型症状就是单个数百行的函数处理多个不相关关注点、由多个 AI 生成片段拼装而成——这与 GitClear 的函数行数 142→267 的数据相互印证共同支撑失败模式 8 与 SKILL.md规则 2函数 ≤20 行、单层抽象。度量与验证三条可量化的判据clean-code-guard的可操作性的一个重要来源是KISS 这类模糊原则被量化为具体数值门槛而这三条文献正是这些数值的出处全部集中在 dry-kiss-yagni.md。McCabe 圈复杂度NIST 235rMcCabe 1976 年的原创度量报告NIST 235r支撑了 SKILL.md规则 13复杂度上限圈复杂度 ≤10嵌套深度 ≤5超限前先重构与 dry-kiss-yagni.md 的阈值分档11–20 中风险21–50 高风险50 不可测试。技能同时指出它作为结构下限仍有价值但在人类可读性判断上应让位于认知复杂度——两者冲突时优先认知复杂度。SonarSource 认知复杂度SonarSource 的《Cognitive Complexity》白皮书支撑了技能对 KISS 的首要操作化指标认知复杂度 ≤10/函数绿地代码目标 7上限 15超限必须重构。dry-kiss-yagni.md 将其描述为2026 年的主导度量已被 SonarQube、Biome、ReSharper 采纳因为它测量的是代码有多难理解而非独立路径的数量——这与人类代码评审的直觉一致。ReSharper 圈复杂度阈值指南JetBrains ReSharper 的圈复杂度阈值指南是 dry-kiss-yagni.md 中分档阈值11–20 / 21–50 / 50的直接出处与 NIST 235r 相互补充McCabe 提供度量本体ReSharper 指南提供经过工程实践的阈值建议。技能在使用建议上给出明确分工认知复杂度用于人类可读性判断圈复杂度用于是否可测试判断。来源引用机制与实战用法理解这份书目如何被消费比记住 26 个条目本身更重要。技能在三个层面使用sources.md其一规则文件只写名称。所有参考文件与 SKILL.md 中的规则尾注都以来源名称出现——(Clean Code Ch. 2)、(Fowler, Yagni)、(McCabe 1976)、(Pragmatic Programmer, DRY)、(SRP, Uncle Bob 2014)、(USENIX Security 25)——正文保持可读URL 统一收敛到sources.md一处维护。这让规则 → 文献 → URL成为一条清晰的单向链。其二用户质疑规则时用来举证。根据 SKILL.md当用户对某条规则提出异议时先引用对应参考文件里的来源名称仅在需要 URL 时才打开sources.md。技能的辩护逻辑是这些规则来自一手来源Uncle Bob、Fowler、Hunt Thomas、McCabe、Metz和 2024–2026 年已发表的 LLM 代码生成研究而非网络传闻。其三例外必须带复审触发条件。若用户因上下文有理由覆盖某条规则例如配置 DTO 的构造函数确实需要 8 个参数应在代码注释中记录被覆盖的原则、理由和复审触发条件revisit trigger。值得注意的是一个没有复审触发条件的例外注释本身就是下次守卫通过的 finding——没有出口的权衡只是被推迟的债务SKILL.md。结语一份书目如何让守卫可辩护clean-code-guard之所以把 26 条文献组织成一份中央书目本质是为了让每一条命令式规则都可以被追问、被辩护、被追溯规则 1–14 与 24 站在 Uncle Bob、Fowler、Hunt Thomas、McCabe、Metz 的肩膀上规则 15–23 则被 2024–2026 年的 LLM 代码生成研究逐一背书。当你在代码评审中引用(Karpathy)拒绝一个 catch-all 处理器或在规格分歧中引用(USENIX Security 25)要求验证 import 时你实际上是在调用这份书目背后的完整证据链。查看这份书目时建议按 SKILL.md 的提示顺序阅读先读优先级最高的 ai-failure-modes.md再按需翻阅各经典原则文件最后仅在需要核实外部来源时才回到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,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考