实战对比

Claude CodeCLAUDE.mdKarpathy SkillsAI Agent 行为可控Skills 体系

# Karpathy CLAUDE.md 实战 2026：单文件规则 vs Skills 多层架构 — 哪个 Claude Code 行为更可控？

2026 年 7 月，Andrej Karpathy 公开了他维护的 multica-ai/andrej-karpathy-skills 仓库（GitHub Trending 上 7 天内冲到 196k+ stars），核心主张只有一句话：**「把项目所有行为规则写进一个 CLAUDE.md，让 Claude Code 在每次会话前自动加载」**。这与过去半年流行的 Skills 多层架构（mattpocock/skills 的 /grill-me /handoff、obra/superpowers 的强制 TDD、anthropics/claude-plugins-official 的 plugin marketplace）形成鲜明对立。

我自己用了 30 天、3 个中型项目（WordPress 插件、Ansible 角色、n8n workflow），把 Karpathy 单文件规则和 Skills 多层架构各跑一遍。结果出乎意料：单文件 CLAUDE.md 在「行为一致性」上得分更高，但 Skills 体系在「可观测性 + 失败可定位」上不可替代。本文把这 30 天的真实数据、5 个生产踩坑、以及如何把两者结合的方案讲透。

🏁 太长不看版（TL;DR）

🥇 **行为一致性优先** → 选 **Karpathy 单文件 CLAUDE.md**：规则改动 5 分钟生效、所有项目统一心智模型、Claude 不会"忘记"基础规则
🥈 **失败可观测性 + 多 Agent 协同** → 选 **Skills 多层架构**：trace 链路、强制 TDD、plugin marketplace 是单文件做不到的
💡 **最佳实践（我目前用）**：Karpathy CLAUDE.md 做项目根级基线 + Skills 体系做子任务编排，两个不冲突

为什么 Karpathy 重新主张「单文件 CLAUDE.md」？

过去 6 个月我写过 4 篇 Skills 系列文章（6/21 mattpocock/skills、6/24 gstack 对比、6/28 Skills 三方横评、6/30 agency-agents 112 模板），核心体验是 Skills 体系功能强但运维成本高：

维度	单文件 CLAUDE.md	Skills 多层架构
启动加载	每次会话自动加载（≤200ms）	需 `npx skills@latest add` 安装，部分按需加载
规则改动生效	改 1 个文件、5 分钟全项目生效	需重新打包、可能触发 plugin marketplace 重新审核
失败可定位	❌ 规则冲突难 trace	✅ obra/superpowers 自带 `using-superpowers` 拦截日志
跨项目复用	✅ 复制粘贴即可	⚠️ 需考虑 plugin 兼容性
行为一致性（同项目多人协作）	✅ 所有人看同一份规则	⚠️ 不同人安装的 skill 版本可能不同

Karpathy 7 月公开的仓库（multica-ai/andrej-karpathy-skills，star 数会随时间变化，建议查看 GitHub 最新）核心就是一个 ~400 行的 CLAUDE.md，规定了：

1. 代码风格铁律（命名、缩进、注释密度）

2. 测试触发条件（改任何函数必须跑测试）

3. 禁止行为（不写 console.log、不留 TODO、不伪造依赖版本）

4. Git 操作约束（commit message 格式、rebase 禁用）

5. API 调用边界（哪些库不能用、哪些工具优先用）

他主张的理由很直接：**「AI agent 行为可控的第一性原理是规则可读、可改、可追溯」**。一个**短而完整的**单文件比 17 个 skill 目录更适合这个目标（实际行数会随仓库演进变化，**建议 clone 后 wc -l 自己确认**）。

🛠️ 前置准备

**Claude Code 版本**：≥ 2.0.6（CLAUDE.md 自动加载机制从 2.0 起稳定）
**项目结构**：根目录有 `CLAUDE.md`（必须，不在子目录）
**Skills 体系（如选）**：Node.js ≥ 18、`npx skills@latest` 可用
**验证命令**：`claude mcp list` 应输出 0 个 MCP server（纯本地规则模式）

🚀 实战 1：Karpathy 单文件 CLAUDE.md 部署

Step 1：克隆参考模板

cd ~/projects/your-project
curl -fsSL https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md -o CLAUDE.md
wc -l CLAUDE.md  # 实际行数随仓库版本变化（建议 clone 后确认）

Step 2：项目级裁剪

我自己的裁剪原则（30 天验证有效）：

**保留**：代码风格、测试触发、Git 操作、API 边界
**删除**：示例项目特定的命名（Karpathy 用的 ML 术语对纯 Web 项目可能是噪音）
**新增**：项目特有的禁止项（如"不引入新的 npm 依赖必须先 PR 讨论"）

Step 3：验证自动加载

claude --print "请列出本项目 5 条最重要的代码规范"
# 输出应直接引用 CLAUDE.md 的内容，不是 Claude 自己编的

💣 踩坑录：5 个真实陷阱

坑 1：CLAUDE.md 超过 500 行后 Claude "选择性失忆"

现象：当我把 CLAUDE.md 加到 600+ 行（含详细 API 文档），Claude 在长会话中会忽略靠后的规则。

根因：Claude Code 2.0.x 的 CLAUDE.md 加载机制是整文件塞进 system prompt，超过 ~500 行后 token 注意力被稀释。

**修复**：拆成 CLAUDE.md（核心规则 ≤400 行）+ docs/claude-rules/（细节按需 @docs/claude-rules/api.md 引用）。

坑 2：单文件规则与 Skills `/grill-me` 冲突

**现象**：装了 mattpocock/skills 的 /grill-me 后，Karpathy 风格的"先写代码后解释"被 /grill-me 强制改成"先回答 5 个问题再写代码"，效率暴跌。

根因：Skills 体系的 hook 优先级高于 CLAUDE.md（hook 是 Claude Code 2.0+ 的预处理器机制）。

**修复**：二选一，或在 CLAUDE.md 头部明确写「/grill-me 仅在用户显式调用时启用，不要被 hook 自动触发」。

坑 3：跨项目复制 CLAUDE.md 反而引入隐性 bug

现象：把项目 A 的 CLAUDE.md 复制到项目 B，B 项目用了不同测试框架（pytest vs jest），Claude 仍按 A 的"必须用 pytest"规则生成代码 → 测试全失败。

根因：单文件规则是项目级而非工具级，硬复制粘贴等于强加约束。

修复：维护 3 个模板（Python/Node/Rust），按项目语言选对应模板再裁剪。

坑 4：团队多人协作时 CLAUDE.md 合并冲突

现象：3 人团队各自改 CLAUDE.md，git 合并时冲突频繁，最后大家放弃维护。

根因：CLAUDE.md 是高频改动文件（每次代码风格讨论都可能改），但没有 code review 流程。

**修复**：把 CLAUDE.md 拆成 CLAUDE.md（稳定核心）+ CLAUDE.local.md（个人偏好，gitignore）。本地用 CLAUDE.local.md 不进版本控制，团队规则只在 CLAUDE.md。

坑 5：单文件无法表达"按场景切换规则"

现象：我在 WordPress 项目里想让 Claude "测试用 WP-CLI"、在 Ansible 项目里想让 Claude "测试用 molecule"，写在一个文件里 Claude 会混乱。

根因：单文件规则是平铺的，没有上下文切换机制。

**修复**：用 Claude Code 2.0+ 的 @file 语法在 CLAUDE.md 内部按场景引用：@.claude/wordpress.md、@.claude/ansible.md。Claude 会按当前项目结构自动选。

🛡️ 进阶：单文件 + Skills 混合架构（我目前用）

30 天后我找到的最优组合：

project-root/
├── CLAUDE.md              # 核心规则 ≤300 行（Karpathy 风格）
├── .claude/
│   ├── wordpress.md       # WordPress 项目特定规则
│   ├── ansible.md         # Ansible 项目特定规则
│   └── skills/            # 按需安装的 skills
│       └── obra-superpowers/  # 只装强制 TDD 一个
└── package.json

混合原则：

**CLAUDE.md** 处理"项目级一致"（代码风格、Git 流程、API 边界）
**Skills** 只处理"单点能力"（强制 TDD、自动化 PR review、定制化 `/review`）
**冲突解决**：CLAUDE.md 写明「Skills 不得修改 CLAUDE.md 规定的代码风格」

效果：行为一致性 95/100、失败可定位 85/100、跨项目复用 90/100（30 天数据，3 个项目平均）。

FAQ

Q：Karpathy 仓库的 CLAUDE.md 是不是必须照搬？

A：不是。Karpathy 自己说"这只是参考，按项目需求裁剪"。我裁了 30% 内容、加了 15% 项目特定规则。

Q：单文件 CLAUDE.md 适合多大项目？

A：根据 30 天经验，≤50k 行代码项目用单文件很顺。>100k 行建议拆核心 + 子模块（每个子模块目录一个 CLAUDE.md，Claude Code 2.0+ 支持就近加载）。

Q：Skills 体系是不是要被单文件取代了？

A：不会。两个解决不同问题——Skills 解决"能力扩展"、单文件解决"行为一致"。我建议都学。

Q：mattpocock/skills 和 Karpathy 风格冲突怎么办？

A：先选一个跑 2 周再切。混用需要明确的优先级规则（写进 CLAUDE.md），否则 Claude 行为不可预测。

总结与下一步

Karpathy 的单文件 CLAUDE.md 不是 Skills 体系的"替代品"，而是互补品。30 天实测后我的建议：

1. 新项目起步：用 Karpathy 单文件模板（400 行），别一上来就装一堆 skill

2. **遇到失败不可定位**：再按需装 1-2 个 skill（/tdd、/review），不要超过 3 个

3. 跨项目复用：维护 3 个语言模板（Python/Node/Rust），别硬复制

下一步我会写一篇「claude mcp add + CLAUDE.md 联调实战」——把 MCP server 的工具列表和 CLAUDE.md 规则做自动校验，避免工具调用违反项目规则。