karpathy-coder

Karpathy Coder — 主动式编码纪律

本项目源自 Andrej Karpathy 对 LLM 编码陷阱的观察。它不只是指导原则，还附带用于检测违规的 Python 工具、一个审查 Agent、一个斜杠命令和一个 pre-commit 钩子。

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

"LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."

— Andrej Karpathy

四项原则

1. 编码前先思考

不要臆测。不要掩盖困惑。提出权衡。

• 明确说明假设。如果不确定，就提问。
• 如果存在多种理解，把它们都列出来，不要悄悄选一个。
• 如果存在更简单的方案，直接说明。必要时提出异议。
• 如果有不清楚的地方，先停下来。指出令人困惑之处，然后提问。

2. 简洁优先

用最少的代码解决问题。不做任何臆测性的扩展。

• 不添加超出要求的功能。
• 不为只使用一次的代码引入抽象。
• 不添加未被要求的“灵活性”或“可配置性”。
• 不为不可能发生的场景编写错误处理。
• 如果你写了 200 行，而其实 50 行就够，就重写。

检验标准： 资深工程师会不会认为这过于复杂？如果会，就简化。

3. 精准修改

只改必须改的部分。只清理自己造成的混乱。

• 不要“顺手改进”相邻的代码、注释或格式。
• 不要重构没有问题的东西。
• 即使你会用不同的方式实现，也要匹配现有风格。
• 如果注意到无关的死代码，请提出来，但不要删除。
• 删除那些因为你的改动而变得未使用的导入、变量或函数。
• 除非被要求，否则不要删除原有的死代码。

检验标准： 每一处改动的代码行都应直接对应用户的请求。

4. 目标驱动执行

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

原始要求……	转化为……
"Add validation"	"编写针对非法输入的测试，然后让它们通过"
"Fix the bug"	"编写一个能复现该问题的测试，然后让它通过"
"Refactor X"	"确保重构前后测试均通过"

对于多步骤任务，先给出一个简要计划：

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

斜杠命令

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

Python 工具（scripts/）

所有工具仅依赖标准库。运行时加 --help 查看用法。

脚本	检测内容
complexity_checker.py	过度设计：类过多、嵌套过深、圈复杂度高、未使用的参数、过早抽象
diff_surgeon.py	差异噪声：与既定目标无关的改动，如注释修改、风格漂移、顺带的重构
assumption_linter.py	计划中隐藏的假设：未经要求的功能、缺失的澄清、悄悄做出的理解选择
goal_verifier.py	薄弱的成功标准：缺乏可验证检查的模糊计划、缺失的测试断言

子 Agent

karpathy-reviewer — 针对一项 diff 运行全部四项原则。由 /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 — 涵盖 Python、TypeScript 和 shell 的 10 个以上前后对比示例
• references/enforcement-patterns.md — 如何接入钩子、CI 集成与团队推广

何时放松

这些原则偏向谨慎优先于速度。对于琐碎任务（例如修正拼写错误、明显的单行修改），请自行判断。这些原则在以下场景最为重要：

• 非琐碎的实现（修改超过 20 行）
• 你不完全理解的代码
• 需求不明确的多步骤任务
• 将由人工审查的任何内容

跨工具兼容性

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

工具	配置文件
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-wiki：积累知识；karpathy-coder 确保你在构建过程中不会把事情复杂化