Back to Details

karpathy-coder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Karpathy Coder — Active Coding Discipline

Karpathy Coder——主动编码准则

Derived from Andrej Karpathy's observations on LLM coding pitfalls. This is not just guidelines — it ships Python tools that detect violations, a review agent, a slash command, and a pre-commit hook.
"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
源自Andrej Karpathy对LLM编码陷阱的观察（链接：https://x.com/karpathy/status/2015883857489522876）。这**不仅仅是指导方针**——它配套了用于检测违规的Python工具、评审Agent、斜杠命令和预提交钩子。
“模型会擅自替你做出错误假设，并且不加验证地继续执行。它们不会管理自身的困惑，不会寻求澄清，不会指出矛盾，不会呈现权衡方案，也不会在该质疑时提出反对。”
“它们非常喜欢把代码和API复杂化，过度抽象，不清理无用代码……明明100行就能解决的问题，却写出1000行的冗余结构。”
“LLMs在循环执行直至达成特定目标方面表现异常出色……不要告诉它具体怎么做，给它成功标准，然后看它推进。”
—— Andrej Karpathy

The four principles

四大原则

1. Think Before Coding

1. 编码前先思考

Don't assume. Don't hide confusion. Surface tradeoffs.
  • State assumptions explicitly. If uncertain, ask.
  • If multiple interpretations exist, present them — don't pick silently.
  • If a simpler approach exists, say so. Push back when warranted.
  • If something is unclear, stop. Name what's confusing. Ask.
不要假设，不要掩盖困惑，明确权衡方案。
  • 明确陈述假设。若有不确定，主动询问。
  • 若存在多种解读，全部列出——不要默默选择一种。
  • 若有更简单的方案，直接说明。在必要时提出反对。
  • 若有不清楚的地方，暂停。指出困惑点并询问。

2. Simplicity First

2. 简洁优先

Minimum code that solves the problem. Nothing speculative.
  • No features beyond what was asked.
  • No abstractions for single-use code.
  • No "flexibility" or "configurability" that wasn't requested.
  • No error handling for impossible scenarios.
  • If you write 200 lines and it could be 50, rewrite it.
The test: Would a senior engineer say this is overcomplicated? If yes, simplify.
用最少的代码解决问题，不做无意义的拓展。
  • 不添加需求外的功能。
  • 不针对单次使用的代码做抽象。
  • 不添加未被要求的“灵活性”或“可配置性”。
  • 不为不可能出现的场景做错误处理。
  • 若写了200行但其实50行就能解决，重写代码。
**测试标准：**资深工程师会不会觉得这段代码过于复杂？如果是，就简化。

3. Surgical Changes

3. 精准修改

Touch only what you must. Clean up only your own mess.
  • Don't "improve" adjacent code, comments, or formatting.
  • Don't refactor things that aren't broken.
  • Match existing style, even if you'd do it differently.
  • If you notice unrelated dead code, mention it — don't delete it.
  • Remove imports/variables/functions that YOUR changes made unused.
  • Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
只修改必要部分，只清理自己造成的冗余。
  • 不要“优化”无关的代码、注释或格式。
  • 不要重构未损坏的代码。
  • 匹配现有代码风格，即使你有不同偏好。
  • 若发现无关的无用代码，只需提及——不要删除。
  • 删除因你的修改而变得无用的导入/变量/函数。
  • 除非被要求，否则不要删除已存在的无用代码。
**测试标准：**每一处修改都应直接对应用户的需求。

4. Goal-Driven Execution

4. 目标导向执行

Define success criteria. Loop until verified.
Instead of...Transform to...
"Add validation""Write tests for invalid inputs, then make them pass"
"Fix the bug""Write a test that reproduces it, then make it pass"
"Refactor X""Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
定义成功标准，循环执行直至验证通过。
不要写...要改成...
“添加验证”“编写针对非法输入的测试，然后让测试通过”
“修复bug”“编写复现bug的测试，然后让测试通过”
“重构X”“确保重构前后测试都能通过”
对于多步骤任务，列出简要计划：
1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]

Slash command

斜杠命令

/karpathy-check
— Run the full 4-principle review on your staged changes.
/karpathy-check
—— 对暂存的变更运行完整的四大原则评审。

Python tools (
scripts/
)

Python工具（
scripts/
目录）

All tools are stdlib-only. Run with 
--help
.
ScriptWhat it detects
complexity_checker.py
Over-engineering: too many classes, deep nesting, high cyclomatic complexity, unused params, premature abstractions
diff_surgeon.py
Diff noise: lines that don't trace to the stated goal — comment changes, style drift, drive-by refactors
assumption_linter.py
Hidden assumptions in a plan: unasked features, missing clarifications, silent interpretation choices
goal_verifier.py
Weak success criteria: vague plans without verifiable checks, missing test assertions
所有工具仅依赖标准库。使用
--help
查看帮助。
脚本检测内容
complexity_checker.py
过度设计：类过多、嵌套过深、圈复杂度高、未使用参数、过早抽象
diff_surgeon.py
冗余变更：与既定目标无关的代码行——注释修改、风格偏移、顺带重构
assumption_linter.py
计划中的隐藏假设：未被要求的功能、缺失的澄清、默默做出的解读选择
goal_verifier.py
模糊的成功标准：无验证检查的模糊计划、缺失的测试断言

Sub-agent

子Agent

karpathy-reviewer
— Runs all 4 principles against a diff. Dispatched by 
/karpathy-check
or manually before committing.
karpathy-reviewer
—— 针对代码变更运行全部四大原则检查。可通过
/karpathy-check
触发，或在提交前手动运行。

Pre-commit hook

预提交钩子

hooks/karpathy-gate.sh
— runs 
complexity_checker.py
and 
diff_surgeon.py
on staged files. Warns (non-blocking) when violations are found. Wire it via 
.claude/settings.json
or Husky.
hooks/karpathy-gate.sh
—— 对暂存文件运行
complexity_checker.py
和
diff_surgeon.py
。当检测到违规时发出警告（非阻塞）。可通过
.claude/settings.json
或Husky配置。

References

参考资料

  • references/karpathy-principles.md
    — the source quotes, deeper context, when to relax each principle
  • references/anti-patterns.md
    — 10+ before/after examples across Python, TypeScript, and shell
  • references/enforcement-patterns.md
    — how to wire hooks, CI integration, team adoption
  • references/karpathy-principles.md
    —— 原始引用、更详细的背景信息、何时放宽各原则
  • references/anti-patterns.md
    —— 10+个Python、TypeScript和Shell语言的正反示例
  • references/enforcement-patterns.md
    —— 如何配置钩子、CI集成、团队落地方法

When to relax

何时放宽原则

These principles bias toward caution over speed. For trivial tasks (typo fixes, obvious one-liners), use judgment. The principles matter most on:
  • Non-trivial implementations (>20 lines changed)
  • Code you don't fully understand
  • Multi-step tasks with unclear requirements
  • Anything that will be reviewed by humans
这些原则偏向谨慎优先于速度。对于琐碎任务（拼写错误修复、明显的单行修改），可灵活判断。原则在以下场景中最为重要：
  • 非 trivial 的实现（变更超过20行）
  • 你不完全理解的代码
  • 需求不明确的多步骤任务
  • 任何需要人工评审的内容

Cross-tool compatibility

跨工具兼容性

Installs via plugin for Claude Code. For other tools, copy the principles into your schema file:
ToolSchema file
Claude Code
CLAUDE.md
(auto-loaded by plugin)
Codex CLI
AGENTS.md
Cursor
AGENTS.md
or 
.cursorrules
Antigravity / OpenCode / Gemini CLI
AGENTS.md
可通过Claude Code插件安装。对于其他工具，将原则复制到对应的 schema 文件中：
工具Schema文件
Claude Code
CLAUDE.md
（插件自动加载）
Codex CLI
AGENTS.md
Cursor
AGENTS.md
或 
.cursorrules
Antigravity / OpenCode / Gemini CLI
AGENTS.md

Related skills (chains via 
context: fork
)

相关技能（通过
context: fork
关联）

  • self-eval
     — honest quality scoring after completing work
  • code-reviewer
     — broader code review; karpathy-coder focuses on the 4 LLM-specific pitfalls
  • llm-wiki
     — compound knowledge; karpathy-coder ensures you don't overcomplicate while building it
  • self-eval
     —— 完成工作后进行客观的质量评分
  • code-reviewer
     —— 更全面的代码评审；karpathy-coder专注于4个LLM特有的编码陷阱
  • llm-wiki
     —— 复合知识构建；karpathy-coder确保你在构建过程中不会过度复杂化