boy-scout

童子军守则

“离开营地时，要让营地比你到达时更整洁。” — Robert Baden-Powell

“提交模块时，要让它比检出时更整洁。” — Robert C. Martin，Clean Code

理念

你不必让每个模块都完美。只需让它比你发现时好一点点。

如果我们都遵循这条简单的规则：

• 系统会随着演进逐步变得更好
• 团队会共同维护整个系统
• 软件不可避免地逐渐恶化这一现象将会终结

编写代码时

每次修改代码时，都要寻找至少一处小改进：

快速改进（立即完成）

• 重命名命名不当的变量 → 触发 clean-names
• 删除多余的注释 → 触发 clean-comments
• 移除无用代码或未使用的导入
• 将魔法数字替换为有名称的常量
• 将深层嵌套的代码块提取为命名清晰的函数

深入改进（有时间时完成）

• 拆分承担多项工作的函数 → 触发 clean-functions
• 消除重复（DRY）→ 触发 clean-general
• 补充缺失的边界检查
• 提高测试覆盖率 → 触发 clean-tests

实践这条规则

# You're asked to fix a bug in this function:
def proc(d, x, flag=False):
    # process data
    for i in d:
        if i > 0:
            if flag:
                x.append(i * 1.0825)  # tax
            else:
                x.append(i)
    return x

# Don't just fix the bug and leave.
# Leave it cleaner:
TAX_RATE = 0.0825

def process_positive_values(
    values: list[float],
    apply_tax: bool = False
) -> list[float]:
    """Filter positive values, optionally applying tax."""
    rate = 1 + TAX_RATE if apply_tax else 1
    return [v * rate for v in values if v > 0]

改动内容：

• ✅ 函数名称具有描述性（N1）
• ✅ 参数名称清晰（N1）
• ✅ 类型提示（P3）
• ✅ 为魔法数字定义了有名称的常量（G25）
• ✅ 未修改输出参数（F2）
• ✅ 有用的文档字符串（C4）

技能编排

此技能会根据你的工作内容，与专门技能协同工作：

任务	触发技能
编写或审查任何 Python 代码	python-clean-code（主技能）
为变量、函数、类命名	clean-names
编写或编辑注释	clean-comments
创建或重构函数	clean-functions
审查代码质量	clean-general
编写或审查测试	clean-tests

心态

不要：

• 让代码比你发现时更糟
• 说“这不是我写的代码”
• 等待专门的重构冲刺
• 做与任务无关的大规模改动

要：

• 每次提交都做一处小改进
• 修复你发现的问题，即使不是你造成的
• 让改动与任务规模相称
• 持续积累质量改进

AI 行为

编写代码时：

1. 先完成请求的任务
2. 找出至少一处值得清理的小问题
3. 应用适当的专门技能
4. 说明所做的改进（例如：“另外清理了：将 x 重命名为 results，让名称更清晰”）

审查代码时：

1. 加载 python-clean-code，全面检查规则
2. 按规则编号指出违规之处
3. 建议渐进式改进，而非彻底重写

童子军誓言

每段经你修改的代码都会变得好一点。不必完美，只需更好。

日积月累，改进终将汇聚成卓越。