boy-scout-rule

童子军规则

应用前

如果 .agents/stack-context.md 存在，请先阅读。根据检测到的技术栈，采用符合其惯例的模式来应用这一原则。有关框架特定的细节，请使用 context7 MCP 或网络搜索，不要猜测。

原则

让你接触到的每个文件都比接手时好一点。不是好很多，而是好一点。随着时间推移，持续的小改进会累积成整洁的代码库。

这在生产环境中为何重要

代码库不会一夜之间腐坏。它们是一次又一次地走捷径，逐渐退化的——这里硬编码一个值，那里跳过一次重命名，还有一个 TODO 一留就是三年。童子军规则是解药：它让改进成为默认做法，而不是定期安排的活动。

践行这一规则的团队永远不需要“清理冲刺”。他们的代码始终保持健康，因为维护工作会持续进行，并融入常规的功能开发中。

但这需要自律：改进必须小而安全，且范围明确。如果一次“清理”改动了 40 个文件，还破坏了两个功能，那就比维持现状更糟。

规则

1. 在范围内修复你发现的问题。 如果你打开一个文件修复 Bug 时，发现变量名容易误导，就重命名它。如果发现无用的导入，就删掉。这些都是安全、低风险的改进。
2. 将清理放在单独的提交中。 功能提交应包含功能，清理提交应包含清理。把两者混在一起会增加代码审查的难度，也会让回滚变得危险。
3. 不要重构你不了解的代码。 如果你打开一个不熟悉的文件，发现某处看起来有问题，请先调查，再进行“修复”。看似无用的代码可能是关键的回退机制；看似拼写错误的内容也可能是有意为之。
4. 控制改进范围。 童子军规则意味着修正容易混淆的名称或补上缺失的类型注解，而不是重设计你碰巧经过的模块。
5. 留下线索。 如果你发现的问题太大，无法顺手修复，就创建一个问题，或添加 TODO(ticket-number)，以免被遗忘。

什么算是“好一点”

• 将变量从 x 重命名为 user_count
• 移除未使用的导入或无用代码
• 添加缺失的类型注解
• 修正容易误导的注释（或移除重复说明代码的注释）
• 将魔法数字替换为命名常量
• 简化不必要地复杂的条件判断
• 修复编译器或代码检查工具的警告

什么不算

• 在不改变功能的情况下，以“更好”的风格重写函数
• 在整个代码库中迁移到一种新模式
• 添加功能或改变行为
• 重新格式化文件以匹配另一种风格（请使用自动格式化工具）
• 在没有充分理解的情况下重构你不熟悉的代码

边界

• 规模限制： 如果一次清理会改动超过约 20 行，或涉及多个模块，就不属于童子军式改进，而是需要单独创建工单并进行审查的重构任务。
• 与“不要改动你不负责的内容”之间的张力： 在共享代码库中，通常欢迎小幅改进。跨模块边界的大型重构则需要协调。要分清两者。
• 与最小差异之间的张力： 有些团队更偏好只包含预期改动的 PR。在这种情况下，请将童子军式清理放在单独的 PR 中。

代码审查清单

• 这些清理是否确实风险低且显然正确？
• 清理是否与功能开发分别提交？
• 清理是否只涉及作者正在处理的代码？
• 如果回滚清理，功能是否仍然完整？

相关技能

• kiss：用于判断什么算是“更简单”
• convention-over-configuration：用于在“修复”问题之前了解项目的惯例
• dry：用于发现值得整合的重复内容