Karpathy 的 CLAUDE.md 详解：技能搜索背后的一个文件

在 Google Trends 上，全球范围内，过去七天，截至 2026年10月23日查阅，“karpathy skills”作为“claude skills”种子下的上升查询出现。任何追踪该搜索的人都会落到同一个地方：github.com/multica-ai/andrej-karpathy-skills，一个在 GitHub 上显示有 222,612 个星标的仓库，查阅于 2026年10月23日。其描述中完全没有“skill”这个词。描述写道：“一个单独的 CLAUDE.md 文件，用于改善 Claude Code 的行为，源自 Andrej Karpathy 对 LLM 编码陷阱的观察。”

查询与对象之间的差距并不是一个小技术细节。一项技能和一个 CLAUDE.md 文件是执行不同工作的不同机制，而人们关于这个仓库的几乎每一种说法，要么依赖于知道它究竟是哪一个，要么悄悄预设了错误的那一个。其中的指导内容只是一个文件。围绕该文件的仓库还带有一个插件清单以及 skills 下的一个文件夹，搜索栏里的那个词很可能就来自这里。把封装与负载区分开来，是这里第一个有用的步骤。

这些数字全部来自 GitHub，读取于 2026 年 10 月 23 日：222,612 个星标，22,321 个复刻，创建于 2026 年 1 月 27 日，最后推送于 2026 年 4 月 20 日，MIT 许可证。最后那一对日期才是有意思的地方。{{1}}该仓库大约六个月没有收到任何推送，而星标数却仍在持续攀升。{{/1}}

文件负责实际工作；包装负责解释搜索词

打开这个仓库，文件列表就让这种不匹配一目了然。根目录下有 CLAUDE.md，旁边还有 CURSOR.md、EXAMPLES.md、一个以 Cursor 项目规则形式存放同样指南的 .cursor/rules 文件夹、一个 .claude-plugin 文件夹，以及一个 skills/karpathy-guidelines 目录。README 推荐的安装途径是插件市场，并且它把结果描述为让“该技能在你所有项目中都可用”。

所以，搜索词与其说是错的，不如说是不精确。有一个 skills 文件夹。有一个插件。真正没有的，是一组各自承担不同任务的独立技能——而这通常是人们所说的技能包（skill pack）的形态：一个文件夹，里面放着一个 SKILL.md 以及该能力所需的任何支持文件，并针对某一项任务被调用。在这里，全部指导内容就是一份常设指令文档，而插件的存在是为了把这份文档交付到项目中。

这个区别对你是否重要，取决于你想从这次搜索中得到什么。如果你要找的是一个工具箱，那它并不是。如果你想要的是一本简短的规则手册，用来改变编码智能体在整个项目中的行为方式，那它正好就是这样一本手册，而且值得去理解：为什么有人会把它写成一个文件，而不是写成一组技能。

它针对的投诉

README 中注明的来源是 Andrej Karpathy 在 X 上发布的一篇帖子，README 引用了该帖子中关于模型如何编写代码的三点抱怨。这些内容值得完整阅读，因为那四条原则几乎与它们一一对应。

首先：模型“替你做错误假设，然后不加核实就顺着这些假设一路做下去”，而且“不处理自己的困惑，不寻求澄清，不揭示不一致之处，不呈现权衡取舍，在该反驳时不反驳”。注意这里描述的是什么。这不是对错误答案的抱怨。这是对流畅但错误的答案被毫不犹豫地给出的抱怨：本应促成提问的不确定性，反而促成了自信满满的代码。

第二点：他们“特别喜欢把代码和 API 过度复杂化，膨胀抽象层，不清理死代码……明明 100 行就能搞定，却要写出一套 1000 多行的臃肿构造。”凡是提过一个功能需求、结果却收到一个框架的人，都会对这一点很熟悉。

第三种情况更隐蔽，而且对任何审阅 diff 的人来说代价最高：它们“仍然有时会作为副作用更改/删除自己并未充分理解的注释和代码，即使这些改动与任务无关”。单独看，对一条注释做无关改动影响很小。但在整个代码库中累积起来，就会让审查队列堆满没人要求的改动，也会让解释某个变通方案的注释在任何人弄清该变通方案为何存在之前就消失。

四项原则，以及每一项留下的考验

这份文件体现了四条原则。每条原则都附有一小组简短规则，其中两条还明确给出了一行式测试，无需安装任何东西即可将其应用到 diff 上。规则正是这份文件的特色所在。

先思考再编码

标题的指示是“不要假设。不要隐藏困惑。把权衡摆到明面上。”其下写明：明确陈述假设，拿不准就问而不要猜；当请求有歧义时，给出多种解释；当存在更简单的做法时，要提出反对；困惑时就停下，指出不清楚的地方，并请求澄清。这正针对第一条抱怨。其机制不是“更加小心”——而是把隐性的选择变成可见的选择，让评审者能在代码写出来之前而不是之后提出异议。

简洁优先

规则是：用最少的代码解决问题，不做任何投机性的东西：不添加超出要求的功能，不为一次性代码做抽象，不提供没人要求的灵活性或可配置性，不为不可能发生的场景写错误处理，并且"如果 200 行能写成 50 行，那就重写它"。检验标准只有一个问题——资深工程师会不会说这过于复杂了？——这是一个主观判断，而且坦率地说就是主观判断。

外科手术式更改

文件在这里把指令分成两部分，这是其中最有用的地方。编辑现有代码时：不要改进相邻的代码、注释或格式；不要重构没坏的东西；即使你会有不同做法，也要遵循现有风格；提及不相关的死代码，而不是删除它。当你自己的更改产生孤立项时：移除你的更改导致不再使用的导入、变量和函数，但除非被要求，否则不要动预先存在的死代码。检验标准是，每一行更改都能直接追溯到该请求。

目标驱动执行

定义成功标准，并循环直到验证通过。README 以成对形式展示这种转变。与其“添加验证”，不如为无效输入编写测试，然后让它们通过。与其“修复这个 bug”，不如编写一个能复现它的测试，然后让它通过。与其“重构 X”，不如确保重构前后测试都通过。对于多步骤工作，它要求给出一个简短计划，其中每一步都指明自己的验证方式。README 在这里再次引用 Karpathy 的话：“LLMs 非常擅长循环执行，直到达成特定目标……不要告诉它该做什么，给它成功标准，然后看它行动。”

文件、技能和插件是三件不同的事情

值得精确说明这套机制，因为实际行为有所不同。CLAUDE.md 是项目指令文件：Claude Code 会将其作为仓库的常驻上下文来读取，无论本轮是否有人要求它，它都存在。技能（skill）是一个包含 SKILL.md 的文件夹，其中描述该能力应在何时使用，仅在任务需要时加载，而不是在此之前。插件（plugin）是通过市场安装的分发包，可以携带技能、命令和其他组件。这些区别在于指令何时进入上下文以及由谁决定，而不在于质量。

从这个意义上说，CLAUDE.md 是三者中最粗放的。它在该项目中始终开启，适用于其中的每项任务，并且无论工作是修复一行拼写错误还是进行迁移，它都会在每一轮占用上下文。该文件自带的 README 在一个名为 Tradeoff Note 的章节中承认了这一代价：这些准则偏向谨慎而非速度，对于琐碎任务——简单的拼写错误修复、显而易见的一行代码——你应自行判断。它表示，目标是减少非平凡工作中代价高昂的错误，而不是拖慢简单工作。

这是对常驻指令文件能做什么的客观描述。它无法增加模型本来不具备的能力。它只能让模型现有行为发生的可能性变大或变小。这就是为什么该文件写成约束——不要做这个，做那个之前先询问——而不是写成鼓励它变得更好。

222,612 颗恒星衡量的是什么

它们衡量的是关注度。这不是贬低，也并非无足轻重：一个创建于2026年1月、最后推送于4月的代码仓库，截至2026年10月23日在GitHub上获得了222,612颗星和22,321次分叉，这是当天读取的数据，意味着它被广泛分享，并被那些想要拥有自己副本的人分叉。星标数量可以合理反映有多少人认为某样东西值得收藏。

它不是效果的替代指标，仓库也没有假装 otherwise。其中任何地方都没有发布：任何比较有该文件与没有该文件的结果的基准测试，任何衡量它是否有效的方法论，以及任何与对照组的比较。没有在真实代码库上的前后对比，没有评审者研究，没有事故率。这样的文件是一个关于模型行为的假设，表述得很优雅，而且没有人进行过试验。

README 转而提供的，是一个名为“如何知道它正在起作用”的章节，其中列出了你可能会观察到的四件事：差异中不必要的变化更少；因过度复杂化而进行的重写更少；澄清性问题在实现之前而非在犯错之后提出；以及干净、极简的拉取请求。这些是合理的信号。它们也恰恰是你在没有进行任何测量的情况下会写出来的内容，而且它们是由任何应用该文件的人自我报告的。请把它们当作在你自己的仓库中用来要求该文件达到的检查清单，而不是当作它已经通过的证据。

安装它时你实际输入的内容

README 给出了两条路径。推荐路径在 Claude Code 中运行：先添加市场，再安装插件，之后这些准则会在各项目间生效，而不是按仓库分别生效。第二条是按项目进行：将原始 CLAUDE.md 获取到新仓库中，或将其追加到现有仓库中。此外还有一个已提交的 Cursor 项目规则，因此当该文件夹在 Cursor 中打开时，同样的准则也会适用——这个细节说明该文件被编写为可跨工具移植，适用于读取项目级指令文件的工具，而不是绑定到某个厂商的加载器。

有一个粗糙之处值得指出，因为如果你完全按照 README 操作，就会碰到它。市场命令名是 forrestchang/andrej-karpathy-skills，而页面顶部的仓库 URL 是 multica-ai/andrej-karpathy-skills。这两个字符串都出现在同一份 README 中，读取于 2026 年 10 月 23 日。我能看出这种不匹配，但无法告诉你它为什么存在，所以诚实的建议是：如果其中一个路径失败，就试试另一个，并把这两个字符串中的一个视为过时。

首页上另一点值得注意的是：该仓库由 multica-ai 维护，而 README 开头的引用块宣传了 Multica，称其为“一个用于运行和管理编码智能体、并具备可复用技能的开源平台”。这是一种正当的披露，也为打包方式为何呈现成现在这样提供了线索。一个关注可复用技能的项目，很可能会把自己的指导内容作为可安装的东西发布，而这个插件正是如此。

使用它，但不承袭它的假设

“自定义”部分是大多数读者会跳过的地方。该文件的设计初衷是与项目特定的指令合并使用，而不是取代它们，并且它给出的示例都很具体：使用 TypeScript 严格模式、所有 API 端点都必须有测试、遵循某个特定文件中现有的错误处理模式。这不是装饰性的内容。这正是通用规则手册与一套知道你代码在哪里的指令集之间的区别。

合并而非叠加是有实际理由的。如果你原样粘贴该文件，而你的项目又有自己的约定，那么两套指令就可能相互冲突；而模型在调和这种分歧时所产生的，恰恰是第一条原则试图消除的那种混乱。将你的约定以同一种语气写入同一个文件，可以使指令面保持足够小，便于审查。

你确实应该审计它。这是一份简短的行为指令文档，将适用于仓库中的每一个请求。正确的问题不是 222,612 个人是否可能都错了——这种说法说明不了任何问题——而是每条规则是否对得上你实际见过的一次失败。如果你的 diff 中从未包含顺手改写注释的情况，那么“外科手术式变更”一节只会白白消耗你的上下文。删掉它。该文件采用 MIT 许可证，本就是供人编辑的。

再往下一层，这些都不会改变由哪个模型来回答。CLAUDE.md 文件影响的是请求到达模型后如何处理；它并不说明由哪个模型接收请求。第二个决定取决于位于模型前面的那一层。一种安排方式是使用一个 OpenAI 兼容的单一端点，在一个密钥下承载 200 多个模型，支持跨提供商自动故障转移，并以 0% 加价透传提供商的标价。我们托管模型；我们不开发 Claude Code，而且你的代码仓库中的任何内容对我们都不可见。

搜索会一直说“skills”，因为人们就是用这个词来指代那种你安装后能让智能体表现不同的东西，而这个仓库外围的包装也用了这个词。产物是一个文件：一份常设指令文档，针对三类具体抱怨写成，包含四项原则和一组你可以手动应用的测试。判断它时，要看那些抱怨听起来是否像你的仓库。这比星标数是个更好的问题，星标数从来只衡量了多少人和你刚才有同样的反应。