clean-code

Clean Code

在选择模型之前先选择分支。协调工作和确定性命令都在调用权限范围内执行。在当前角色中应用此方法。它不会派发工作线程。如需派发工作线程，请使用 shared/references/model-preview.md 及其唯一获批的路由快照。嵌套技能和运行器会使用该快照，不会再次选择模型或工作线程。

改进现有代码，使其更易于阅读、更安全地修改、更容易测试，同时默认保持行为不变。

操作规则

• 除非用户明确要求改变行为，否则应保持行为不变：保留公共 API、副作用、错误行为和错误消息、性能特征、可观察的时序假设、边缘情况和数据形状，除非改变这些内容属于请求的一部分。
• 相较于大范围重写，优先选择最小且有效的改动。
• 优先改进名称，而不是添加注释或抽象。
• 保持领域语言清晰可见。不要用通用辅助函数掩盖业务规则。
• 只有当重复代码表达同一概念且变更原因相同时，才消除重复。
• 避免引入新模式、依赖、格式变动和模块迁移，除非它们能明确降低实际复杂度。
• 如果测试缺失或薄弱，且重构风险较高，应先改进现有测试，或添加或建议有针对性的特征测试，以此作为保持行为不变的保障，然后再深入调整结构。对于没有测试保障的遗留代码，应先应用 safe-incremental-coding，然后再回到此处。

工作流

1. 理解代码。

   • 确定代码的用途、公共接口、输入、输出、副作用、不变量、框架约束和现有测试。
   • 如果用户只要求审查，则报告发现的问题，不要编辑。

2. 对工作分类。

   • 对命名、常量、简单提取和控制流清晰度，使用 local cleanup。
   • 对保持行为不变的结构调整，使用 refactor。
   • 只有在用户允许改变行为或所请求修复的问题明确时，才使用 bug fix plus cleanup。
   • 除非用户明确要求，否则将 redesign 视为超出范围。
   • 如果安全方案需要重新设计、更改依赖或进行超出请求范围的行为变更，则停止并向用户说明可选方案，不要继续操作。

3. 选择改进方式。

   • 重命名含义不清的标识符。
   • 为魔法值提取有意义的常量。
   • 在辅助函数能为领域中的真实步骤命名时，提取小型辅助函数。
   • 使用守卫子句扁平化嵌套控制流。
   • 如果解析、验证、业务规则、持久化、格式化、编排和副作用相互纠缠，则将它们拆分开。
   • 改进错误处理的一致性，但不要削弱现有错误。

4. 安全地编辑。

   • 将改动限制在请求涉及的代码路径内。
   • 尽可能一次只进行一项逻辑改进。
   • 按上述规则重新核实改动是否保持行为不变。
   • 不要用取巧的代码替换清晰的代码。

5. 验证。

   • 有相关现有测试或检查时，运行其中最相关的项目。
   • 如果无法运行测试，请说明原因。
   • 重新检查名称是否能表达意图、函数是否职责明确、抽象层级是否一致、注释是否仍然准确，以及副作用是否清晰可见。

异味检查清单

按名称诊断。在更改任何内容之前，先说出你发现的异味——指出异味名称，才能让改进一目了然，并确保更改不影响行为。以下每种异味都是一个术语；请使用该术语，不要换种说法。

• 命名异味：名称不清晰、魔法值。
• 函数异味：函数过长、嵌套过深、布尔表达式复杂、标记参数、抽象层级不一致。
• 职责异味：职责混杂、类过大、隐藏的变更。
• 数据异味：基本类型偏执、数据组团、参数列表过长。
• 重复异味：逻辑重复（仅当它们表达相同概念，且变更原因相同时）。
• 注释异味：重复代码内容或为代码开脱的冗余注释。
• 安全异味：错误处理不一致、测试脆弱或缺失。

先指出异味，再应用相应的改进。“这些参数存在基本类型偏执和数据组团”这类句子应当出现在每次编辑之前。

命名指南

• 优先使用能体现意图的名称，例如 elapsedTimeInDays、customerRepository、isEligibleForDiscount、calculateInvoiceTotal 和 parsePaymentRequest。
• 避免使用含义模糊的名称，例如 data、info、manager、processor 和 helper，除非领域本身确实使用这些术语。
• 布尔值命名应读起来自然：isActive、hasPermission、canRetry、shouldNotifyCustomer。
• 尽可能使用动词命名函数：calculateTotal、validateRequest、loadCustomer、sendReceipt、formatCurrency。

注释

将每条注释诊断为有价值的注释或噪声。只有当注释说明了代码无法表达的内容时，它才有价值，例如业务规则、外部限制、安全问题、性能权衡、历史背景或不明显的决策。编辑时请明确指出：“这是有价值的注释——它记录了参数名称无法体现的身份验证限制。”其他注释都是噪声：重复代码内容、陈述显而易见之事、为本应重命名或提取的代码开脱，或读起来像 AI 垃圾文本（道歉、占位内容，或资深开发者绝不会留下的逐行叙述式修改说明）。

• 保留有价值的注释：业务规则、外部限制、安全问题、性能权衡、历史背景、不明显的决策。
• 删除无价值的注释：复述代码、陈述显而易见之事、过时内容或 AI 垃圾文本。

输出约定

返回结果时，请包含：

• summary：改进内容。
• key_improvements：对可读性、可维护性、安全性或可测试性影响最大的改进。
• behavior_changes：行为保持不变时写 none；否则准确说明更改了什么以及原因。
• validation：运行的测试或检查及其结果。
• risks：缺失的测试、要求不明确之处、框架限制或需要额外审查的领域。

仅审查任务应先按严重程度列出问题，并尽可能注明文件和行号。

注意事项

不要引用或重构这项技能所提炼的书籍原文。