一个 CLAUDE.md 文件刚刚获得了 19.2 万个 GitHub Star。

（源自 Karpathy 的编码规则）

Andrej Karpathy 观察到，LLM 在编写代码时会犯同样的可预测错误：过度工程化、忽略现有模式，以及添加你从未要求的依赖。

如果你用过 AI 编码助手，你一定遇到过所有这些问题。

但关键在于：

如果错误是可预测的，那么你可以用正确的指令来预防它们。

这正是这个 CLAUDE.md 所做的。你只需将一个 markdown 文件放入你的仓库，它就能为 Claude Code 提供一套结构化的行为准则，适用于整个项目。

这很重要。

• 完全围绕 AI 编码助手的提示工程构建
• 没有框架，没有复杂工具，只有一个能塑造行为的 .md 文件

开发者已经超越了“用 AI 写代码”的阶段，进入了“设计 AI 的行为，让代码真正高质量”的阶段。

Claude Code 的生态系统正在快速增长，而其中最好的工具并不总是软件。有时它们只是精心编写的指令。

100% 开源。

GitHub 仓库链接：https://github.com/multica-ai/andrej-karpathy-skills…

另外，我写过一篇关于 .claude 文件夹结构的文章，有 1100 万人阅读过。

这是一份关于 CLAUDE.md、hooks、skills、agents 和权限的完整指南，以及如何正确设置它们。

文章内容如下。

multica-ai/andrej-karpathy-skills

来源：https://github.com/multica-ai/andrej-karpathy-skills

受 Karpathy 启发的 Claude Code 指南

看看我的新项目 Multica (https://github.com/multica-ai/multica)——一个用于运行和管理带有可复用技能（skills）的编码代理的开源平台。

在 X 上关注我：https://x.com/jiayuan_jy

一个 CLAUDE.md 文件，用于改进 Claude Code 的行为，源自 Andrej Karpathy 对 LLM 编码陷阱的观察 (https://x.com/karpathy/status/2015883857489522876)。

English | 简体中文

问题

来自 Andrej 的帖子：

“模型会替你做错误的假设，然后直接执行，而不去核实。它们不会管理自己的困惑，不会寻求澄清，不会暴露不一致，不会呈现权衡，也不会在应该的时候提出异议。”

“它们非常喜欢过度复杂化代码和 API，膨胀抽象，不清理死代码……用 1000 行实现一个臃肿的结构，而 100 行就足够了。”

“它们有时仍会修改/删除它们并不完全理解的注释和代码，即使这些修改与任务无关。”

解决方案

一个文件中包含四个原则，直接解决这些问题：

四个原则详解

1. 先思考，再编码

不要假设。不要隐藏困惑。呈现权衡。

LLM 常常默默地选择一种解释然后执行。这个原则迫使进行显式推理：

• 明确陈述假设——如果不确定，就问出来，不要猜
• 提供多种解释——存在歧义时，不要默默选择
• 在必要时提出异议——如果有更简单的方法，就说出来
• 困惑时停下来——指出不清楚的地方并要求澄清

2. 简洁优先

解决问题的最小代码。没有推测性内容。

对抗过度工程化的倾向：

• 不要超出要求的功能
• 不要为一次性使用的代码创建抽象
• 不要添加未被要求的“灵活性”或“可配置性”
• 不要为不可能的场景编写错误处理
• 如果 200 行可以写成 50 行，就重写

检验标准： 一个高级工程师会认为这过于复杂吗？如果是，简化。

3. 外科手术式修改

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

编辑现有代码时：

• 不要“改进”相邻的代码、注释或格式
• 不要重构未损坏的东西
• 匹配现有风格，即使你会用不同方式做
• 如果发现无关的死代码，提出来——但不要删除

当你的修改产生了孤立的代码：

• 删除你的修改导致不再使用的导入/变量/函数
• 不要删除先前存在的死代码，除非被要求

检验标准： 每一处修改的行都应直接追溯到用户的请求。

4. 目标驱动执行

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

将命令式任务转化为可验证的目标：

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

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

强的成功标准让 LLM 能够独立循环。弱的标准（“让它工作”）需要不断的澄清。

安装

选项 A：Claude Code 插件（推荐）

在 Claude Code 中，首先添加市场中：

/plugin marketplace add forrestchang/andrej-karpathy-skills

然后安装插件：

/plugin install andrej-karpathy-skills@karpathy-skills

这会将这些指南作为 Claude Code 插件安装，使该技能在你的所有项目中可用。

选项 B：CLAUDE.md（按项目）

新项目：

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

已有项目（追加）：

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

在 Cursor 中使用

该仓库包含一个已提交的 Cursor 项目规则（.cursor/rules/karpathy-guidelines.mdc），因此当你用 Cursor 打开该项目时，相同的指南适用。详见 CURSOR.md 了解设置、在其他项目中使用该规则，以及它与 Claude Code 的关系。

关键洞察

来自 Andrej：

“LLM 在循环直到达到特定目标方面异常擅长……不要告诉它做什么，给它成功标准，然后看着它执行。”

“目标驱动执行”原则捕捉了这一点：将命令式指令转化为带有验证循环的声明式目标。

如何判断它在发挥作用

如果你看到以下情况，说明这些指南在起作用：

• 差异中不必要的修改更少——只出现请求的修改
• 因过度复杂化而重写的情况更少——代码第一次写出来就很简单
• 澄清性问题在实现之前提出——而不是在犯错之后
• 干净、最小的 PR——没有顺带的重构或“改进”

自定义

这些指南设计为与项目特定指令合并。将它们添加到现有的 CLAUDE.md 中，或创建一个新的。

对于项目特定规则，添加如下的部分：

## 项目特定指南

- 使用 TypeScript 严格模式
- 所有 API 端点必须有测试
- 遵循 `src/utils/errors.ts` 中的现有错误处理模式

权衡说明

这些指南倾向于谨慎重于速度。对于简单任务（简单的拼写修复、显而易见的一行代码），请自行判断——并非每次修改都需要全部严谨步骤。

目标是减少重要工作中的昂贵错误，而不是拖慢简单任务。

许可

MIT