CLAUDE.md 规则从 Karpathy 的 4 条增加到 12 条¶

Ch09.036 CLAUDE.md 规则从 Karpathy 的 4 条增加到 12 条¶

📊 Level ⭐⭐ | 13.4KB | entities/claude-md-12-rules-mnilax.md

评分¶

维度	分数
知识价值	9
置信度	8
推荐入库	是

核心标签¶

claude claude-code claude-md prompt-engineering coding-agent

摘要¶

Mnilax 在 Karpathy 原版 4 条 CLAUDE.md 规则基础上，通过 6 周在 30 个代码库上持续测试，补齐了 8 条新规则。错误率从 41% 降至 3%，且合规执行开销几乎不变（78% → 76%）。

关键洞察¶

实测数据说话：规则扩展到 12 条，合规率仅下降 2%（78%→76%），但错误率再降 8pp——新旧规则形成互补增强，而非争夺注意力预算
12 条规则分类：
决策边界（规则 5：模型只做判断不做决策）
资源约束（规则 6：Token 预算）
冲突处理（规则 7：显式暴露冲突不折中）
代码理解（规则 8：先读后写）
测试有效性（规则 9：测试验证意图不止行为）
长任务保障（规则 10：检查点强制）
规范遵从（规则 11：约定胜于新奇）
失败透明（规则 12：显性失败不静默）
200 行天花板：超过 200 行 Claude 只做模式匹配"规则存在"，不再真正读规则
身份提示无效：让 Claude 做"高级工程师"的指令没用——差距在"想"和"做"之间，祈使句规则才能闭合差距
翻车驱动规则：每条规则都对应一个真实翻车场景，CLAUDE.md 是行为合约而非许愿清单

技术细节¶

原版 4 条：先思后写 / 简单至上 / 外科手术式修改 / 目标驱动
新增 8 条：判断vs决策 / Token预算 / 冲突显式化 / 先读后写 / 测试验证意图 / 检查点 / 规范优先 / 显性失败
删除的尝试：身份提示、"小心/多想"等不可测试指令、放例子（三个例子≈10条规则）、超12条（18条时合规率跌至52%）
Token预算建议：单任务4K / 单会话30K，接近上限时摘要重置
实测配置：30个代码库、50个标准任务、6周持续测试
原文：https://x.com/Mnilax/status/2053116311132155938

深度分析¶

方法论价值：从经验到可复现的工程实践¶

Mnilax 的研究方法论值得重视。他没有在 X/Twitter 上人云亦云地转发 Karpathy 的 4 条规则，而是花了 6 周、30 个代码库、50 个标准任务 做系统性测试。这种 failure-driven 的迭代方式——"每条规则都对应一个真实翻车场景"——将 prompt engineering 从玄学推向实验科学。关键数字：12 条时合规率 76%，18 条时跌至 52%。这验证了 Karpathy 200 行天花板的判断，但同时也说明 上限不是 200 行，而是规则密度的临界点——超过这个密度，信号被噪音淹没。

规则互补性：新旧规则争夺注意力预算？¶

一个反直觉的发现：规则从 4 条扩展到 12 条，合规执行开销仅下降 2%（78%→76%），但错误率再降 8pp。Mnilax 的解释是"互补增强"——新旧规则覆盖的是不同 failure mode，而非同一注意力的拆分。这对 prompt engineering 社区是一个重要提醒：不是规则越多越贵，而是要确保每条规则的failure coverage 正交。

规则 1-4 的内在局限¶

Karpathy 的 4 条规则是为"编码瞬间"（coding moment）设计的，在以下场景存在系统性空白：

长任务 Agent：缺乏 Budget/Checkpoint/Fail-loud 机制，多步执行中极易产生语义漂移（semantic drift）
多代码库冲突：在 Monorepo 中面临多种风格博弈时，缺乏优先级逻辑，只能输出平庸的"平均值"风格
测试质量：Goal-driven 隐含"测试通过 = 任务成功"，导致大量逻辑空洞的测试用例通过但无技术覆盖价值
生产 vs 原型：简约至上的约束在原型探索阶段反而成为迭代枷锁

值得商榷的结论¶

"身份提示无效"——原文说"让 Claude 做'高级工程师'没用"，但这一结论在不同模型上可能不成立。Claude Sonnet 4 在身份提示上的响应模式与早期 GPT-4 存在差异。更严谨的表述应该是：在当前 Claude Code 场景下，祈使句规则的闭合差距效果优于身份提示，而非身份提示本身无效。

翻车场景的分类学价值¶

Mnilax 最具方法论创新的一点是将"翻车场景"作为规则设计的原子单位。12 条规则中的每一条都可以还原到一个具体的、可以向他人描述的失败事件。这种 failure-driven 的设计哲学有以下几个层次的价值： 第一层：可验证性。一条规则如果能被一个真实翻车场景所定义，那它就是可测试的。"先读后写"可以防止"在已有同功能函数旁新建函数"的失败；"显式失败"可以防止"迁移完成但静默跳过 14% 记录"的失败。每条规则的有效性都可以通过复现那个失败来验证。 第二层：正交性检验。当提出一条新规则前，先问：这条规则覆盖的 failure mode 是否已被现有规则覆盖？如果是，这条新规则是冗余的。如果否，才有必要加入。这个简单的过滤机制解释了为什么最终规则集合能保持在 12 条而不是膨胀到 18 条。 第三层：优先级排序。不是所有 failure mode 发生概率都相同。在自己的代码库里，最高频的 failure mode 应该排在最前面。Karpathy 的 4 条之所以是地基，是因为它们覆盖的是最高频的失败——隐蔽假设、过度复杂化、波及非目标代码。

Token 预算作为语义漂移的熔断机制¶

规则 6（Token 预算）是 12 条规则中最具系统思维的一条。Mnilax 的 90 分钟调试会话案例——模型反复建议早已否决的方案——揭示了一个根本性问题：LLM 的上下文窗口虽然能容纳大量信息，但模型对"已尝试路径"的记忆并不均匀。越早的决策上下文在模型的注意力分布中越被稀释。 Token 预算的本质不是节省成本，而是一个语义漂移（Semantic Drift）的熔断机制。当对话长度接近预算上限时，强制摘要重置的目标是：清除那些在模型注意力中已被稀释但仍在影响生成的"幽灵上下文"。这个机制与 Harness Engineering 中的"状态检查点"概念高度一致——都是在长程任务中防止错误累积的系统性手段。

12 条规则的注意力经济学¶

从 4 条扩展到 12 条，合规执行开销仅下降 2%（78%→76%）——这个数字背后有深层的注意力经济学含义。 Mnilax 的测试证明，当规则覆盖的是正交的 failure mode 时，Claude 对每条规则的遵循概率是相对独立的。一条规则的存在不会线性地消耗其他规则的注意力预算。但当规则总数超过临界点（~12 条或 ~200 行）后，Claude 的遵循率急剧下降（18 条时跌至 52%），说明此时规则之间开始竞争同一份注意力资源，信号被噪音淹没。这个临界点的存在有几个实践含义：①规则集合需要定期"修剪"，删除从未触发过的规则；②规则的表述应尽量简洁，避免用长段落包装简单指令；③规则的顺序也很重要——Claude 对前几条规则的注意力最强。

规则 5 的核心地位：判断与决策的边界¶

在 12 条规则中，规则 5（模型只做判断，不做决策）是最具架构意义的一条，因为它定义了 Claude Code 在系统中的角色边界。在传统的 AI 助手交互模式中，Claude 被视为一个可以处理各类任务的通用智能体。但规则 5 揭示了一个更精确的模型：Claude 适合处理的是"判断"任务（分类、摘要、提取），不适合处理"决策"任务（路由、重试、状态转换）。前者需要的是认知加工，后者需要的是确定性。这个边界的深层原因在于：判断任务的输出是语义空间中的一个点，容错空间大；决策任务的输出是系统状态的一次实际变更，错误代价是累积的、不可逆的。Claude Code 的可靠集成需要将决策层留给确定性代码，Claude 只负责决策前的语义分析。

实践启示¶

CLAUDE.md 写作原则¶

Failure-driven 而非 template-driven：不要从规则模板出发，而要从自己观察到的真实失败出发。先有"踩过这个坑"，再有"这条规则"。6 条针对真实踩过的坑的规则 > 12 条泛化的好建议
200 行天花板是真实约束：实测 18 条（超过 200 行）合规率跌至 52%。控制规则数量，优先覆盖最高频的 failure mode
祈使句优于身份提示：用"这条规则禁止做什么"而不是"像一个高级工程师一样写代码"。具体、可测试的指令比抽象身份更有效
避免依赖不一定存在的工具：用"匹配代码库强制执行的风格"替代"始终用 eslint"。规则应在工具缺失时静默失效改为明确声明
测试要验证意图而非行为：expect(getUserName()).toBe('John') 形同虚设——业务逻辑变更时测试不报错说明函数设计本身就有问题

团队采纳路径¶

|| 阶段 | 动作 | 目标 | |------|------|------| | 起点 | 直接采用 Karpathy 4 条规则作为地基 | 覆盖 ~40% 失败模式 | | 渐进补齐 | 每次踩坑后评估：这是新 failure mode 吗？现有规则能覆盖吗？ | 避免规则膨胀 | | 定期复盘 | 每季度审查 CLAUDE.md，删除从未触发过的规则 | 保持信号/噪音比 | | Token 预算强制 | 单会话 30K 上限，接近时强制摘要重置 | 防止语义漂移 |

判断任务 vs 决策任务的分离实践¶

规则 5（模型只做判断，不做决策）对团队的系统设计有直接影响。在引入 Claude Code 之前，团队应该先做一次任务分类审计：梳理现有开发流程中哪些环节属于"判断任务"，哪些属于"决策任务"。典型的判断任务包括：代码审查意见生成、变更摘要与 changelog 编写、技术方案的多角度分析、测试用例补充建议。这类任务适合交给 Claude，输出质量取决于 Prompt 的清晰度。典型的决策任务包括：API 路由逻辑、错误重试策略、数据库事务边界、部署条件判断。这类任务必须由确定性代码处理，Claude 的输出只能作为辅助参考而非直接执行指令。

Token 预算的分级设置建议¶

Mnilax 给出的是单任务 4K / 单会话 30K 的基准值，但这个数字需要根据实际代码库规模进行调整。 小型代码库（单个仓库 < 5K 行）：单任务预算可压缩至 2K Token，因为每次修改涉及的文件数量有限，不需要那么长的上下文。单会话预算可以维持 30K。 大型代码库（单仓库 > 50K 行，或 Monorepo）：单任务预算建议提升至 6-8K Token，因为理解一个大型模块的上下文本身就消耗大量 Token。单会话预算建议提升至 50K，同时增加"阶段性检查点"——在每个关键里程碑强制输出当前状态摘要，而非等到接近上限才触发。

CLAUDE.md 的版本演进管理¶

随着团队使用 Claude Code 的经验积累，CLAUDE.md 也会演进。以下是推荐的版本管理策略： 版本 1.0（起点）：直接采用 Karpathy 的 4 条规则，文件名存为 CLAUDE.md.base。这确保了新成员或新项目有一个可靠的起点。 版本 2.0（踩坑补齐）：每次发现一个现有规则无法覆盖的 failure mode 时，在规则文件中添加对应的行，格式为：## 规则 N+1：[规则名称]（添加日期：YYYY-MM-DD，触发场景：[具体翻车描述]）。这种记录方式确保规则有据可查。 版本 3.0（定期修剪）：每季度审查时，统计 CLAUDE.md 中每条规则的触发频率（可以在 Claude 的每次输出末尾加上[规则N被触发]的标记）。删除从未触发过的规则，或将它们移入 CLAUDE.md.archive 作为备选而非active状态。

与 Harness Engineering 的关联¶

CLAUDE.md 本质上是 Agent 的架构约束层（Architecture Constraints） 在 Harness Engineering 三支柱中的具体实现。它与 Agent Harness Context Management Working Set 中的 working set 管理共同构成 Claude Code 的记忆-约束体系。Mnilax 的 12 条规则可视为对这一约束体系的系统性补全。规则 6（Token 预算）和规则 10（检查点强制）是 Harness 思维在 CLAUDE.md 中的直接映射——前者防止语义漂移，后者确保长任务的可恢复性。这两条规则与中定义的"状态管理"和"熔断机制"在逻辑上完全一致，说明 Mnilax 的实践实际上是在用更低成本的方式实现 Harness Engineering 的核心目标。