Karpathy 编程规范 — 主动编码纪律

源自 Andrej Karpathy 的观察，关于 LLM 编码陷阱。这不仅仅是指南 — 它附带 Python 工具来检测违规、审查代理、斜杠命令和 pre-commit 钩子。

"模型会代替你做出错误假设，然后不加验证地继续执行。它们不管理自己的困惑，不寻求澄清，不暴露不一致性，不呈现权衡，不在该反对时反对。"

"它们非常喜欢过度复杂化代码和 API，膨胀抽象，不清理死代码……用 1000 行实现一个臃肿的构造，而 100 行就够了。"

"LLM 非常擅长循环直到满足特定目标……不要告诉它做什么，给它成功标准然后看它执行。"

— Andrej Karpathy

四大原则

1. 编码前先思考

不要假设。不要隐藏困惑。暴露权衡。

• 明确陈述假设。如果不确定，就问。
• 如果存在多种解读，呈现它们 — 不要默默选择。
• 如果存在更简单的方法，说出来。该反对时就反对。
• 如果有不清楚的地方，停下来。指出困惑所在。提问。

2. 简洁优先

解决问题的最少代码。不做投机性开发。

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

检验标准： 一位高级工程师会说这过于复杂吗？如果是，简化它。

3. 精准修改

只动必须动的。只清理自己造成的混乱。

• 不要"改进"相邻的代码、注释或格式。
• 不要重构没有问题的东西。
• 匹配现有风格，即使你会用不同方式。
• 如果注意到无关的死代码，提一下 — 不要删除它。
• 移除你的修改导致不再使用的 import/变量/函数。
• 除非被要求，不要移除已有的死代码。

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

4. 目标驱动执行

定义成功标准。循环直到验证通过。

| 不要这样... | 转换为... | |---|---| | "添加验证" | "为无效输入编写测试，然后让它们通过" | | "修复 bug" | "编写复现测试，然后让它通过" | | "重构 X" | "确保重构前后测试都通过" |

对于多步骤任务，陈述简要计划：

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

斜杠命令

/karpathy-check — 对暂存的更改运行完整的四原则审查。

Python 工具（scripts/）

所有工具仅依赖标准库。使用 --help 运行。

| 脚本 | 检测内容 | |---|---| | complexity_checker.py | 过度工程：类过多、嵌套过深、圈复杂度高、未使用参数、过早抽象 | | diff_surgeon.py | Diff 噪音：与目标无关的行 — 注释修改、风格漂移、顺手重构 | | assumption_linter.py | 计划中的隐藏假设：未要求的功能、缺失的澄清、默默的解读选择 | | goal_verifier.py | 薄弱的成功标准：没有可验证检查的模糊计划、缺失的测试断言 |

子代理

karpathy-reviewer — 对 diff 运行全部 4 项原则检查。由 /karpathy-check 调度或在提交前手动运行。

Pre-commit 钩子

hooks/karpathy-gate.sh — 对暂存文件运行 complexity_checker.py 和 diff_surgeon.py。发现违规时发出警告（非阻塞）。通过 .claude/settings.json 或 Husky 配置。

参考资料

• references/karpathy-principles.md — 原始引用、深层上下文、何时放宽每条原则
• references/anti-patterns.md — 10+ 个 Python、TypeScript 和 shell 的前后对比示例
• references/enforcement-patterns.md — 如何配置钩子、CI 集成、团队采用

何时放宽

这些原则偏向谨慎而非速度。对于琐碎任务（修复拼写错误、明显的单行修改），自行判断。这些原则在以下情况最重要：

• 非平凡实现（>20 行改动）
• 你不完全理解的代码
• 需求不明确的多步骤任务
• 任何将被人类审查的代码

跨工具兼容性

通过插件安装到 Claude Code。对于其他工具，将原则复制到你的 schema 文件中：

| 工具 | Schema 文件 | |---|---| | Claude Code | CLAUDE.md（由插件自动加载） | | Codex CLI | AGENTS.md | | Cursor | AGENTS.md 或 .cursorrules | | Antigravity / OpenCode / Gemini CLI | AGENTS.md |

相关技能（通过 context: fork 链接）

• self-eval — 完成工作后的诚实质量评分
• code-reviewer — 更广泛的代码审查；karpathy-coder 专注于 4 个 LLM 特有的陷阱
• llm-wiki — 复合知识；karpathy-coder 确保编码纪律