← 返回文章归档

把《代码整洁之道》变成 Skill:我如何在开发和 Review 中使用 clean-code

2026年11月6日作者 王京64 个内容块

把 Clean Code 原则整理成可重复调用的工作流程:从安装、四种使用场景和提示词模板,到保持行为不变的局部重构,说明怎样让 AI 改善可维护性,同时控制修改范围。

使用 AI 写代码时,我经常遇到一个问题:让它“把代码写整洁一点”,并没有说清楚究竟要改善什么。它可能改了几个变量名,也可能拆出许多函数,甚至把一个局部修复扩成整片重构。

因此,我把 Robert C. Martin 的《代码整洁之道》中的部分原则,整理成了一个 clean-code Skill。它把命名、职责、错误处理和模块边界等建议,转成可执行的检查流程,让每次修改都能说明理由、控制范围,并给出验证依据。

它最适合可维护性 Review 和局部重构;开发新功能、修 bug 时,也可以按需调用。

1. 这个 Skill 解决什么问题

clean-code 关心的是:下一位读代码的人,能否理解意图;下一次需求变化,能否找到正确的修改位置;出现问题时,能否分清业务上的缺失与真正的故障。

它主要检查以下方面:

  • 命名:名称是否表达领域含义、单位和状态,缩写是否造成误解。
  • 函数与职责:一段代码是否承担了不同的变化原因,副作用是否清楚。
  • 注释与布局:注释是否解释约束和原因,相关代码是否放在一起。
  • 错误处理:失败是否保留了上下文,是否被空值或默认值悄悄掩盖。
  • 模块与边界:外部实现细节是否泄漏,是否在负责接收未知输入的边界完成校验。
  • 测试:测试是否验证可观察行为,失败后能否帮助定位问题。

这些检查仍然要服从项目约定和现有契约。函数较长、参数较多、出现 null,都只是进一步检查的信号,不能单凭它们判定代码有问题。

2. 安装与首次调用

clean-code 的添加地址:

在支持技能安装的 Codex 对话中,可以直接提出:

安装这个 clean-code skill:
https://github.com/xjccc-skills/agent-skills/tree/main/clean-code/skills/clean-code

注意仓库中的两层目录:外层 clean-code/ 是插件目录,实际技能位于 clean-code/skills/clean-code/,其中包含 SKILL.md。安装完成后,在新的对话轮次显式调用:

用 $clean-code 审查当前 diff,重点检查可维护性。
只给建议,不修改代码。

安装完成后的使用示例:

clean-code-usage.png

图:在 Codex 中安装 clean-code 后,使用 $clean-code 发起 Review 或局部重构。上方保留了可以直接复制的调用文本。

Claude Code 用户也可以按仓库 README 中的方式安装插件:

/plugin marketplace add xjccc-skills/agent-skills
/plugin install clean-code@xjccc-skills

这个 Skill 本身是一组指导 Agent 工作的说明和参考文件,不需要额外运行服务,也不需要单独的 API Key。使用它的 Agent 仍使用原有模型和运行环境。

3. 四种场景,四种调用方式

Review:先找具体问题

这是我建议优先使用的场景。让 Agent 阅读目标代码、调用方和相关测试,再区分正确性风险与可维护性建议。Review 模式默认提出建议,只有明确要求实施时才修改文件。

用 $clean-code 审查当前 diff。
重点检查命名、职责边界和错误处理。
按影响排序,区分正确性风险与可维护性建议。
指出具体位置、影响和建议验证方式;只给建议,不修改代码。

一条有价值的结论应当说明“哪里造成了什么成本”。例如,把数据库异常统一转成 null,会让调用方把服务故障误判为用户不存在。这样的发现,比“建议优化错误处理”更容易判断和落实。

重构:明确范围和需要保留的行为

当一段代码已经难以理解,但功能本身不需要改变时,可以让 Skill 指导局部重构。先记录基线行为,再做一个完整而小的改动。

用 $clean-code 重构这个导出映射函数及其必要调用点。
保持输出字段、公开接口、错误语义和性能特征不变。
优先使用清晰命名与现有边界,不按行数拆函数。
完成后说明修改理由,并运行相关的最小验证。

这里的关键是把“什么不能变”写出来。只说“优化一下”,会给 Agent 留下过多解释空间。

开发:在本次功能中使用原则

实现新功能时,Skill 可以帮助整理命名、放置业务规则、处理错误和外部输入。范围应落在新路径及其必要关联代码上。

实现这个功能时使用 $clean-code,只处理本次涉及的代码。
先阅读项目约定、附近实现和相关测试,沿用已有设计。
在负责外部输入的边界完成校验,向内部传递已收窄的类型。
完成后说明行为变化与实际运行的验证。

边界校验强调的是责任归属:未知数据进入系统时完成校验,内部已经由类型或构造过程保证的值,不必沿途重复检查。是否需要新增适配层,要看外部细节是否泄漏、检查是否重复,或是否有实际替换与测试需求。

修 bug:把整洁原则用于最小修复

修 bug 时,先复现失败,再定位和修正行为。附近代码存在命名或结构问题,并不会自动扩大本次任务。

使用 $clean-code 修复这个年龄边界问题:年满 18 岁应当符合条件。
先确认失败场景,再做最小修正。
验证 17、18、19 岁的结果,运行相关现有测试。
保持无关逻辑不变,其他可维护性建议单独列出。

如果缺陷只是 age > 18 应改为 age >= 18,那么一行修正加上必要验证就可能已经足够。

4. 它怎样判断“值得改”

Skill 的核心流程是:信号 → 动作 → 证明。

  1. 信号:指出可观察的问题,以及它增加的阅读、修改、测试或排障成本。
  2. 动作:选择能够消除该成本的最小改动。Review 时只提出方案和理由。
  3. 证明:用相关测试、类型检查、lint 或行为对照验证结果;区分已经执行的检查与建议后续执行的检查。

例如,一个名为 hasPendingJobs() 的函数,内部却把任务标记为“已领取”。问题在于名称承诺查询,实际发生状态变化。改进方向应围绕操作契约、名称及调用方展开,并验证领取行为,而不是只把函数拆短。

这个流程也允许得到“保留现有设计”的结论。找不到具体维护成本时,没有必要为了满足某条口号制造改动。

5. 三类容易过度重构的情况

代码相似,但业务规则不同

function loyaltyCredit(amount: number) {
  return amount * 0.10;
}

function latePaymentFee(amount: number) {
  return amount * 0.10;
}

这里的计算形式相同,但会员返利和逾期费用由不同政策决定。如果需求只是把返利提高到 15%,修改返利函数即可。提前合并为一个带类型参数的通用函数,会把独立规则绑在一起。只有确实共享同一业务规则、需要一起变化时,提取共同逻辑才有依据。

函数较长,但表达一个连贯过程

一个包含 28 个字段的导出映射,可能只是按同一抽象层次组装结果。新增字段时,可以在原位置补充并核对输出契约。给每个字段拆一个 helper,会增加阅读时的跳转。出现独立业务决策或可复用的归一化逻辑时,再提取对应操作。

返回空值或返回数据,都有明确契约

findUser(id): Promise<User | null> 可以明确约定:null 表示没有匹配用户。需要检查的是,数据库故障是否仍走独立的错误路径,而不是一律禁止空值。

同样,claimNextJob() 可以原子地领取任务并返回它。机械地拆成“先查看,再标记”,反而可能让两个 worker 领取同一任务。涉及共享状态、重叠异步操作或执行顺序时,才按需加载并发检查,核对原子性与状态所有权。

6. 一份可以反复使用的任务模板

实际调用时,我会把模式、范围、契约和验证要求放在一起:

使用 $clean-code。

模式:Review / 重构 / 开发 / 修复,选择本次需要的一种。
范围:具体文件、函数或当前 diff,以及必要的调用方。
目标:本次要解决的需求、缺陷或维护成本。
契约:必须保留的行为、公开接口、错误语义和数据格式。
验证:相关测试、类型检查、lint 或行为对照。

先阅读项目约定和现有实现,只应用相关原则。
Review 模式只提出建议;需要修改时,做最小且完整的改动。
最后说明发现或改动、已执行的验证,以及未确认的部分。

提交前,我会检查三件事:每项修改是否有明确理由,是否偷偷改变了契约,以及验证是否真的执行。Skill 能帮助组织判断,业务正确性仍要结合需求和验证结果来确认。

7. 参考来源与适用边界

这个 Skill 是对 Robert C. Martin 的 Clean Code: A Handbook of Agile Software Craftsmanship(Prentice Hall,2008)的独立、选择性归纳,不是逐章摘要。命名、函数、注释、错误处理、测试与并发等主题参考原书;边界 schema 与类型收窄、兼容迁移和取舍案例属于现代工程适配或原创示例。

技能将详细内容按需拆成几个文件,普通任务不必一次读完所有材料:

第一次使用,可以从一个范围清楚的 Review 开始。让它解释一个具体问题、提出一个小改进,再由验证结果决定是否采用。这样更容易看清这个 Skill 对自己项目的实际价值。