uncle-bob-craft

Uncle Bob 工艺

应用 Robert C. Martin（Uncle Bob）的标准进行代码审查和生产开发：Clean Code、Clean Architecture、The Clean Coder、Clean Agile 和设计模式规范。本技能与现有的 @clean-code 技能（专注于 Clean Code 一书）及项目的 linter/formatter 互为补充，并不取代它们。

解读边界

这些是结合上下文的设计启发，并非要求每次修改都引入接口、分层或测试的普遍规则。遵循项目架构和语言的错误处理惯例；提出建议时，应说明具体的变更风险，而不能只引用原则名称。下方的示例保留了金额原有的增幅：它是一个比率乘数，而非折扣。

概述

本技能汇集了 Uncle Bob 著作中的原则，用于审查和编写代码：命名和函数（通过 @clean-code）、架构和边界（Clean Architecture）、专业素养和估算（The Clean Coder）、敏捷价值观和实践（Clean Agile），以及设计模式的正确使用与误用。可用它评估结构、依赖关系、结合上下文应用 SOLID、代码异味和专业实践。它只提供工艺和设计标准，不负责语法或风格检查；这些仍由 linter 和 formatter 负责。

何时使用此技能

• 代码审查：应用依赖规则、边界、SOLID 和代码异味启发，提出具体重构建议。
• 重构：决定要提取什么、如何划分边界，以及设计模式是否合理。
• 架构讨论：检查分层边界、依赖方向和关注点分离。
• 设计模式：在引入模式前，评估其正确使用与盲目照搬或过度使用。
• 估算和专业素养：应用 Clean Coder 中的理念（说“不”、保持可持续的工作节奏、三点估算）。
• 敏捷实践：讨论流程时参考 Clean Agile（铁三角、TDD、重构、结对编程）。
• 不要用它来替代或覆盖项目的 linter、formatter 或自动化测试。

按来源分类的索引

来源	重点	参阅
Clean Code	命名、函数、注释、格式、测试、类、代码异味	详情请参阅 @clean-code；本技能在审查和生产开发中引用该技能。
Clean Architecture	依赖规则、分层、边界、架构中的 SOLID	参阅 reference.md 和 references/clean-architecture.md。
The Clean Coder	专业素养、估算、说“不”、可持续的工作节奏	参阅 reference.md 和 references/clean-coder.md。
Clean Agile	价值观、铁三角、TDD、重构、结对编程	参阅 reference.md 和 references/clean-agile.md。
设计模式	何时使用、误用、盲目照搬	参阅 reference.md 和 references/design-patterns.md。

设计模式：正确使用与误用

• 使用模式来解决真实的设计问题（例如行为差异、生命周期或横切关注点），而不是为了显得“企业级”。
• 避免盲目照搬：不要只因为代码库“应该”有 Factory/Strategy/Repository 就添加它们；只有在重复或僵化足以证明抽象合理时，才添加它们。
• 误用迹象：每个类名中都带有模式名称、只转发调用而不包含逻辑的分层，以及让简单代码更难理解的模式。
• 经验法则：当你发现第三处重复，或第二个需要修改的原因时，就引入模式；在代码或文档中标明模式名称，以清晰表达意图。

代码异味与启发式原则（摘要）

代码异味／启发式原则	含义
僵化	微小改动也会迫使你修改许多地方。
脆弱性	改动会破坏无关的部分。
难以移植	难以在其他上下文中复用。
黏滞性	走捷径很容易，做正确的事却很难。
不必要的复杂性	推测性或未使用的抽象。
不必要的重复	违反 DRY；同一想法出现在多个地方。
晦涩性	代码难以理解。

精简的编辑分类（其中的 C/T 标识符并非书中启发式原则的标准标识符）见 reference.md。在评审中使用这些术语来指出问题并提出重构建议（提取、移动依赖、引入边界）。

评审与生产代码

场景	应用方式
代码评审	检查依赖规则和边界；结合上下文应用 SOLID；列出代码异味；建议一到两项具体重构（例如提取函数、反转依赖）；检查测试和专业性（是否有测试、是否存在明显的应急补丁）。
编写新代码	优先使用小函数并遵循单一职责；依赖向内（整洁架构）；采用 TDD 时先写测试；除非重复或变化足以证明其合理性，否则避免使用模式。
重构	每次识别一种代码异味；以小步重构并保持测试通过；先改善命名和结构，再添加行为。

工作方式

评审代码时

1. 边界和依赖规则：检查依赖是否向内指向（例如，用例不依赖 UI 或 DB 细节）。参见 references/clean-architecture.md。
2. 结合上下文应用 SOLID：检查单一职责、开闭原则、里氏替换原则、接口隔离原则和依赖倒置原则是否适用于修改过的代码。
3. 代码异味：检查僵化、脆弱性、难以移植、黏滞性、不必要的复杂性／重复和晦涩性；注明所在文件／区域。
4. 具体建议：提出一到两项重构建议（例如，“将此处提取为名为 X 的函数”，“引入接口，避免这一层依赖具体的 DB 客户端”）。
5. 测试与工程素养：报告观察到的测试覆盖情况和具体的延后风险；不要根据 TODO 注释推断作者的专业性或工作节奏。

编写或重构代码时

1. 优先使用小型、单一用途的函数和类；使用 @clean-code 改善命名和结构。
2. 确保依赖向内指向；将业务规则放在中心，将适配器放在边缘。
3. 只有在重复或变化足以证明其合理性时，才引入设计模式。
4. 以小步进行重构，并确保测试始终通过。

示例

示例 1：代码评审提示词（可直接复制粘贴）

使用以下内容请求一项以 Uncle Bob 为导向的评审：

Please review this change using Uncle Bob craft criteria (@uncle-bob-craft):
1. Dependency Rule and boundaries — do dependencies point inward?
2. SOLID in context — any violations in the touched code?
3. Smells — list rigidity, fragility, immobility, viscosity, needless complexity/repetition, or opacity.
4. Suggest one or two concrete refactors (e.g., extract function, invert dependency).
Do not duplicate lint/format; focus on structure and design.

示例 2：前后对比（提取并命名）

之前（晦涩，做了不止一件事）：

def process(d):
    if d.get("t") == 1:
        d["x"] = d["a"] * 1.1
    elif d.get("t") == 2:
        d["x"] = d["a"] * 1.2
    return d

之后（意图清晰，抽象层级单一）：

def apply_rate_multiplier(amount: float, rate_type: int) -> float:
    if rate_type == 1:
        return amount * 1.1
    if rate_type == 2:
        return amount * 1.2
    return amount

def process(order: dict) -> dict:
    order["x"] = apply_rate_multiplier(order["a"], order.get("t", 0))
    return order

最佳实践

• ✅ 使用 @clean-code 处理命名、函数、注释和格式；使用此技能处理架构、边界、SOLID、代码异味和流程。
• ✅ 在评审中指出代码异味或原则（例如，“违反依赖规则：用例导入了 Web 框架中的内容”）。
• ✅ 仅在观察到的问题确实需要时提出具体重构建议；代码整洁的评审可能无需任何建议（提取、重命名、反转依赖）。
• ✅ 分别运行项目的 linter 和 formatter；此技能不能替代它们。
• ❌ 不要使用此技能强制执行语法或风格；这是 linter 的职责。
• ❌ 没有明确的重复或变化理由时，不要添加设计模式。

常见陷阱

• 问题： 把每个类都当作需要 Factory 或 Strategy。
  解决方案： 只有存在真实的设计需求（第三次重复、第二个变化维度）时才引入设计模式。

• 问题： 评审时只写“违反 SOLID”，却不指出在哪里、如何违反。
  解决方案： 指明文件/函数，以及所违反的原则（例如“SRP：该函数既解析又持久化；拆分为解析和持久化”）。

• 问题： 因为“我们应用了 Uncle Bob”就跳过项目 linter。
  解决方案： 本技能关注的是技艺与设计；始终运行项目的 lint 和 format。

相关技能

• @clean-code — 《Clean Code》一书的详细材料（命名、函数、注释、格式、测试、类、坏味道）。用于日常代码质量；架构和跨书准则请使用 uncle-bob-craft。
• @architecture — 通用架构决策与权衡。在选择高层结构时使用；依赖规则和边界请使用 uncle-bob-craft。
• @code-review-excellence — 代码评审实践。与 uncle-bob-craft 结合，进行基于原则的评审。
• @refactor-clean-code — 向整洁代码重构。在为边界和 SOLID 进行重构时，与 uncle-bob-craft 一起使用。
• @test-driven-development — TDD 工作流。与《Clean Agile》和《Clean Coder》一致（测试即需求、可持续节奏）。

限制

• 不能替代项目的 linter 或 formatter。 需单独运行 lint 和 format；本技能只提供设计与技艺方面的准则。
• 不能替代自动化测试。 它可以提醒你编写测试（《Clean Coder》、《Clean Agile》），但不会运行或生成测试。
• 与工具互补。 与现有的 CI、lint 和测试套件配合使用。
• 不强制语法或风格。 它关注结构、依赖、坏味道和职业实践，而不是大括号风格或行长度。
• 是摘要，不是原书。 完整的《Clean Code》启发式规则、组件原则（REP/CCP/CRP、ADP/SDP/SAP）和详细案例都在书中；我们只引用最常用的部分。参见 reference.md 的“Scope and attribution”。