clean-code

name	clean-code
description	在生成或修改实现代码时应用整洁代码原则。强制执行函数职责单一、命名清晰、复杂度管理、错误处理和自文档化风格。在代码生成、重构时使用，或当用户提到'整洁代码'、'代码质量'、'重构这个'、'简化这个'、'改进这个'、'让这个更干净'、'清理这个'、'整理这个'、'编码规范'或'实现质量'时使用。此技能管理编写独立代码单元的技巧——不涉及架构（参见 architecture）、不涉及安全策略（参见 secure-coding），也不涉及测试结构（参见 test-quality）。

整洁代码

配置解析

技能支持项目自定义。优先级顺序如下：

1. 在仓库根目录查找 .lattice/config.yaml
2. 如果找到，检查 paths.clean_code 以获取自定义文档路径
3. 如果存在自定义路径，读取该文档并检查 YAML frontmatter 中的 mode：
   • mode: override（或无 mode）：自定义文档具有最高优先级。使用它替代内置默认值。必须全面——作为唯一参考。
   • mode: overlay：先读取内置的 ./references/defaults.md，然后将自定义文档的内容叠加在上面。自定义部分替换默认值中匹配的章节（通过标题匹配）。新章节追加在默认内容之后。
4. 如果没有配置/路径/文件，读取 ./references/defaults.md
5. 语言适配：如果配置中存在 paths.language_idioms，读取该文档并使用以下章节将默认值适配为语言习惯：
   • "错误处理" → 适配 §8（错误处理）中的模式为语言习惯。语言习惯优先于伪代码默认值。
   • "类型系统与对象模型" → 适配 §1（单一职责）中的内聚性指导原则为语言特性（例如 struct vs class）。
   • "命名约定" → 适配 §4（有意义的命名）中的模式为语言约定。
   • "参数与函数设计" → 适配 §2（小而专注的函数）和 §5（参数设计）为语言特性。
   • "依赖管理" → 适配 §9（测试友好代码）中的 DI 模式为语言习惯。

默认随技能提供。带有偏好的最佳实践。开箱即用。仅当团队有不同标准时才覆盖。

自我验证清单

生成每个组件后停止检查。在继续之前验证所有项。如果检查明显失败，修复后再展示。如果存在多种有效方案的判断性决策（参见歧义信号），请标记——提供选项和推理。

1. 单一职责：描述每个函数时是否不需要"和"？如果需要 → 提取为独立函数。
2. 大小：每个函数是否低于加载文档中的大小阈值（约 20 行，默认值）？如果不是 → 将子操作提取为命名函数。
3. 复杂度：圈复杂度是否低于加载文档中的阈值（约 10，默认值）？如果不是 → 使用卫语句展平、提取分支。
4. 抽象层级：每个函数是否运行在单一层级？如果高层与低层混合 → 提取细节。
5. 命名：函数/变量名是否在无需上下文的情况下揭示意图？如果不是 → 重命名为自文档化名称。
6. 参数：参数数量是否低于加载文档中的阈值（4 个，默认值）？如果不是 → 分组为对象。
7. 原始类型痴迷：字符串/数字/布尔值是否更适合作为命名类型？如果是 → 引入参数对象或类型包装器。
8. 错误处理：每个可能失败的操作是否都有显式处理并附带可操作的消息？是否在合适的层级处理？

项目特定检查：如果加载的文档（来自配置解析）包含验证清单章节（§10），将那些检查作为额外的项目特定验证，在上述清单之后应用。

活跃反模式扫描

在清单检查之后，扫描以下反模式。如果发现，修复后再展示。

• 上帝函数：函数超过约 30 行且做多件事；描述需要"和" → 提取专注的函数
• 深层嵌套：三层或更多缩进层级 → 使用提前返回/卫语句展平
• 晦涩命名：变量名为 d、tmp2、processData → 重命名为揭示意图
• 长参数列表：五个或更多参数 → 分组为对象或拆分函数
• 过早抽象：仅从两个相似代码块中提取工具函数 → 在相同变更理由出现第三次之前，内联处理
• 吞没错误：空 catch 块、泛化的"出错了"、静默返回 null → 显式处理
• 注释作为除臭剂：注释解释复杂的代码而非重构 → 重命名为自文档化；仅保留"为什么"的注释，删除"是什么"
• 隐藏副作用：函数名为 getX 却同时写入缓存/发送通知 → 重命名或分离
• 死代码：注释掉的代码块、未使用的导入、不可达的分支 → 删除（版本控制会保留）
• 无法测试的逻辑：副作用与业务逻辑纠缠；单元测试需要模拟 I/O → 将副作用推至边界，提取纯函数，注入依赖

歧义信号

存在多种有效结果。提供选项而非静默选择。参见 ./references/defaults.md 以获取以下每个信号的解决指导。

• 单一职责：两个紧密耦合的连续操作可能是一个责任（管道），而非两个。"和"测试既能捕获真正的违规，也会产生误报。
• 函数大小：接近阈值（20-30 行）且只有一个明确目的——提取可能创建五个含义模糊的小函数。请权衡利弊。
• DRY vs 过早抽象：两个相同的代码块可能服务于不同目的并会分化。在相同变更理由出现第三次之前，确实存在歧义。
• 错误处理策略：异常 vs Result 类型 vs 错误码取决于语言习惯和团队约定，而非通用规则。

核心原则

整洁代码关乎编写独立单元的技巧——函数、类、模块。这与架构（管理代码存放位置）和领域建模（管理业务规则）不同。在代码生成时应用，而非生成后审查。

参见 ./references/defaults.md 以获取 SRP 管道细节、大小与清晰度阈值、魔法数字提取规则、布尔参数模式、DRY vs 错误抽象启发式方法，以及错误消息指南。