Karpathy 的 LLM 陷阱清单：用 CLAUDE.md 减少 80% 代码返工

你每天花多少时间在「修 AI 代码」上？

最近我在一个中小型团队做技术调研，发现一个扎心现象：大家用 Claude Code / Copilot 生成代码的热情很高，但花在修改这些代码上的时间，平均占据了每天 30%~50% 的编码时长。这种「高产出的低质量」正在吞噬开发者的有效生产力。

症状很典型：

  • 变量命名一半 camelCase 一半 snake_case，风格不统一
  • 明明项目里已经有通用的工具函数，LLM 却总是自己再写一遍
  • 边界条件不处理，参数校验缺失，上线后频繁报错
  • 函数一两百行，逻辑耦合严重，review 的时候被疯狂打回

Andrej Karpathy 是最早系统总结 LLM 编码陷阱的人之一。他在推文里列举了 20 多个常见问题，比如「不要假设用户输入正确」「不要省略错误处理」「注释要写 why 而不是 what」等等。而最近 GitHub 上一个名为 multica-ai/andrej-karpathy-skills 的项目，把这些陷阱打包成了一个 CLAUDE.md 文件，让 Claude Code 在生成代码时自动遵守这些规则。项目发布当天就涨了 15 万 star，说明大家对这个痛点的共鸣有多强烈。

核心思路：把「编码规范」写进 AI 的基因里

以前我们怎么让 LLM 生成符合规范的代码？全靠手动写 prompt：

“请使用 TypeScript，用函数式风格，不要魔法数字，先写测试……”

结果每次对话都要重复一遍，而且还经常被忽略。因为 LLM 的上下文窗口是有限的，你的 prompt 越长，它越容易在生成中途“分心”。

CLAUDE.md 的解决方案很巧妙： 在项目根目录放一个 Markdown 文件，Claude Code 在每次交互时都会自动读取它，并作为 最高优先级的系统指令 来遵循。本质上是把编码规范从「人肉记忆」转移到了「AI 的内存里」。

这个文件的作用类似于 .gitignore——你只需要维护一份，团队所有人都能共享，每次生成代码时自动生效。唯一的区别是它只作用于 Claude Code（其他 AI 工具目前不兼容）。

工具实现：你的第一份 CLAUDE.md 应该写什么？

项目 multica-ai/andrej-karpathy-skills 提供了一个开箱即用的模板。我结合 Karpathy 的陷阱清单和实际项目经验，整理了一份生产可用版（经过自己项目实测）。

基础结构（必须放在项目根目录）

text
1 2 3 4 
./
├── CLAUDE.md       # 全局规则
└── .claude/        # 可选：分模块规则
    └── CLAUDE.md   # 子目录下的覆盖规则

核心内容（基于 Karpathy 陷阱清单）

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 
# CLAUDE.md - Coding Rules for This Project

## General Guidelines
- Use TypeScript (strict mode) for all new code.
- Prefer pure functions and immutability. Avoid classes unless performance-critical.
- Never write a function longer than 50 lines. If needed, break into smaller helpers.
- No magic numbers: define constants with descriptive names.

## Trap Avoidance (from Andrej Karpathy's list)
- **Assume nothing about inputs**: always validate parameters with explicit type guards.
- **Don't hallucinate APIs**: before using a library function, verify it exists in the current version. If unsure, check the actual import path.
- **Avoid code duplication**: scan the project for existing similar functions first. Reuse them.
- **Write comments only for WHY**: do not restate what the code does. Explain design decisions, trade-offs, or unusual edge cases.
- **Error handling is not optional**: every external call (API, file system, DB) must have try/catch with proper logging and fallback.
- **Performance matters**: prefer array methods over for-loops for readability, but use for-loops for hot paths (document with a comment).

## Project-Specific
- Do NOT import from `lodash`; use native ES2022 alternatives.
- Test file must be created in the same directory following the pattern `*.test.ts`.
- Commit messages must follow Conventional Commits (feat/fix/chore).

!claude-md-config-example(示例：CLAUDE.md 文件在 VS Code 中的显示，包含规则列表和文件树结构。用于说明文件放置位置和内容格式。)

进阶技巧：分层规则

如果项目很大，可以在子目录下放额外的 CLAUDE.md。例如 src/utils/ 下的规则更强调纯工具函数。Claude Code 会合并全局和局部的规则，但局部优先级更高。

实际效果：从「反复修改」到「一次通过」

我拿一个真实的 React + Node.js 项目做了对照测试。用相同的 prompt 生成一个「用户注册接口」：

  • 未用 CLAUDE.md：生成的代码有 5 个问题 —— 密码哈希用了 md5（应该用 bcrypt）、没有验证邮箱格式、错误信息是英文硬编码、路由直接在 app.use 里写、注册成功后的 201 状态码写成了 200。
  • 用了 CLAUDE.md（上面的模板）：生成的代码直接用了 bcrypt、有 validator.isEmail 校验、错误信息用了国际化的 t() 函数、路由抽到了单独的文件、状态码正确。前后花了 3 分钟生成，0 处修改。

当然，这不是科学实验，但类似的结果在社区报告里多次出现。Karpathy 本人也表示，使用这种方式后，“90% 的代码不需要人工修改”。我的判断是：对于 80% 的常规 CRUD 业务代码，CLAUDE.md 确实能规避掉大部分低级错误，显著减少 code review 压力。

落地注意事项：别踩这些坑

  1. CLAUDE.md 不是银弹：它只对 Claude Code 有效。如果你团队主要用 GitHub Copilot 或 Cursor，这个文件会被忽略。不过 Anthropic 最近开放了 CLAUDE.md 的规范，未来其他工具也可能会支持。
  2. 规则越多，效果越差：我的经验是规则数量控制在 20 条以内，每条一句话。过多的约束会让 Claude Code 在生成时“困惑”，反而出现不符合任何一条的奇怪输出。
  3. 版本管理：CLAUDE.md 应该纳入 Git，每次修改都要经过团队 review，就像更新 .eslintrc 一样。
  4. 你需要持续迭代：Karpathy 的陷阱清单是起点，但你的项目可能有独特的要求（比如某些数据不能缓存、特定模块必须用类）。建议每两周回顾一次 CLAUDE.md，删掉无效规则，加入新发现的陷阱。
  5. 不要只抄网上的模板：我见过直接把 Karpathy 的推文复制进来的团队，结果提示太抽象（比如“不要过度工程”），Claude Code 不理解什么叫“过度”。要用具体例子，比如“禁止在单行代码中使用 3 层以上的箭头函数嵌套”比“保持简单”有效。

!code-quality-comparison(图表对比：使用 CLAUDE.md 前后，代码在 code review 中的平均问题数、首次通过率、修改耗时。数据基于 10 次重复实验取中位数。)

我的观点：CLAUDE.md 将成为下个 .editorconfig

两年前，.editorconfig 和 .prettierrc 还是“高级配置”，现在几乎每个项目都标配了。因为格式化过程不再需要人工参与。同样，随着 LLM 辅助编码成为常态，我们需要一种声明式的方式，把编码规范和业务约束“告诉” AI，而不是每次人肉对话。

CLAUDE.md 的底层逻辑其实是“Prompt 工程的结构化”——它把可复用的规则独立出来，与对话内容解耦。这比在 prompt 里写一大段杂乱的约束要可靠得多。

但要注意：这个项目本质上是 Karpathy 个人经验的打包，不是官方规范。如果你在用 Claude Code，建议基于它调整，而不是原封不动地用。比如你的项目用的是 React+JavaScript，那就删掉 TypeScript 的规则，加上 React hooks 的约定。

最后，我猜未来一年内，类似 CLAUDE.md 的机制会出现在多个主流 AI 编码工具中。届时，维护一份“AI 行为规范”将成为开发者日常工作的一部分。现在开始实践，你就比别人早一步进入“AI 代码质量可控”的阶段。

参考资料