clean-code-ts-react

用途

本技能用于在编写、评审或重构 TypeScript 或 React 代码时提供工艺（craftsmanship）层面的指导。它把 Robert C. Martin（Uncle Bob）《Clean Code》（2008）中的原则，重新表达为现代 TypeScript 5.x 与 React 19 的实践。规则关注的是历久弥新的原则，而非特定 API。

主要能力

技能包含 61 条规则，分布在 11 个类别中，按一次代码变更生命周期（阅读 → 理解 → 修改 → 验证 → 发布 → 维护）中的认知成本排序。越靠前的阶段越具有级联影响——糟糕的命名会污染每一次阅读。

类别与优先级如下：

有意义的命名（CRITICAL，前缀 name-，8 条规则）
函数、组件与 Hook（CRITICAL，前缀 func-，8 条规则）
自文档化：类型与注释（HIGH，前缀 doc-，5 条规则）
超越 Prettier 的格式化（HIGH，前缀 fmt-，4 条规则）
错误处理（HIGH，前缀 err-，7 条规则）
数据形状与不可变性（MEDIUM-HIGH，前缀 data-，6 条规则）
边界（MEDIUM-HIGH，前缀 bound-，4 条规则）
组合优于继承（MEDIUM-HIGH，前缀 comp-，6 条规则）
测试（MEDIUM，前缀 test-，5 条规则）
涌现与简单设计（MEDIUM，前缀 emerge-，4 条规则）
元：当原则冲突时（MEDIUM，前缀 meta-，4 条规则）

各规则要点

命名：名称应揭示意图、避免误导、做出有意义的区分；组件用 PascalCase 名词短语，Hook 用 useX 动词短语，事件处理器用 onX / handleX，布尔变量用 is/has/can，类型与接口用 PascalCase。

函数、组件与 Hook：保持小、只做一件事、单一抽象层级、优先对象参数、避免隐藏副作用（尤其在渲染中）、命令与查询分离、DRY 直到概念分叉、为可复用有状态逻辑抽取自定义 Hook。

自文档化：优先类型而非注释、用 satisfies 做推断但受检的值、为公共 API 和非显而易见的副作用写 JSDoc、避免冗余注释、删除被注释掉的代码。

格式化：相关代码靠近、无关代码远离；文件按报纸顺序自上而下排列；团队约定优先于个人偏好；导入按来源分组。

错误处理：用提前返回压平错误路径；审慎选择 throw 还是 Result；catch 块中始终收窄 unknown；渲染期失败用错误边界；加载状态用 Suspense；绝不静默吞掉错误；每个领域在 null 与 undefined 中二选一。

数据形状与不可变性：用可辨识联合而非布尔标志；只读数据标记 readonly；用品牌类型表达领域不变量；分离 DTO 与领域类型；prop drilling 常是 Demeter 法则的气味；警惕结构化类型别名问题。

边界：用自定义 Hook 包装第三方 Hook；为第三方行为写学习测试；把框架特定代码隔离在边缘；类型断言只应出现在边界。

组合优于继承：用 children 组合而非配置 props；保持组件小而内聚；避免高阶组件堆叠；Context 用于依赖注入而非避免传 props；逻辑复用优先 Hook 而非 render props；分离构造与使用。

测试：测行为而非实现；只在真正的边界处 mock；应用 FIRST 原则；每个测试一个概念（而非一个断言）；测试代码值得生产级用心。

涌现与简单设计：按顺序应用简单设计四规则；避免过早的类型泛型；抵制过早抽象；最大化表达力——代码即沟通。

元类别（本技能的标志性类别）：明确指导一条整洁原则何时让位于另一条。包括 DRY 与单一职责的取舍、小函数与深模块（Ousterhout）的取舍、类型精度与 API 人体工学的取舍、测试作为规格与作为文档的取舍。资深与否的标志，就是知道该弯折哪一条。

与其他技能的区别

三点使其区别于通用的 clean-code 副本：

以现代惯用法为载体。示例使用 TS 5.x（satisfies、品牌类型、可辨识联合、const 类型参数）和 React 19（函数组件、Hook、use()、相关场景下的 Server Components）。但规则始终是原则，而非语法。
“何时不适用”是一等公民。每条规则都有 2-3 个具体场景说明原则应当弯折——不是泛泛的免责声明，而是真实情境。循环计数器可以叫 i；一次性代码不应 DRY；有些 HOC 无法避免。
用于原则冲突的元类别。第 11 类明确点出最常见的张力。

使用方式

临时问题（“这个命名可以吗？”“该不该抽取？”）：直接通过快速参考跳到相关规则文件。
代码评审或重构：按优先级顺序扫描类别——先看命名和函数形态（级联影响最高），再看错误和数据形状，然后是组合和测试。按类别扫描比按文件扫描更高效。
当两条原则看似冲突时：阅读对应的元规则（第 11 类），选出胜出的原则，并记录这一判断。

适用场景

在以下情况参考这些指南：

编写新的 TypeScript 或 React 代码并希望获得工艺反馈
评审 pull request 的清晰度、命名或抽象
为可读性或可维护性重构既有代码
设计函数、Hook 或组件 API
决定是抽取、抽象还是重复
解决两条整洁规则之间的张力（见第 11 类）

限制与不适用场景

以下情况跳过本技能，改用其他技能：

react：用于 React 19 API 模式（并发渲染、Server Components、ref-as-prop、useActionState、<Context>-as-provider）
typescript：用于编译器性能、tsconfig 调优、类型系统性能
refactor：用于机械式重构工作流
tdd：用于 TDD 工作流本身

参考文件

references/_sections.md：类别定义与排序
assets/templates/_template.md：新增规则的模板
metadata.json：版本与参考信息

技能介绍

用途