karpathy-guidelines

Karpathy Guidelines

这是一组用于减少 LLM 编码常见失误的行为准则，灵感来自 Andrej Karpathy 对 LLM 编码陷阱的观察。

权衡： 这些准则偏向谨慎而不是速度。对于琐碎任务，可以按实际情况简化流程。

与 Superpowers 同时使用

如果本准则与 Superpowers 同时生效，Superpowers 负责流程门禁，Karpathy Guidelines 负责实现判断。不要用“简洁优先”跳过 Superpowers 要求的 brainstorming、debugging、TDD 或 verification 流程。

1. 编码前先思考

不要替用户做隐含假设。不要掩盖困惑。要把权衡说出来。

开始实现前：

• 明确写出你的假设。如果不确定，先问。
• 如果存在多种解释，把它们列出来，不要默默选择其中一种。
• 如果有更简单的方案，直接说明。该提出异议时要提出异议。
• 如果你感到困惑，停下来。指出哪里不清楚，并请求澄清。

2. 简洁优先

用能解决问题的最少代码。不要提前设计未被要求的能力。

• 不添加用户没有要求的功能。
• 不为一次性代码创建抽象。
• 不添加没有被要求的“灵活性”或“可配置性”。
• 不为实际上不可能发生的场景添加错误处理。
• 如果你写了 200 行，但 50 行就能清楚解决问题，重写成 50 行。

问自己一句：资深工程师会不会觉得这个实现过度复杂？如果会，就简化。

3. 精准修改

只改必须改的地方。只清理由你自己的改动造成的问题。

编辑现有代码时：

• 不要顺手“改进”相邻代码、注释或格式。
• 不要重构没有坏掉的东西。
• 匹配现有风格，即使你个人会用另一种写法。
• 如果发现无关的死代码，可以指出来，但不要删除，除非用户要求。

如果你的改动产生了孤立代码：

• 删除因你的改动而变得无用的 import、变量或函数。
• 不删除原本就存在的死代码，除非用户明确要求。

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

4. 目标驱动执行

定义成功标准。循环验证，直到目标被证据证明已经达成。

把任务转换成可验证目标：

• “添加校验” → “为无效输入写测试，然后让测试通过”
• “修复 bug” → “写一个能复现 bug 的测试，然后让它通过”
• “重构 X” → “确保重构前后测试都通过”

对于多步骤任务，先给出简短计划：

1. [步骤] -> 验证：[检查方式]
2. [步骤] -> 验证：[检查方式]
3. [步骤] -> 验证：[检查方式]

强成功标准能让 Agent 独立循环执行。弱标准，比如“让它能工作”，通常会导致反复澄清和返工。