software-clean-code-standard

Clean Code 标准

这项技能是本仓库共享技能的权威 Clean Code 标准。它定义了稳定的规则 ID（CC-*）、如何在评审中应用这些规则，以及如何通过语言叠加层和明确的例外安全地扩展标准。

判断重于教条：本标准中的 CC-* 规则经久耐用（耦合与内聚、命名、小型接口、明确的错误处理）。数字迷信——严格的函数长度上限、“注释是一种坏味道”、绝对化地应用 DRY——则不然。Robert C. Martin 的 Clean Code（第 2 版，2025 年）和 John Ousterhout 的 A Philosophy of Software Design 在一场公开发表的辩论中，就函数大小和注释问题持有不同意见（参见 references/code-quality-operational-playbook.md § 14）；应用规则 ID 的意图，而非某本书中的具体数字要求，并了解何时不该重构（同一参考资料的 § 14.3）。

---

快速参考

任务	工具/框架	命令	使用时机
引用标准	CC-* 规则 ID	不适用	PR 评审评论、设计讨论、事后复盘
对反馈分类	CC-NAM、CC-ERR、CC-SEC 等	不适用	统一反馈，避免陷入“风格之争”
补充技术栈细节	语言叠加层	不适用	基础规则对某种语言/框架过于笼统时
允许例外	豁免记录	不适用	必须违反规则并明确记录风险时
复用共享检查清单	assets/checklists/	不适用	需要与产品无关的评审/发布检查清单时
复用实用模式	references/*-utilities.md	不适用	提取共享的身份验证/日志记录/错误处理/弹性/测试工具时

何时使用这项技能

• 在团队和不同语言之间制定或执行 Clean Code 规则。
• 将具体的评审意见或扫描器发现映射到 CC-* ID；评审工作流请使用 software-code-review。
• 构建自动化：将代码检查工具/CI 门禁映射到 CC-* ID。
• 解决反复出现的评审争议：就规则 ID、适用范围和例外达成一致。

何时不使用这项技能

• 深入安全审计 → 对 CC-SEC-* 基准之外的 OWASP/SAST 深入分析，请使用 software-security-appsec。
• 评审工作流机制 → PR 工作流、评审者分配和反馈模式，请使用 software-code-review。
• 重构执行 → 分步重构模式和质量门禁，请使用 qa-refactoring。
• 架构决策 → 代码级规则之外的系统级权衡，请使用 software-architecture-design。

工作流

1. 判断请求涉及基础规则、叠加层还是例外。
2. 如果实际问题涉及安全、评审流程或重构机制，则转交给相邻技能。
3. 在提出新的措辞或自动化方案前，先以现有的 CC-* 规则为依据；映射工具发现时，应依据其失效模式，而不仅仅是工具给出的严重性。
4. 应用相关标准、叠加层或豁免模式，并明确说明适用范围和理由。
5. 添加或修订长期标准前，对照导航参考资料进行交叉检查。

规则应用检查清单

在评审中引用或执行 CC-* 规则时：

• 明确引用规则 ID（而非转述）——例如 CC-SEC-01、CC-ERR-03（两位数字的 CC-<CAT>-<NN>；仅限目录中存在的 ID——python3 scripts/check_cc_ids.py [paths] 会在遇到未知 ID 时失败）
• 说明适用范围：文件、模块、服务或整个仓库
• 如果仓库使用特定语言且基础规则含糊不清，则应用语言叠加层
• 明确说明阻塞还是建议：正确性/安全问题会阻止合并；风格问题仅供参考
• 如果确实无法在不进行架构变更的情况下满足规则，则记录豁免路径

决策树：基础规则、叠加层还是例外

Feedback needed: [What kind of guidance is this?]
    ├─ Universal, cross-language rule? → Add/modify `CC-*` in `references/clean-code-standard.md`
    │
    ├─ Language/framework-specific nuance? → Add overlay entry referencing existing `CC-*`
    │
    └─ One-off constraint or temporary tradeoff?
        ├─ Timeboxed? → Add waiver with expiry + tracking issue
        └─ Permanent? → Propose a new rule or revise scope/exception criteria

---

可选：AI/自动化

重构证据门槛。

不要仅仅因为代码看起来不够时髦就判定违反规则。指出它导致的维护问题：重复修改、隐藏的副作用、不安全的耦合、难以阅读的控制流，或经测量确认的复杂度热点。如果拟议的重写缺少能保持行为不变的测试，或无法具体降低修改风险，就保留稳定但不够优雅的代码；应记录范围明确的例外，而不是制造不必要的改动。

• 通过规则级示例映射自动化检查结果；确定优先级前先检查代码。
• AI 辅助建议仅供参考；由人工审查者通过规则引用批准或拒绝（https://conventionalcomments.org/）。
• 针对新的阻断性违规，以代码库基线为门槛；将代码质量下降和冗长程度视为经过审查的变化趋势，而非普遍适用的阈值（指标指南）。

审查 AI 生成的代码

AI 生成的代码需要遵循相同的 CC-* 标准，并且还要格外留意以下模式：

模式	CC-* 映射	检测方式
虚构的导入	CC-SEC-05	npm info / pip index / 类型检查失败
过时或已弃用的 API	CC-DEP-01	编译器警告、检查变更日志
缺少错误处理路径	CC-ERR-01, CC-ERR-04	没有 catch/finally、没有 null 防护、没有超时
过早抽象	CC-FUN-06	只有一个调用点的包装器、未使用的泛型
自信但错误的注释	CC-DOC-01, CC-DOC-02	与实现不符的文档字符串
安全反模式	CC-SEC-08, CC-SEC-03	查询中使用字符串拼接、硬编码令牌
静默回退或空 catch	CC-ERR-01	错误路径返回看似合理的默认值，调用方却无法感知失败
弱化或删除断言	CC-TST-01, CC-TST-03	反转需求后，测试不再失败
重复的辅助函数或范围扩张	CC-FUN-05, CC-FUN-06	在现有行为旁新增平行辅助函数，或抽象没有第二处用途

关于 Agent 修改纪律和用于检测回归的测试，请参阅 coding-behavior.md。有关详细的幻觉检查，请参阅 references/code-quality-operational-playbook.md § 11.3。

---

导航

资源

• references/clean-code-standard.md — CC-* 规则定义；请先打开以查找或引用规则 ID
• references/code-quality-operational-playbook.md — 操作手册：LLM 代码审查、复杂度管理、同行审查控制、审慎判断而非教条（旧版 RULE-01–13 已废弃；§ 1 将它们映射到 CC-*）
• references/working-effectively-with-legacy-code-operational-checklist.md — 安全修改缺少测试或测试薄弱的代码（Feathers）
• references/refactoring-operational-checklist.md — 保持行为不变的重构方案及前提条件（Fowler）
• references/design-patterns-operational-checklist.md — 何时 GoF 模式带来的收益足以抵消其复杂度，以及何时会过度设计
• references/functional-programming-patterns.md — Result/Either 类型、pipe/compose、不可变性、纯函数、铁路导向编程、CC-* 规则映射
• references/code-complexity-metrics.md — 圈复杂度／认知复杂度、Halstead 指标、嵌套深度、工具（ESLint、Biome、Oxlint、SonarQube、Ruff）、重构触发条件
• data/sources.json — 用于审查、安全设计、可观测性和现代工具的当前外部参考资料（优先使用官方文档）

模板

• assets/checklists/backend-api-review-checklist.md
• assets/checklists/secure-code-review-checklist.md
• assets/checklists/frontend-performance-a11y-checklist.md
• assets/checklists/mobile-release-checklist.md
• assets/checklists/ux-design-review-checklist.md

实用模式

• references/utility-patterns.md — 何时以及如何提取实用工具，而不是重复编写代码（具体实用工具下方的决策指南）
• references/auth-utilities.md
• references/error-handling.md
• references/config-validation.md
• references/resilience-utilities.md
• references/logging-utilities.md
• references/observability-utilities.md
• references/testing-utilities.md
• references/llm-utilities.md

相关技能

• ../software-code-review/SKILL.md — 审查工作流与判断；引用 CC-* ID
• ../software-security-appsec/SKILL.md — 深入探讨基线 CC-SEC-* 之外的安全问题
• ../qa-refactoring/SKILL.md — 重构执行模式与质量门禁
• ../software-architecture-design/SKILL.md — 系统级权衡与边界

---

时效性协议

• 对于指定的代码检查器或扫描器，在将发现映射到 CC-* 之前，请检查其官方规则文档以及项目解析的版本。
• 对于拟议的 CI 门禁，请检查扫描器当前对基线／新代码的支持情况，并将其规则覆盖范围与仓库现有检查进行比较。
• 报告所选的规则映射、任何不受支持的规则或迁移风险，以及用于核实的来源。

已知陷阱

• 将“整洁代码”仅视为风格偏好，忽视正确性、可观测性、安全性和变更安全。
• 以整洁为名，强制执行一刀切的抽象规则，增加间接层并降低运行时的清晰度。
• 将特定语言的格式化工具和代码检查工具的意见混入通用指南，却未保留稳定的 CC 规则意图。
• 当明确的仓库规则 ID 另有规定时，仍让工具默认设置悄然重新定义团队标准。
• 仅根据静态风格检查结果审计代码，遗漏故障模式、数据边界和可运维性风险。

常见反模式

• 仅为满足整洁美学，就用分层抽象取代具体且易懂的代码。
• 将短函数、DRY 或命名规则视为绝对要求，即使它们会损害内聚性、局部性或领域清晰度。
• 借“整洁代码”之名，阻止能保留边界或避免过早引入框架的务实重复。
• 把规则 ID 变成清单式作秀，却不解释规则为何有益于可维护性或安全性。
• 不考虑工具链、运行时和团队工作流的差异，就将某种语言生态的惯例全盘套用到另一种语言上。

经验反馈循环

如果以往的决策或陷阱与当前情况相关，请在 learnings.consolidated.md 存在时查阅；仅在需要回顾历史或其为唯一可用选项时使用 learnings.md。否则跳过两者。

应用后，如果遇到值得记住的模式、值得避免的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的要点。不要修改 SKILL.md 本身。