CLAUDE.md：一个65行纯文本文件，凭什么拿下GitHub 8.2万星？

一个 65 行的 Markdown 文件，连续 3 天 GitHub Trending 日榜第一，一周新增 4.4 万星，总计超过 8.2 万——LinkedIn 上有人说已经到了 15 万+。

不是新框架，不是新语言。只是一个纯文本配置文件。

它解决的是一个你可能每天都在忍的问题：AI 编码助手每次会话都从零开始，而且总在犯同样的错。

一、Karpathy 的三条吐槽

2026 年 1 月 26 日，Andrej Karpathy——OpenAI 联合创始人、前 Tesla AI 负责人、"vibe coding"的提出者——在 X 上发了一条帖子。他不是在推荐什么工具，而是在吐槽 AI 编码助手的三个核心问题：

❶ 暗中假设 — 模型替你做决定，错了也不吭声。你说"加个导出"，它默认导出全部数据、选了 JSON+CSV、定了文件路径——全没问过你。

❷ 过度工程 — 你要一个简单功能，它给你一套企业级架构。要个折扣计算，它写了 DiscountStrategy 抽象类 + 五个子类，50 多行。一个 3 行函数就够。

❸ 附带伤害 — 改一个 bug，顺手重构了 25 处无关代码。你以为只是修个空指针，结果 diff 出来 400 行变更。

开发者 Forrest Chang（张嘉元，注意不是 Karpathy 本人）把这些观察提炼成了机器可读的行为规范，就是 CLAUDE.md。Karpathy 本人没有写这个文件。

二、四条核心原则

CLAUDE.md 只有 65 行，但每一条都是血泪教训。核心是四条原则：

CLAUDE.md 四条核心原则 原则一：先想再写 不确定的必须问，不能猜 多种理解时列出选项让用户选 有更简单方案时主动提出 困惑时停下来，说出哪里不懂 原则二：简约至上 不写没要求的功能 只用一次的代码不做抽象层 不加没人要求的"灵活性" 200行能缩成50行就重写 原则三：精确手术 不"顺手"改旁边的代码 不重构没坏的东西 匹配现有风格 每行改动必须追溯到需求 原则四：目标驱动 给验收标准，不给步骤 "加验证" → 写测试用例通过 "修bug" → 写能复现的测试 验收标准越清晰，你介入越少 来源：Andrej Karpathy LLM 编码观察，Forrest Chang 提炼

三、为什么能爆？

GitHub 上一周新增 4.4 万星。一个纯文本文件凭什么？

因为每个用过 AI 编码助手的人都踩过这些坑。

核心洞察：瓶颈不在模型，在模型周围的脚手架。  "A Markdown file hitting #1 on trending shows the bottleneck isn't the model — it's the scaffolding around it. This 'glue' IS the product." — Kraggich

本质上，CLAUDE.md 做的事情是把顶级工程师的隐性知识编码成 AI 能直接消费的格式。这个概念被称为 Agentic Engineering——把 AI 当作需要明确目标、清晰边界、严格验证的协作伙伴，而不是一个会写代码的搜索引擎。

四、我的踩坑记录

用 AI 编码助手做实际项目，每一条原则都能对应到一次翻车。

翻车一：暗中假设（违反原则一）

我在做一个 API 服务的配置模块，跟 AI 说"加个验证逻辑"。它直接选了 Joi 校验库、定了 schema 格式、写了 middleware——全程没问一句。跑起来才发现它选的校验库跟项目已有的 Zod 冲突，两套校验体系打架，光清理就花了一小时。

原则一的价值："不确定的必须问，不能猜。"如果它先问一句"项目已有校验库吗？用哪个？"，这一小时就省了。

翻车二：过度工程（违反原则二）

让 AI 给一个 Python 脚本加个简单的命令行参数解析。本来 argparse 十行搞定的事，它给了我一个完整的配置系统：BaseConfig 抽象类、YAMLConfigLoader、EnvConfigLoader、配置合并策略、环境变量覆盖——50 多行代码，三个新文件。

资深工程师看了会说"太复杂"。砍到最后，就是 argparse 十行。

原则二的价值："检验标准：资深工程师看了会说太复杂吗？如果会，砍。"

翻车三：附带伤害（违反原则三）

让 AI 修一个空指针异常。它确实修了——顺便把那个文件的 import 排序规则从按字母序改成了按长度排序，把三个函数的参数名从 snake_case 改成了 camelCase，还删了五条它认为"没用"的注释。diff 出来 200 多行变更，我花半小时 review 才确认核心修复只有两行。

原则三的价值："每行改动必须能追溯到用户需求。" 你修空指针，就只改空指针那一行。

翻车四：90 分钟死循环（违反原则四）

让 AI 给一个模块加单元测试。它开始写，发现有个依赖需要 mock，去写 mock，mock 的接口变了需要改实现，改了实现又发现测试过不了……循环往复。90 分钟后我回来一看，还在跑，代码比初始状态还乱。

这就是社区补充的"Token 预算"规则：单任务约 4000 tokens，单会话约 30000 tokens。到上限就停下来总结，重新开始。不是死磕。

原则四的价值：先定义验收标准（"写 5 个测试用例，全部通过"），然后循环到验证通过。不是循环到你觉得"差不多了"。

五、不是 Claude 专属

CLAUDE.md 是 Anthropic 的方案。但行业已经在走向统一标准——AGENTS.md，由 Linux 基金会旗下的 Agentic AI Foundation 管理。

目前支持 AGENTS.md 的工具有 60 多种：OpenAI Codex、Cursor、GitHub Copilot、Windsurf、Aider、Gemini CLI、Zed、Warp、Devin、JetBrains Junie……一个文件，所有工具通用。OpenAI 自己的 codex 仓库里就分散使用了 88 个 AGENTS.md 文件。

选择建议：如果团队只用 Claude Code，用 CLAUDE.md（功能更丰富：导入、路径限定、hooks）。如果团队用多种工具或维护开源项目，用 AGENTS.md（一个文件惠及所有贡献者）。最佳实践是两者兼顾。

六、三个最常见的坑

坑一：规则越多越好。 错。前沿 LLM 大约只能稳定遵循 150-200 条指令。一个 600 行的文件不等于 600 条指导——AI 会选择性忽略它认为无关的部分。大多数项目 300 行是上限。超过就提取到子文档，按需加载。

坑二：用指令规范代码格式。 错。Prettier、ESLint、Biome 能以零 Token 成本确定性执行格式规范。永远不要让 LLM 做 Linter 该做的事。CLAUDE.md 只写 LLM 无法从代码推断的决策。

坑三：写完就不动了。 错。CLAUDE.md 是动态文档，应该提交到 git，团队共同维护。AI 反复犯同一个错 → 加规则；规则没改变行为 → 文件太臃肿，规则被淹没了。与其增加规则细节，不如减少噪音。

七、两步上手

两步上手 CLAUDE.md 第一步：/init 自动分析代码库生成初稿 第二步：狠心删 删掉AI不被告知也能做对的 只留：是什么（技术栈）· 为什么（不明显的决策）· 怎么做（命令、工作流）

如果你用多种 AI 编码工具，把通用规则写进 AGENTS.md，再让 CLAUDE.md 导入它就行。

八、这不是魔法，这是记忆

CLAUDE.md / AGENTS.md 代表的不只是一个配置文件格式。它标志着 AI 编码工具从"你问我答"走向"你定规矩我执行"。

过去我们给新人写 onboarding 文档。现在我们给 AI 写 onboarding 文档。本质上一样——把团队隐含的知识显式化、结构化、可传递。

2026 年 Anthropic 的 Agentic Coding 趋势报告提到：成功团队的共同特征是把配置视为头等工程事项。精心编写的指令文件 + linting 钩子 + 测试要求的确定性强制执行——这是区分"AI 辅助但混乱"与"AI 辅助且高效"的关键。

不追求完美的规则，追求有效的规则。写下来，交给 git，团队一起维护。

这不是魔法。这是记忆。

认知层面：CLAUDE.md 不是给 AI 的"使用说明书"，而是团队的"隐性知识显式化"。瓶颈不在模型能力，在模型周围的脚手架。

能力层面：两步上手——/init 生成初稿，然后狠心删。只留"是什么、为什么、怎么做"。不超过 300 行。交给 git 管理，团队共同维护。用多种工具就写 AGENTS.md，一个文件通用 60+ 平台。

判断层面：规则越多不等于效果越好。LLM 稳定遵循的指令有上限（约 150-200 条）。发现 AI 反复犯错才加规则，发现规则无效就减少噪音而非增加细节。Token 预算：单任务 4000 tokens，到上限就停下来重新开始，别死循环。