Claude Code 必装的 CLAUDE.md？我用 10 个真实工单测试了 Karpathy Skills

先说结果。为了验证 Karpathy Skills（社区整理的 CLAUDE.md 行为准则）是否真的有用，我挑了 10 个真实工单，固定 Claude Opus 4.8，唯一变量是是否启用 Karpathy 四条原则。一周下来，最让我记住的数字是：

也有失望的时候——改一个常量的工单，准则几乎没帮上忙，还多了一轮「确认假设」的啰嗦。下文会把成功与失败都写清楚，并附上我仓库里正在用的 CLAUDE.md 最终版本（Claude Code Rules / Prompt 长尾词会搜到这类内容）。

Claude Code 为什么总乱改代码？

不是模型「笨」，而是默认优化目标和工程师不一致：它倾向于尽快产出「看起来完整」的补丁——多写抽象、多改邻文件、少问歧义。Andrej Karpathy 在 X 上归纳过四类慢性病灶：没问清楚就动手、简单需求过度工程、顺手改不该改的文件、用「搞定它」代替可验证目标。

2026 年春天，社区把这套观察压进一个几十行的 CLAUDE.md（forrestchang/andrej-karpathy-skills，亦称 Karpathy Skills）。没有新运行时，只有四条行为合同——Claude Code 每次开会话都会读。我关心的是：I tested it — 数字到底多少。

Karpathy Skills 是什么？

名字里带 Skills，但产物形态是项目级指令文件，不是 OpenAI GPT、也不是 OpenHuman 的 SKILL.md 插件包。Claude Code 启动会话时会读取仓库根目录的 CLAUDE.md（以及全局插件注入的等价文本），在你敲第一行需求之前就约束 Agent 怎么思考、怎么改 diff。

四条原则与官方 CLAUDE.md 原文一一对应（见 仓库 CLAUDE.md）：

• Think Before Coding：先陈述假设、暴露歧义、提出更简单方案，而不是静默选一种理解开写。
• Simplicity First：只写解决问题所需的最小代码；拒绝未被要求的抽象、配置项与「将来可能用到」的层。
• Surgical Changes：只动任务相关行；不顺手「整理」邻域代码；自己引入的死代码要清，历史遗留的只提示不删。
• Goal-Driven Execution：把「修 bug / 加校验」改写成可验证目标（先写失败测试再绿），多步任务列出每步的 verify 检查点。

安装方式二选一：Claude Code 插件 /plugin install andrej-karpathy-skills@karpathy-skills，或把上游 CLAUDE.md 合并进你仓库根目录——下文「我的 CLAUDE.md 最终版本」可直接复制。

我的测试方法

为了验证这套规则是否真的有用，我按下面方式控制变量（测试运行于 Mac mini M4 Cloud Mac，只为保证 tmux 长跑与 xcodebuild 不断线；结论与是否在云端无关，你在本机 Mac 上同样可以复现）：

• 10 个真实工单：Swift 小功能 4、跨文件重命名 2、补测试 2、CI 脚本 2。
• 固定模型：claude-opus-4-8，Effort high，同一周内不升级小版本。
• 唯一变量：对照组用旧 CLAUDE.md（无 Karpathy 段）；实验组合并四条原则 + 下文两条团队规则。
• 每个工单跑两次（先 A 后 B 或隔天交替），避免「同一天状态好」偏差。

记录五类指标，对齐评审里真正费时间的部分：

10 个工单测试结果

下表为中位数（n=10，非官方基准）。若你只记一个数：无关 diff −78%。

展开无关 diff：18% → 4%，即 Agent 仍改了很多文件，但「Payment 模块被顺手格式化」这类路径从 diff 里消失了——Surgical Changes 直接对应这条曲线。首次 CI 绿 5/10 → 8/10 则主要来自 Goal-Driven Execution：Agent 更常先补失败测试再改实现。

哪些场景提升最大？

• 跨文件重命名 / 改签名：无关 diff −78% 体感最明显，CR 不再像「扫雷」。
• 需求略含糊的小功能：Think Before Coding 逼 Agent 先列假设，返工从 3 次降到 1 次（工单 PAY-1842、AUTH-901）。
• 补测试 + 改实现：一次绿率上升，Goal-Driven 的「先红后绿」被写进 CLAUDE.md 后执行更稳定。

与 代码知识图谱 正交：图谱答「改哪里」，CLAUDE.md 答「别乱改」。

哪些场景几乎没提升？（含失败案例）

一个让我失望的任务：改一个常量。 工单 CFG-77：把 maxRetryCount 从 3 改为 5，路径已写明。启用 Karpathy 后，Agent 仍多了一轮：「是否也要改退避策略与单元测试默认值？」——澄清步骤 +1，diff 质量与无准则时一样干净，总耗时反而多 4 分钟。这类规格极清的单点修改，四条里的 caution 偏「过度认真」，几乎 0 收益。

其它几乎无效的情况：

• 团队 CLAUDE.md 已很长且与 Karpathy 重复——边际收益递减。
• 没有测试 / xcodebuild——Goal-Driven 无法闭环，Agent 仍会「看起来做完」。
• 只在聊天里问问题、不写仓库——CLAUDE.md 根本不加载。

我的 CLAUDE.md 最终版本（可直接复制）

Claude Code 用户搜 CLAUDE.md、Claude Code Rules、Claude Code Prompt，最终要的是能粘贴进仓库的成品。下面是我合并 Karpathy 四条 + 两条 iOS 团队规则后的版本（英文正文与上游一致，便于模型遵循；中文说明见注释）：

# CLAUDE.md — Karpathy rules + Vuncloud iOS team

## Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: state assumptions; if unclear, ask; if a simpler approach exists, say so.

## Simplicity First
Minimum code that solves the problem. Nothing speculative.
No extra abstractions, config, or error handling for impossible cases.

## Surgical Changes
Touch only what you must. Don't "improve" adjacent code or formatting.
Match existing style. Mention unrelated dead code; don't delete unless asked.

## Goal-Driven Execution
Transform tasks into verifiable goals (tests first when applicable).
Multi-step: list plan with verify check per step.

## Vuncloud: Build Verification (custom)
After code changes to Swift/ObjC targets, run before claiming done:
  xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'
Report exit code. If tests fail, fix or stop — do not claim success.

## Vuncloud: Path Allowlist (custom)
Unless the user explicitly expands scope, only edit paths they named
or standard paired test paths (e.g. Sources/Foo/ ↔ Tests/Foo/).

安装上游原文可执行：

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

# 或 per-project：
curl -fsSL -o /tmp/karpathy-claude.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 勿覆盖已有 CLAUDE.md，合并段落即可

Cursor 用户：同步 .cursor/rules/karpathy-guidelines.mdc，与 Claude Code 保持同一语义。测 Karpathy 时务必固定 claude-opus-4-8，别与模型升级搅在一起——见 Opus 4.8 长跑指南。

Cloud Mac 长跑方案（Claude Code → tmux → Mac mini）

这篇比 OpenHuman 更适合谈 Cloud Mac，因为链条天然闭合：Claude Code 长会话 → tmux 防断线 → 同机 xcodebuild → 独享 Mac mini。对照实验、夜间 Agent、跨时区 CR 都怕笔记本睡眠；我在试点里用 Cloud Mac 只为环境稳定，数字本身在你本机复现即可。

• tmux + Claude Code：SSH 断开不杀会话（Opus 4.8 文内有示例）。
• 持久卷上的 CLAUDE.md：准则与 monorepo 绑定，不丢配置。
• Goal-Driven 硬验收：把上节 Build Verification 写进 CLAUDE.md，Agent 改完必须跑 Scheme。
• 与 Mac 云端 CI 同机，改完即验。

对照实验脚本片段

TASK_ID="PAY-1842"
git diff --stat main...HEAD > "/tmp/${TASK_ID}-stat.txt"
git diff --name-only main...HEAD | wc -l | awk '{print "files_changed=" $1}'
# 无关路径：人工或用 allowlist 对比
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16' \
  | tee "/tmp/${TASK_ID}-xcodebuild.log"
echo "exit=$?" >> "/tmp/${TASK_ID}-xcodebuild.log"

在 Claude Code 里下达任务时，尽量用目标句式喂给第四条准则，例如：

目标：为 CheckoutViewModel.validateAmount 增加非正数校验。
验证：1) 新增单元测试覆盖 0、负数、NaN；2) xcodebuild test -scheme YourApp 通过；
范围：仅允许修改 Sources/Checkout/ 与对应 Tests/，不要动 UI 主题与其它模块。

常见问题 (FAQ)

这是 Karpathy 官方写的吗？ 准则源自他在 X 上对 LLM 写代码的观察；CLAUDE.md 由社区整理（Forrest Chang 等维护）。Karpathy 转发过相关仓库，请以仓库 README 为准。

和 Claude Code 自带 memory / 项目说明冲突吗？ 应合并而非覆盖。把四条原则放在 CLAUDE.md 前部，后面接你们团队的命名、分支、测试命令。

能否替代 Code Review？ 不能。准则降低噪声 diff 概率；合并门禁、人工 CR、安全扫描仍必需。

Cursor 用户怎么办？ 复制 .cursor/rules/ 版本即可；与 Claude Code 共用同一 git 仓库时，保持两份准则语义一致。

百分比结论能引用吗？ 请引用你自己的对照实验。本文表格仅为 Vuncloud 团队试点示例，样本 n=10，未做严格双盲。

结论

我测了 Karpathy Skills，不是泛泛谈「有没有用」。 10 个工单、固定 Opus 4.8：无关 diff 少 78%，首次 CI 绿 +30 个百分点；改常量则几乎没帮助。真正值钱的是一份写进仓库的 CLAUDE.md——四条 Karpathy 原则 + 你自己的构建与路径规则。Claude Code 长跑若要 7×24，Mac mini Cloud Mac + tmux 比 OpenHuman 卖 Mac 自然得多：Agent、终端、Xcode 本来就该在同一台 macOS 上。