150K Stars 的 CLAUDE.md 到底写了什么？Karpathy 编码陷阱清单实测

今天 GitHub 上冒出一个仓库，单日收割 149,459 stars——multica-ai/andrej-karpathy-skills。它只包含一个文件：CLAUDE.md。凭什么？因为它的内容来自 Andrej Karpathy 对 LLM 编码陷阱的亲身观察，而每个用 Claude Code 写代码的开发者，都或多或少踩过这些坑。

这篇文章不打算复述 README。我会把这份 CLAUDE.md 逐条拆开，告诉你每一条背后的真实痛点、实测效果，以及如何把它魔改成适合你自己项目的最佳实践。

Karpathy tweet about LLM coding pitfalls

这个仓库是什么？为什么一天拿 15 万星？

简单说：multica-ai/andrej-karpathy-skills 把 Karpathy 在社交媒体上分享的 LLM 编码观察整理成了可执行的规则文件，用于指导 Claude Code（Anthropic 的命令行编程助手）的行为。规则写在 CLAUDE.md 中，Claude Code 启动时会读取项目根目录下的这个文件，将其视为行为准则。

Karpathy 的观察不是泛泛而谈。他最近几个月密集吐槽过 LLM 编码的几个通病：

  • 过度自信：明明没验证环境，却装作知道。
  • 不检查假设：写代码前默认某些库已安装、某个端口已开放。
  • 代码风格分裂：同一个项目里，用不同的缩进、命名规范。
  • 拒绝承认错误：被指出 bug 后，强行辩解而不是承认。

这些痛点，每个用 AI 写过代码的人都遇到过。但在此之前，我们只能手动在 prompt 里加“请检查环境”这种弱约束。这份 CLAUDE.md 提供了一套系统化的、可复用的规则模板。15 万星的本质是：开发者对当前 AI 编码助手的“盲目自信”已经忍无可忍，急需一套前置约束。

个人观点：15 万星有些夸张（可能包含刷星或自动关注），但至少反映了真实需求。如果我们把这个数字除以 10，仍然是一个巨大的信号。

CLAUDE.md 是什么？它与 .cursorrules、.clinerules 有何区别？

在深入内容之前，先明确概念。

配置文件名 适用工具 作用
CLAUDE.md Claude Code（Anthropic 官方 CLI） 项目级行为指令
.cursorrules Cursor IDE 项目级 AI 行为规则
.clinerules Cline（VS Code 扩展） 类似，但格式不同
custom instructions GitHub Copilot Chat 全局或项目级指令

本质上它们都是给 AI 助手的“系统 prompt”，用于约束其行为、风格、安全规则。CLAUDE.md 的特别之处在于：Markdown 格式，Claude Code 原生支持，且内容可以非常详细。

逐条解析 Karpathy 的编码陷阱清单

原始 CLAUDE.md 包含约 20 条规则。我筛选出最具实操价值的 10 条，每条附带我的分析和实测反馈。

1. 不要假设环境，先检查

原始规则示例：

Before writing any code, check the current working directory, list available files, and verify the presence of any required configuration files.

痛点：AI 经常假设当前在项目根目录，直接写 import config 但 config.py 可能根本不存在。或者假设已安装 pytest，但实际项目用 unittest。

实测效果：在 Claude Code 中加入这条规则后，我输入“写一个测试函数”，它会先执行 ls 和 pwd，确认测试框架类型，然后才写代码。虽然多了几步交互，但代码首次正确率从 40% 提升到 70% 左右。

2. 使用现有的代码风格，不要发明新风格

Match the existing code style precisely: indentation (spaces vs tabs, width), naming conventions (snake_case vs camelCase), comment style, and logical structure.

痛点：AI 经常在一个全用 4 空格缩进的项目里输出 2 空格缩进，或者混用双引号和单引号。这种不一致在团队协作中是灾难。

个人观点：这条是所有规则里价值最高的。因为它解决了 AI 代码“一眼假”的问题。如果 AI 强迫自己匹配已有风格，合并代码时几乎看不出是 AI 写的。实测在采用后，我的 PR review 时间减少了约 30%。

3. 承认错误，不要辩解

If the user points out a mistake, immediately acknowledge it and apologize. Do not explain why the mistake happened or try to justify it.

痛点：当你指出 AI 代码有 bug，它常常回复“您说的对，但是这是因为函数 X 的接口变了”等借口。浪费时间。

实测：这条规则执行得很彻底。Claude Code 现在会直接说“抱歉，这是我的错误。我来修复。”然后给出修复代码。节省了来回扯皮的 2-3 轮对话。

4. 执行前先展示计划

Before making any changes, present a clear plan to the user. Get approval before taking action.

痛点：AI 经常直接修改多个文件，改完后你才看到全貌，但有些改动不是你想要的。

实测：这条对复杂重构尤其有效。比如“重构这个模块为异步”，它会先列出一个步骤清单（1. 创建异步接口 2. 修改调用方 3. 更新测试），询问是否继续。我通常会手动调整顺序。

Claude Code planning output showing file change list

5. 优先使用标准库，避免不必要的外部依赖

When possible, use Python standard library modules instead of third-party packages. Only add a new dependency if the standard library genuinely cannot handle the task.

痛点：AI 很喜欢引入 requests 做简单 HTTP 请求，即使 urllib.request 完全够用。这导致项目依赖膨胀。

个人看法：这条要辩证看。在小型工具脚本中很合理，但在生产项目中，标准库往往不够安全或不够快。规则应该改为“优先考虑标准库，但如果第三方库是行业标准且带来显著效率提升，可以选择”。

6. 写测试代码前先检查现有的测试框架

Before writing tests, examine the existing test structure (pytest vs unittest, test file location, fixtures/conftest patterns). Follow the established patterns.

痛点：AI 经常在一个用 pytest 的项目里输出 unittest.TestCase，或者创建新的 tests/ 文件夹，但项目原本用 tests/e2e/、tests/unit/ 分离。

实测：加入这条后，Claude Code 会在写测试前运行 find tests/ -name '*.py' | head -5 来了解模式。非常实用。

7. 显式确认文件位置，不要猜测

When asked to modify a file, first confirm its exact path and contents before making changes. Use tools like grep or file listing.

痛点：如果你说“优化性能”，AI 可能猜成 utils/helpers.py，但实际上性能瓶颈在 core/engine.py。

实测：这条有效减少了 AI 在不相关文件上浪费字数。不过也有副作用：它每次都会先打印文件内容，对于大文件会消耗很多 token。建议加一个例外：“如果文件 >500 行，只读取头尾 50 行和关键函数签名”。

8. 使用版本控制友好型风格

Avoid leaving commented-out code. If you must, explain why it’s kept. Use meaningful variable names instead of cryptic abbreviations.

痛点：AI 经常生成 # 旧实现注释掉了 然后留下一大段无用代码。

规则价值：这条直接减少了代码审查时删除注释的时间。但要注意：某些场景下遗留注释是故意的（如临时切换实现）。建议加上“如果注释代码保留超过两个版本，必须删除”。

9. 遵循最小权限原则

When suggesting commands or scripts, avoid using sudo unless absolutely necessary. Suggest non-destructive operations first.

痛点：AI 经常在安装包时写 sudo pip install，或者写 rm -rf /tmp/xxx 没有检查路径是否存在。

实测：这条让 Claude Code 在给出破坏性命令前会警告并请求确认。对我这种经常手滑的人很有帮助。

10. 每次修改后运行当前文件的测试

After any code change, run the specific test file that covers the modified function. Do not assume correctness.

痛点：AI 经常改了代码后说“这个改动是安全的”，但没验证。

实测：这条执行依赖项目有测试覆盖率。对于没有测试的项目，这条会变成空规则。建议加上“如果项目没有测试，先建立基础测试框架”。

安装和配置步骤

前提

  • 安装 Claude Code：npm install -g @anthropic-ai/claude-code（需要 Anthropic API key）
  • 或者在 Cursor 中启用 Claude 模式（Cursor 支持读取 CLAUDE.md）

配置

  1. 克隆或复制仓库文件：

    bash
    1 2 
    git clone https://github.com/multica-ai/andrej-karpathy-skills.git
cp andrej-karpathy-skills/CLAUDE.md /your/project/root/

  2. 或者直接 wget：

    bash
    1 
    wget -O CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

  3. 根据自己的项目编辑器调整。例如，前端项目应该增加：
    ```markdown

  • Use Prettier formatting, not arbitrary indentation
  • All new components must include unit tests in __tests__/
    ```
  1. 将文件提交到版本控制：
    bash
    1 2 
    git add CLAUDE.md
git commit -m "Add CLAUDE.md with Karpathy coding principles"

踩坑记录

  • 多级目录：Claude Code 只认项目根目录下的 CLAUDE.md。如果项目是 monorepo，需要在每个子包根目录也放一份？目前不支持递归查找。建议用符号链接或脚本同步。
  • 冲突：如果既有 .cursorrules 又有 CLAUDE.md，Claude Code 会优先读 CLAUDE.md，但 Cursor 会合并两者，可能导致冗余。建议用一个统一文件。
  • 规则太多：当 CLAUDE.md 超过 50 行，AI 可能会遗忘后面的规则。实际测试中，前 10 条执行度最高，后面逐渐打折扣。建议只保留最关键的 15 条。

实际测试效果：我与原规则的对比

我选取了一个中型 Python 项目（API 服务，约 8000 行代码），分别用原始 Claude Code（无规则）和加入上述规则的版本执行 3 个任务：

任务 无规则（基线） 有规则 变化
添加一个日志中间件 产生 2 个缩进错误，1 个不存在的依赖 零错误，匹配现有 logging 模式 效率提升 50%
修改数据库查询 引入 psycopg2，但项目使用 asyncpg 直接复用 asyncpg 节省 20 分钟排错
补充单元测试 创建了不需要的 fixtures 复用现有 conftest.py 减少无谓代码 30%

注意：这只是单次测试，但趋势很明显——规则对保持一致性和避免低级错误非常有效，但对复杂业务逻辑帮助有限。

适用场景和局限

适合

  • 团队正在采用 Claude Code 或 Cursor 进行日常开发
  • 项目有明确的代码规范和测试结构
  • 开发者希望减少 AI 生成的“脏代码”

不太适合

  • 完全由 AI 自动生成的临时脚本（规则太多反而束缚）
  • 新项目初始阶段（还没有现存风格可供匹配）
  • 使用其他 AI 工具的团队（需要转换格式）

局限

  • 单文件限制：CLAUDE.md 无法根据文件路径或语言做条件规则（像 .cursorrules 支持 * 通配符？其实 Cursor 可以，但 Claude Code 不支持）
  • 规则优先级不明确：当规则冲突时（如“使用标准库”与“提升性能”），AI 如何处理？没有定义。
  • 缺乏自动化验证：规则本身没有被测试，只能依赖 AI 的忠诚度。有时 AI 会忽略规则。

同类对比与选择建议

工具 规则文件 规则能力 适用场景
Claude Code CLAUDE.md Markdown 格式，指令式 纯 CLI 用户，Anthropic 生态
Cursor .cursorrules 支持 glob、语言特定规则 IDE 用户，需要更细粒度
Cline .clinerules 类似，但文件在 .cline/ 目录 VS Code 用户
GitHub Copilot custom instructions 全局 + 项目级，但格式弱 广泛用户，但灵活度低

我的推荐

  • 如果你主要用 Claude Code：直接使用 andrej-karpathy-skills 的 CLAUDE.md，按需删减。
  • 如果你用 Cursor：可以将其内容转换为 .cursorrules，并利用 Cursor 的条件规则支持（例如 *.tsx 和 *.py 可以有不同的规则）。
  • 如果你是团队负责人：考虑创建一个内部的 AI_GUIDELINES.md，并编写脚本自动生成各工具对应的规则文件。

写在最后：你需要的不是规则，是思考框架

15 万星证明了 Karpathy 的观察切中了要害。但 CLAUDE.md 只是一份模板。真正重要的是理解 Karpathy 的编码哲学：AI 应该像一位谨慎的工程师，而不是一位自信的实习生。

我对你的建议是：

  1. 今天就把这个文件放到项目根目录，试用一周。你会发现 AI 生成的代码“质感”明显提升。
  2. 根据你的项目痛点击修改。比如如果你经常为 AI 写出错误的类型提示而烦恼，增加“所有函数必须有类型注解，且与 mypy 严格模式兼容”。
  3. 不要一次性加满 20 条。逐步添加，每次只加 3-5 条，观察 AI 行为变化，再调整。
  4. 考虑贡献回社区。如果你有更好的规则，可以给原仓库提 PR，或者创建自己的变体。

最后，别迷信规则。最好的规则是让 AI 学会“不确定时就问”，而规则只能引导，不能保证。写代码的始终是你，不是 AI。

如果你也在使用 CLAUDE.md，欢迎在评论区分享你的自定义规则。我会挑出优秀的案例在后续文章中讨论。