在飞速发展的 AI 辅助编程领域，一个 GitHub 仓库脱颖而出，成为了 AI 编程 Agent 最受欢迎的行为准则： forrestchang/andrej-karpathy-skills。由开发者 Forrest Chang，它将 Andrej Karpathy 关于 LLM 编程陷阱的疯传观察提炼为一个单一、可操作的 CLAUDE.md 文件。我们调研了 GitHub、Twitter/X、Reddit、网络文章以及源代码本身 — 这就是这份权威指南。
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
🎬 观看视频解析
喜欢阅读？继续向下滚动查看包含代码示例的完整文字指南。
1. 为什么它会走红
让我们先从这个仓库的重要性说起。它成为了 GitHub 上增长最快的仓库之一 — 在发布后的最初几周内就获得了数万个 Star — 对于一个本质上只包含 一个文件。
不是框架，不是库，也不是应用。而是一套针对 AI 编程代理的行为准则。创建于 2026 年 1 月 27 日，基于 MIT license，并且仍在增长。这反映了行业发展方向的一个重要趋势。
为什么这很重要
许多拥有数千名贡献者和多年开发经验的流行开源工具，其 Star 数反而更少。这个仓库凭借 寥寥几次提交和零运行时依赖而走红。其价值不在于代码本身 — 而在于 想法。
2. 起源故事
该仓库可以直接追溯到一条爆火的推文，作者是 Andrej Karpathy — OpenAI 联合创始人、前特斯拉 AI 负责人，也是 “vibe coding” 一词的创造者。在他的帖子中，Karpathy 并没有分享工具或仓库。他分享的是 观察心得 — 一系列关于 LLM 在编写代码时表现出的痛点清单。
过去几周在使用 Claude 编写了大量代码后的一些随笔。
— Andrej Karpathy (@karpathy) 2026 年 1 月 26 日
编程工作流。鉴于 LLM 编程能力的最新提升，和许多人一样，我迅速从 11 月份约 80% 的手动+自动补全编码和 20% 的 Agent 模式，转变为 80% 的 Agent 编码和 20% 的编辑+修饰……
开发者 Forrest Chang 阅读了这些观察心得并付诸实践：他将它们转换成了结构化、机器可读的 CLAUDE.md 文件。不是一篇模糊的博客文章。不是一条 Twitter 推文。一个 配置文件 AI 智能体真正会阅读并遵循的。
核心洞察在于：Karpathy 发现了问题，Forrest Chang 编写了解决方案，而社区验证了这两者 — 这使其成为了 GitHub 上获星最多的 AI 工作流仓库之一。
3. Karpathy 发现的问题
Karpathy's 的观察并非含糊的抱怨。它们是每个使用 AI 编程智能体的开发者都经历过的、具体的、可复现的模式。以下是他的原话：
问题 1：隐藏的假设
“模型会代表你做出错误的假设，并在不进行检查的情况下直接执行。它们不处理自己的困惑，不寻求澄清，不揭示不一致之处，不权衡利弊，也不在应该拒绝时提出异议。”
问题 2：过度工程
“它们非常喜欢把代码和 API 复杂化，让抽象变得臃肿，不清理废弃代码……在 100 行就能搞定的情况下，非要实现一个超过 1000 行的臃肿结构。”
问题 3：意外的副作用
“作为副作用，它们有时仍会修改或删除自己并不充分理解的注释和代码，即使这些内容与当前任务无关。”
如果你使用过 Claude Code、Copilot、Cursor 或任何 AI 编程智能体，你一定深有体会。你让智能体修复一个 Bug，它却重写了半个文件。你让它添加一个功能，它却构建了一个完整的抽象层。你向它寻求帮助，它却带着错误的假设自信地盲目推进。
Reddit 社区（尤其是 r/ClaudeAI 和 r/ClaudeCode）对这种行为有一个广泛使用的术语： “自信的初级开发人员。” AI 速度快、知识广，但如果无人监管，就容易犯天真的错误。它才华横溢但不可靠 — 正是那种需要明确护栏的工程师。
4. 四项原则
Forrest Chang 将 Karpathy 的观察提炼为四项原则。每一项都直接针对特定类别的 LLM 失败案例：
| 原则 | 解决的问题 |
|---|---|
| 编码前先思考 | 错误的假设、隐藏的困惑、缺失的权衡 |
| 简单至上 | 过度复杂化、臃肿的抽象、投机性的功能 |
| 精准变更 | 正交编辑、触碰不该改动的代码、风格偏离 |
| 目标驱动执行 | 模糊的实现、缺乏验证、薄弱的成功标准 |
让我们逐一分解。
原则 1：编码前先思考
“不要假设。不要隐藏困惑。明确权衡。”
这是最基本的原则。LLM 往往会默默选择一种解释并直接执行。这一原则强制进行显式推理：
- 明确陈述假设 — 如果不确定，请询问而不是猜测
- 提供多种解释 — 存在歧义时，不要默默做决定
- 在必要时提出异议 — 如果存在更简单的方法，请直说
- 困惑时请停下 — 指出不明确之处并寻求澄清
示例：隐藏假设陷阱
用户请求： “Add a feature to export user data”
def export_users(format='json'):
users = User.query.all()
# 假设了所有用户、文件位置、字段，
# CSV 字段名 —— 且未进行任何询问
在实现之前，我需要明确：
1. 范围：导出所有用户还是过滤后的子集？
（涉及隐私影响）
2. 格式：下载文件？还是后台任务？
API 端点？
3. 字段：哪些用户字段？
（部分可能涉及敏感信息）
4. 数据量：通常有多少用户？
最简单的方法：添加一个 API 端点，用于
返回分页的 JSON。你更倾向于哪种方式？
原则 2：简单至上
“用最少的代码解决问题。不进行任何推测性开发。”
这可以抑制 LLM 过度设计的倾向。规则非常严格：
- 不提供需求之外的功能
- 不对仅使用一次的代码进行抽象
- 不提供未经要求的“灵活性”或“可配置性”
- 不对不可能发生的场景进行错误处理
- 如果 200 行代码能缩减到 50 行，就重写它
测试标准： 资深工程师会觉得这太复杂了吗？如果是，请简化。
示例：过度抽象的陷阱
用户请求： “添加一个计算折扣的函数”
class DiscountStrategy(ABC):
@abstractmethod
def calculate(self, amount): ...
class PercentageDiscount(DiscountStrategy): ...
class FixedDiscount(DiscountStrategy): ...
class DiscountConfig:
class DiscountCalculator:
# 单次计算需要 50+ 行代码
# 使用前需要 30+ 行的初始化设置
def calculate_discount(amount, percent):
"""计算折扣。percent 取值范围为 0-100。"""
return amount * (percent / 100)
# 使用示例
discount = calculate_discount(100.0, 10.0) # 优惠 10 美元
来自该仓库的核心洞察
“那些‘过度复杂’的例子并非显而易见的错误 — 它们遵循了设计模式和最佳实践。问题在于 时机：它们在需要之前增加了复杂性。” 好的代码应该简单地解决今天的问题，而不是过早地解决明天的问题。
原则 3：外科手术式的改动
“只动必须动的地方。只清理你自己留下的烂摊子。”
这一原则最直接地解决了 Karpathy 对 LLM 进行正交改动（无关改动）的挫败感。在编辑现有代码时：
- 不要“改进”相邻的代码、注释或格式
- 不要重构没有损坏的部分
- 即使你有不同的做法，也要匹配现有的风格
- 如果你发现了无关的死代码，请提及它 —— 不要直接删除
当你的改动产生了孤立项时：
- 删除那些由 你的改动 导致的不再使用的 imports/变量/函数
- 除非被要求，否则不要删除预先存在的死代码
测试标准： 每一行改动的代码都应该能直接追溯到用户的需求。
示例：“顺便重构”的陷阱
用户需求： “修复空电子邮件导致验证器崩溃的 bug”
修改了 15 行：
- 添加了 docstring（未要求）
- 添加了用户名校验（未要求）
- 修改了注释（未要求）
- “改进”了邮箱校验逻辑（未要求）
- 在各处添加了 .strip() 调用（未要求）
修改了 3 行：
- 为邮箱添加了空字符串保护
- 修改了变量引用以避免崩溃
- 未改动其他任何内容。
示例：风格偏移陷阱
用户请求： “为上传函数添加日志记录”
The LLM adds logging — but also changes single quotes to double quotes, adds type hints nobody asked for, adds a docstring, reformats whitespace, and restructures the boolean return logic. The correct approach: add 仅 日志相关行，并使用 现有风格 (single quotes, no type hints, same spacing).
原则 4：目标驱动执行
“定义成功标准。循环执行直至验证通过。”
这一原则捕捉到了 Karpathy 认为的在使用 LLM 时最具杠杆效应的见解：
Karpathy's 核心见解
“LLM 非常擅长不断迭代直到达成特定目标……不要告诉它该做什么，给它成功标准，然后看它发挥。”
这一原则将命令式任务转变为声明式目标：
| 与其…… | 不如转变为…… |
|---|---|
| “添加校验” | “为无效输入编写测试，然后让它们通过” |
| “修复 Bug” | “编写一个能复现该问题的测试，然后让它通过” |
| “重构 X” | “确保重构前后的测试都能通过” |
对于多步骤任务，模型应当陈述一个简要计划：
1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]
Strong success criteria let the LLM loop
独立地。模糊的标准（“让它能跑通”）
需要不断的澄清。
5. 实际的 CLAUDE.md 文件
这是完整、未经删减的 CLAUDE.md 仓库中的文件。它刻意保持简短 — 不到 70 行。这种简洁是一项特性，而非局限：
旨在减少常见 LLM 编码
错误的行为准则。请根据需要与项目特定的指令
合并。
权衡： 这些准则倾向于谨慎
而非速度。对于琐碎的任务，请自行判断。
## 1. 编码前先思考
不要臆断。不要隐藏困惑。明确权衡。
在实现之前：
- 明确说明你的假设。如果不确定，请询问。
- 如果存在多种解释，请一一列出。
- 如果存在更简单的方法，请说明。
- 如果有不清楚的地方，请停止。指出令人困惑之处。
## 2. 简单至上
用最少的代码解决问题。不要进行推测性编码。
- 不要提供超出要求的特性。
- 不要为仅使用一次的代码进行抽象。
- 不要提供未经要求的 “灵活性”。
- 不要为不可能发生的场景编写错误处理。
- 如果 200 行代码能精简到 50 行，那就重写它。
## 3. 精准修改
只触碰必须修改的部分。只清理你自己留下的烂摊子。
- 不要 “改进” 相邻的代码或格式。
- 不要重构没有问题的代码。
- 遵循现有风格，即使你会有不同的做法。
- 如果发现死代码，请指出 — 不要直接删除。
## 4. 目标驱动执行
定义成功标准。循环执行直到验证通过。
将任务转化为可验证的目标：
- “添加校验” → “编写测试，然后使其通过”
- “修复 Bug” → “在测试中复现它，然后修复”
- “重构 X” → “确保重构前后的测试都能通过”
就这些。这就是全部内容。它的力量在于简洁 — 足够短，可以放入 Agent 的上下文窗口而不挤占项目特定的指令；又足够长，可以编码关键的行为护栏。
6. 真实世界示例
该仓库包含一个 EXAMPLES.md 包含详细前后对比的文件。以下是该文件中的核心“反模式总结”：
| 原则 | 反模式 | 修复方案 |
|---|---|---|
| 编码前先思考 | 默认假设文件格式、字段和范围 | 明确列出假设，并请求澄清 |
| 简单至上 | 为单一的折扣计算使用策略模式 | 在真正需要复杂性之前，只使用一个函数 |
| 精准修改 | Reformats quotes, adds type hints while fixing a bug | 仅修改修复报告问题所需的行 |
| 目标驱动 | “我将审查并改进代码” | “为 Bug X 编写测试 → 使其通过 → 验证无回归” |
7. 如何安装
该仓库提供两种安装方法：
选项 A：Claude Code 插件（推荐）
这会将指南安装为 Claude Code 插件，使该技能可在 你的所有项目中可用:
/plugin marketplace add forrestchang/andrej-karpathy-skills
# 然后安装插件
/plugin install andrej-karpathy-skills@karpathy-skills
选项 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
自定义
这些指南旨在 与特定项目的指令合并。你可以根据项目需求添加自己的章节，例如 TypeScript 配置、API 标准、测试规范等。这四项原则构成了行为基础，而你的项目规则则在此之上构建。
8. 什么是 CLAUDE.md？
对于那些不熟悉该概念的人： CLAUDE.md 是一个 项目记忆卡 专为 AI 编程智能体设计。Claude Code 会在每次会话开始时自动读取它，提供跨对话的持久上下文。
可以将其视为面向新开发者的入职文档的 AI 版本 — 只是阅读者变成了 AI 就在每一次 它开始处理你的项目时。
CLAUDE.md 最佳实践 (2026)
| 章节 | 内容 |
|---|---|
| 项目概览 | 用 2-3 句话简述项目的功能 |
| 技术栈 | 语言、框架、核心库 |
| 架构 | 代码库地图（源码、组件、配置） |
| 命令 | dev, build, test, lint 命令 |
| 编码规范 | 命名约定、模式、风格规则 |
| 安全规则 | “切勿硬编码 API 密钥，” “不要修改 /config” |
层级结构
CLAUDE.md(项目根目录) — 共享上下文，已提交至 GitCLAUDE.local.md(项目根目录) — 个人开发专用笔记（需添加到 .gitignore）~/.claude/CLAUDE.md— 跨所有项目的全局偏好设置- 子目录
CLAUDE.md文件 — 仅在对应目录下工作时提取的上下文
经验法则： 如果你在对话中必须重复某条指令超过两次，请将其提升至你的 CLAUDE.md.
9. 社区反响
我们调研了以下平台的讨论： Reddit (r/ClaudeAI, r/ClaudeCode)、Twitter/X 以及技术博客。以下是社区的看法：
“自信的初级开发人员”共识
Reddit 社区经常将 Claude Code 描述为一个才华横溢但有时不太可靠的 “初级开发者。” 它速度快且知识渊博，但如果无人监督，就容易采取危险的捷径、产生幻觉或犯下幼稚的错误。Karpathy 的 skills 文件通过添加初级开发者所需的护栏直接解决了这个问题。
“技术水平问题”之争
Reddit 上流行的一种观点是：AI 生成代码的质量 与用户自身的工程判断力直接成正比 以及“上下文工程”能力。掌握了提示词结构、上下文管理和验证循环的高级用户报告的成功率显著更高。Karpathy 的 skills 文件是最受欢迎的“上下文工程”工具之一。
“AI 精神病”辩论
Karpathy 对“永久性 AI 精神病”的描述 — 一种持续处于高产但令人精疲力竭的 Agent 引导状态 — 引起了深度共鸣。有些人将 AI Agent 视为不容忽视的竞争优势。另一些人则称之为“生产力剧场” — 感觉很快，却产出了难以维护的代码。该 skills 文件介于两者之间：它承认 AI Agent 的强大，但认为它们需要 严格的约束。
人类瓶颈的转移
社区共识：AI 降低了 编写 代码的门槛。但真正的瓶颈已从实现转移到了 架构和评估。挑战不再是“我该怎么写这个？”而是“我是否足够了解 Agent 刚刚构建的内容，以便对其进行维护？”
10. 宏观图景
从“氛围编程”到“智能体工程”
当 Karpathy 在 2025 年初提出“氛围编程”时，它描述的是一种松散的、对话式的 AI 提示方式。到 2026 年，社区已将其演进为 “智能体工程” — 在这一准则中，开发者将 AI 视为合作伙伴，需要明确的目标、清晰的边界和严格的测试。
这个 andrej-karpathy-skills 仓库代表了这种演进。这并不是要限制 AI 的能力，而是关于 引导其发挥能力 通过能够产生更好结果的原则。
“想法文件”模式
这个仓库也体现了 Karpathy 所称的 “想法文件” 模式 — 分享想法而非具体实现。这个 CLAUDE.md 文件并不是任何人都可以导入的库。它是一套任何人都可以采用的原则。接收者的智能体会根据其特定需求进行定制。这是一种新型的开源：不是代码开源，而是 想法开源。
如何判断其是否奏效
根据仓库的 README，如果你看到以下情况，说明这些指南正在发挥作用：
- diff 中不必要的更改更少 — 仅出现请求的更改
- 因过度复杂化而导致的重写更少 — 代码在初次编写时就保持简洁
- 澄清问题应先于代码实现 — 而不是在出错之后
- 保持 PR 简洁且最小化 — 拒绝顺带的重构或所谓的“改进”
权衡说明
该仓库对权衡取舍直言不讳： “这些准则更倾向于谨慎，而非速度。” 对于琐碎任务（如简单的拼写修复、显而易见的一行代码修改），请自行斟酌 — 并非所有变更都需要如此严苛。其目标是减少非琐碎工作中的代价昂贵的错误，而非拖慢简单任务的进度。
11. 所有来源与链接
本文的研究基于 多渠道调研 涵盖 GitHub, Twitter/X, Reddit, 网络文章以及源代码本身。以下是所有主要来源：
主要来源
- GitHub: forrestchang/andrej-karpathy-skills — 仓库本身
- CLAUDE.md — 实际的指南文件
- EXAMPLES.md — 真实的修改前后对比示例
- Karpathy's 原始推文 — 识别 LLM 编程陷阱的热门文章
社区讨论
- Reddit r/ClaudeAI — 关于 Claude Code 工作流以及“自信的初级开发人员”共识的社区讨论
- Reddit r/ClaudeCode — 关于 CLAUDE.md 最佳实践和规范系统的讨论帖
- Twitter/X — 开发者反馈、工作流分享及采用报告
网络资源
- Medium — 技术评论与实现指南
- dev.to — 开发者社区教程
- Forbes — 关于从“vibe coding”向“agentic engineering”演进的报道
- VentureBeat — 分析 Karpathy 将上下文管理比作“编译器”的类比
- Analytics Vidhya — 对 skills 文件处理方式的技术分析
文档
- Claude Code 文档 — 官方 CLAUDE.md 参考指南
- HumanLayer.dev — CLAUDE.md 配置最佳实践
本站相关文章
Get the Ultimate Antigravity Cheat Sheet
Join 5,000+ developers and get our exclusive PDF guide to mastering Gemini 3 shortcuts and agent workflows.