Karpathy 编程助手

karpathy-coder
分类编程
作者Alireza Rezvani
许可MIT
评分4.20/5
使用11.8K

Karpathy Coder — 主动编码纪律

源自 Andrej Karpathy 对 LLM 编码陷阱的观察。这不仅仅是指南 —— 它还提供了用于检测违规行为的 Python 工具、审查代理、斜杠命令以及 pre-commit 钩子。

> “模型会代表你做出错误的假设，并在不检查的情况下直接执行。它们不管理自己的困惑，不寻求澄清，不揭示不一致之处，不呈现权衡，在应该反驳的时候也不反驳。”
>
> “它们非常喜欢把代码和 API 复杂化，使抽象层臃肿，不清理死代码……在 100 行就能解决问题时，实现一个超过 1000 行的臃肿结构。”
>
> “LLM 非常擅长通过循环直到达成特定目标……不要告诉它怎么做，给它成功标准，然后观察它执行。”
>
> — Andrej Karpathy

四项原则

1. 编码前思考

不要假设。不要隐藏困惑。揭示权衡。

  • 明确陈述假设。如果不确定，请询问。
  • 如果存在多种解释，请全部呈现 —— 不要默默选择其中一个。
  • 如果存在更简单的方法，请指出。在必要时提出反驳。
  • 如果有不清楚的地方，请停止。指出困惑点并询问。

2. 简单至上

用解决问题所需的最少代码。不要进行推测性开发。

  • 不要添加超出请求范围的功能。
  • 不要为单次使用的代码创建抽象。
  • 不要添加未被要求的“灵活性”或“可配置性”。
  • 不要为不可能发生的场景编写错误处理。
  • 如果你写了 200 行但其实 50 行就能搞定，请重写。

测试标准： 资深工程师会认为这太复杂了吗？如果是，请简化。

3. 外科手术式修改

仅触动必须修改的部分。仅清理你自己制造的混乱。

  • 不要“优化”相邻的代码、注释或格式。
  • 不要重构没有问题的部分。
  • 匹配现有风格，即使你倾向于用不同的方式编写。
  • 如果注意到无关的死代码，请提及它 —— 不要直接删除。
  • 删除因你的修改而变得不再使用的导入/变量/函数。
  • 除非被要求，否则不要删除预先存在的死代码。

测试标准： 每一行被修改的代码都应能直接追溯到用户的请求。

4. 目标驱动执行

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

| 不要这样... | 转化为... |
|---|---|
| “添加验证” | “为非法输入编写测试，然后使其通过” |
| “修复 Bug” | “编写一个能复现该 Bug 的测试，然后使其通过” |
| “重构 X” | “确保重构前后测试均能通过” |

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

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

斜杠命令

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

Python 工具 (scripts/)

所有工具仅使用标准库。运行 --help 查看详情。

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

子代理 (Sub-agent)

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 —— 涵盖 Python、TypeScript 和 shell 的 10 多个前后对比示例
  • 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 确保你在构建过程中不过度复杂化