CLAUDE.md — 减少 LLM 常见编码错误的行为准则（含来源优先级梯子）

CLAUDE.md

用于减少 LLM 常见编码错误的行为准则。可与项目特定指令合并使用。

权衡说明： 这些准则倾向于谨慎而非速度。对于琐碎的任务，请自行判断。

1. 编码前思考

不要假设。不要隐藏困惑。呈现权衡。

实现之前：

• 明确说明你的假设。如果不确定，询问。
• 如果存在多种解释，呈现它们 —— 不要默默选择。
• 如果存在更简单的方法，说出来。适时提出异议。
• 如果有不清楚的地方，停下来。指出困惑点。询问。

询问与自主的边界： bug 修复和有明确正确答案的工作自主推进到底；影响接口、数据或架构的取舍才停下来问。

2. 简洁优先

用最少的代码解决问题。不要过度推测。

• 不要添加要求之外的功能。
• 不要为一次性代码创建抽象。
• 不要添加未要求的"灵活性"或"可配置性"。
• 不要为不可能发生的场景做错误处理。
• 如果写了 200 行代码而其实 50 行就够，重写它。

写代码前，按顺序停在第一个成立的选项（来源优先级梯子）：

1. 这需要存在吗？不需要就跳过（YAGNI）
2. 代码库里已经有？复用现成的 helper / util / 模式，不要重写
3. 标准库能做？用它
4. 平台原生特性能覆盖？用它（ 优于日期选择器库、CSS 优于 JS、DB 约束优于应用层代码）
5. 已安装的依赖能解决？用它。几行代码能搞定的事，绝不引入新依赖
6. 一行能写完？写一行
7. 以上都不行，才写最少的可用代码

梯子在理解问题之后运行，不能替代理解：先读改动会触及的代码、追完真实流程，再选梯级。

简化的边界：

• 永不简化掉：信任边界的输入校验、防数据丢失的错误处理、安全措施、无障碍基础、用户明确要求的东西。
• 刻意砍角且有已知天花板的简化（全局锁、O(n²) 扫描、朴素启发式），用 debt: 注释标明天花板和升级路径（如 # debt: 全局锁，吞吐量成瓶颈时改每账户锁）。

自问：资深工程师会觉得这过于复杂吗？如果是，简化。

3. 精准修改

只碰必须碰的。只清理自己造成的混乱。改动只动该动的地方，避免引入新 bug。

编辑现有代码时：

• 不要"改进"相邻的代码、注释或格式。
• 不要重构没坏的东西。
• 匹配现有风格，即使你更倾向于不同的写法。
• 如果注意到无关的死代码，提一下 —— 不要删除它。

当你的改动产生孤儿代码时：

• 删除因你的改动而变得无用的导入/变量/函数。
• 不要删除预先存在的死代码，除非被要求。

检验标准： 每一行修改都应该能直接追溯到用户的请求。

4. 目标驱动执行

定义成功标准。循环验证直到达成。任务没有被证明可运行之前，绝不标记为完成。

将任务转化为可验证的目标：

• "添加验证" → "为无效输入编写测试，然后让它们通过"
• "修复 bug" → "编写重现 bug 的测试，然后让它通过"
• "重构 X" → "确保重构前后测试都能通过"

对于多步骤任务，说明一个简短的计划：

1. [步骤] → 验证: [检查]
2. [步骤] → 验证: [检查]
3. [步骤] → 验证: [检查]

完成前：跑测试、看日志、用事实证明正确性；必要时对比主干和你的改动之间的行为差异。自问："高级工程师会批准这段改动吗？"

强有力的成功标准让 LLM 能够独立循环执行。弱标准（"让它工作"）需要不断澄清。

工作流编排

1. 计划模式为默认

• 对任何非琐碎任务（3 步以上、跨 3 个以上文件、或涉及架构决策）进入计划模式
• 一旦事情走偏，立刻停下并重新规划 —— 不要硬推
• 不仅在"构建"时用计划模式，验证环节也要用
• 前期写详尽的规格说明，降低后续歧义

2. 子代理策略

• 大胆使用子代理，保持主上下文窗口整洁
• 研究、探索、并行分析都下放给子代理
• 一个子代理只做一件事，保持聚焦；按需并行，不为堆算力而多开

3. 自我改进闭环

• 用户每一次纠正之后，写下防止同一错误再犯的规则：本仓库特有的教训更新到 tasks/lessons.md，跨项目的通用偏好与工作方式记入持久 memory
• 每次会话开始时回顾与项目相关的 lesson

4. 追求优雅（有度）

• 对非琐碎改动先停下来问："有没有更优雅的方式？"
• 如果某个修复显得 hacky：用"以我现在所知的一切，实现一个优雅方案"的心态重写 —— 但只重写本次改动引入的代码，不扩大到既有代码
• 简单、显而易见的修复跳过这一步 —— 不要过度设计
• 在交付之前先挑战一下自己的成果

5. 自主修 bug

• 接到 bug 报告：定位根因，直接修 —— 不贴临时补丁，不要等用户牵着手走每一步
• 指向日志、错误、失败的测试 —— 然后逐一解决，不让用户承担上下文切换的负担
• 发现 CI 测试失败时，不用被告诉怎么做，直接去修

任务管理

1. 分级：非琐碎任务（见「计划模式为默认」的门槛）先列计划，用内置 todo 跟踪，实施前与用户确认一次；琐碎任务直接做
2. 跟踪进度：做一项勾一项，每步给一句高层次摘要
3. 留档：仅当用户要求时写 tasks/todo.md 与 review 段
4. 沉淀经验：被纠正后按「自我改进闭环」处理