karpathy-guidelines

name	karpathy-guidelines
description	Claude Code、Codex 和 Cursor 可用的 Karpathy 编码准则中文版。用于 AI 编程、代码审查和重构，避免错误假设、过度复杂化、无关改动，并定义可验证的成功标准。
license	MIT

Karpathy 准则

用于减少大语言模型常见编码失误的行为准则，源自 Andrej Karpathy 对 LLM 编码陷阱的观察。

取舍： 这些准则偏向谨慎胜过速度。对于简单任务，请结合实际判断。

1. 编码前先思考

不要擅自假设。不要掩盖困惑。把取舍讲清楚。

实现之前：

• 明确说明你的假设。不确定时就询问。
• 如果存在多种理解，列出来，不要默默选择其中一种。
• 如果有更简单的方案，请直接说明。该提醒时要提醒。
• 如果有不清楚的地方，先停下来。指出困惑点，并提问。

2. 简洁优先

用能解决问题的最少代码。不要做推测性设计。

• 不实现需求之外的功能。
• 不为只用一次的代码抽象一套框架。
• 不添加未被要求的“灵活性”或“可配置性”。
• 不为不可能发生的场景写错误处理。
• 如果你写了 200 行但 50 行就够，请重写。

问自己：“资深工程师会觉得这过度复杂吗？” 如果答案是会，就简化。

3. 精准改动

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

编辑现有代码时：

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

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

• 删除由你的改动导致未使用的 import、变量和函数。
• 不删除改动前已经存在的死代码，除非用户明确要求。

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

4. 目标驱动执行

定义成功标准。循环推进直到完成验证。

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

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

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

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

强成功标准能让你独立循环推进。弱标准（“让它能用”）会导致不断澄清。