| name | clean-code |
| description | 在生成或修改实现代码时应用整洁代码原则。强制执行函数职责单一、命名清晰、复杂度管理、错误处理和自文档化风格。在代码生成、重构时使用，或当用户提到'整洁代码'、'代码质量'、'重构这个'、'简化这个'、'改进这个'、'让这个更干净'、'清理这个'、'整理这个'、'编码规范'或'实现质量'时使用。此技能管理编写独立代码单元的技巧——不涉及架构（参见 architecture）、不涉及安全策略（参见 secure-coding），也不涉及测试结构（参见 test-quality）。 |
整洁代码
配置解析
技能支持项目自定义。优先级顺序如下：
- 在仓库根目录查找
.lattice/config.yaml
- 如果找到，检查
paths.clean_code 以获取自定义文档路径
- 如果存在自定义路径，读取该文档并检查 YAML frontmatter 中的
mode：
mode: override（或无 mode）：自定义文档具有最高优先级。使用它替代内置默认值。必须全面——作为唯一参考。mode: overlay：先读取内置的 ./references/defaults.md，然后将自定义文档的内容叠加在上面。自定义部分替换默认值中匹配的章节（通过标题匹配）。新章节追加在默认内容之后。
- 如果没有配置/路径/文件，读取
./references/defaults.md
- 语言适配：如果配置中存在
paths.language_idioms，读取该文档并使用以下章节将默认值适配为语言习惯：
- "错误处理" → 适配 §8（错误处理）中的模式为语言习惯。语言习惯优先于伪代码默认值。
- "类型系统与对象模型" → 适配 §1（单一职责）中的内聚性指导原则为语言特性（例如 struct vs class）。
- "命名约定" → 适配 §4（有意义的命名）中的模式为语言约定。
- "参数与函数设计" → 适配 §2（小而专注的函数）和 §5（参数设计）为语言特性。
- "依赖管理" → 适配 §9（测试友好代码）中的 DI 模式为语言习惯。
默认随技能提供。带有偏好的最佳实践。开箱即用。仅当团队有不同标准时才覆盖。
自我验证清单
生成每个组件后停止检查。在继续之前验证所有项。如果检查明显失败，修复后再展示。如果存在多种有效方案的判断性决策（参见歧义信号），请标记——提供选项和推理。
- 单一职责：描述每个函数时是否不需要"和"？如果需要 → 提取为独立函数。
- 大小：每个函数是否低于加载文档中的大小阈值（约 20 行，默认值）？如果不是 → 将子操作提取为命名函数。
- 复杂度：圈复杂度是否低于加载文档中的阈值（约 10，默认值）？如果不是 → 使用卫语句展平、提取分支。
- 抽象层级：每个函数是否运行在单一层级？如果高层与低层混合 → 提取细节。
- 命名：函数/变量名是否在无需上下文的情况下揭示意图？如果不是 → 重命名为自文档化名称。
- 参数：参数数量是否低于加载文档中的阈值（4 个，默认值）？如果不是 → 分组为对象。
- 原始类型痴迷：字符串/数字/布尔值是否更适合作为命名类型？如果是 → 引入参数对象或类型包装器。
- 错误处理：每个可能失败的操作是否都有显式处理并附带可操作的消息？是否在合适的层级处理？
项目特定检查：如果加载的文档（来自配置解析）包含验证清单章节（§10），将那些检查作为额外的项目特定验证，在上述清单之后应用。
活跃反模式扫描
在清单检查之后，扫描以下反模式。如果发现，修复后再展示。
歧义信号
存在多种有效结果。提供选项而非静默选择。参见 ./references/defaults.md 以获取以下每个信号的解决指导。
- 单一职责：两个紧密耦合的连续操作可能是一个责任（管道），而非两个。"和"测试既能捕获真正的违规，也会产生误报。
- 函数大小：接近阈值（20-30 行）且只有一个明确目的——提取可能创建五个含义模糊的小函数。请权衡利弊。
- DRY vs 过早抽象：两个相同的代码块可能服务于不同目的并会分化。在相同变更理由出现第三次之前，确实存在歧义。
- 错误处理策略：异常 vs Result 类型 vs 错误码取决于语言习惯和团队约定，而非通用规则。
核心原则
整洁代码关乎编写独立单元的技巧——函数、类、模块。这与架构（管理代码存放位置）和领域建模（管理业务规则）不同。在代码生成时应用，而非生成后审查。
参见 ./references/defaults.md 以获取 SRP 管道细节、大小与清晰度阈值、魔法数字提取规则、布尔参数模式、DRY vs 错误抽象启发式方法，以及错误消息指南。
