2026/08/02

CLAUDE.md：四条规则如何让编码智能体更高效

了解 CLAUDE.md 如何工作、为什么四条编码规则在 2026 年爆火、文件中应包含哪些内容，以及如何构建一份有效的项目指令模板。

一份优秀的 CLAUDE.md 不会让模型变聪慧。它做的是减少歧义——每次智能体进入你的代码库时都更清楚该怎么做。

这个简朴的机制解释了一个围绕四条纯文本编码规则构建的代码库为何成为 2026 年最令人瞩目的智能体项目之一。这四条指令要求智能体先思后行、优先选择简单实现、保持改动精准、明确定义可验证的成功标准。没有一条是新颖的软件工程技巧。但把这四条都放进上下文、在每次任务前都让智能体读到，才是真正有用的部分。

关于那个文件的病毒式标题说一个仓库获得了 91,000 个 GitHub 星。到 2026 年 8 月 2 日为止，该仓库已从 forrestchang 转移到 multica-ai，演进成了插件和编辑器规则，并根据 GitHub API 获得了 198,529 颗星。^[1]这个数字还会继续变化。持久的教训是小小的、持续的指令如何改变智能体行为。

TL;DR

CLAUDE.md 是一个包含持久指令的 Markdown 文件，Claude Code 在会话初始时加载它作为上下文。^[2]
走红的仓库把常见的智能体失败浓缩成四条规则：先思后行、简单优先、精准改动、目标驱动执行。^[3]
这个文件最适合用来存放几乎每次会话都需要的事实和规则：命令、架构、代码约定、边界条件和验证方法。
CLAUDE.md 是上下文而非强制。对于必须技术上被阻止的操作，应该用权限或钩子。^[2]
把任务特定的流程放在 skill 里，把文件特定的指导放在 .claude/rules/ 里；全局加载一切会浪费上下文。
一份有用的文件应该短到可维护、具体到可测试、在智能体犯同样错误时及时更新。

CLAUDE.md 是什么？

CLAUDE.md 是 Claude Code 的项目指令文件。通常这是个提交到代码库根目录的普通 Markdown 文件，为智能体提供持久上下文，比如：

如何安装、测试、构建和格式化项目；
那些从文件名看不出来的架构特征；
命名和代码风格约定；
哪些生成的文件不应手动编辑；
任务完成前必须通过的检查；
特定于代码库的安全边界。

Claude Code 在会话开始时读这个文件。Anthropic 把它描述为两个记忆机制之一：人们编写 CLAUDE.md 指令，而 Claude 的自动记忆则存储从更正中学到的模式。^[2]

这听起来像配置，但 Anthropic 做了一个重要区分。这些指令进入模型的上下文；它们不是硬性控制。如果"绝不部署到生产"必须得到保证，合适的做法是 PreToolUse 钩子或权限边界。Markdown 中的一句话可以指导行为。但它给不了安全保证。

为什么这份四规则文件走红了

现在叫 multica-ai/andrej-karpathy-skills 的仓库说它的指南来自 Andrej Karpathy 对编码模型失败模式的公开观察。^[3]它的人气容易被过度解读。其实每条规则都把开发者常见的挫折映射到智能体可以执行的行为。

常见失败	持久指令	可观测结果
智能体默默猜测你的意思	先思后行	假设和歧义在改代码前浮出水面
小请求膨胀成框架	简单优先	更少的推测抽象，更少的代码
无关文件在"顺便"时改掉	精准改动	更小的 diff，每行都关联到请求
智能体宣称成功而未证明	目标驱动执行	测试和成功标准关闭反馈环

这些规则不教 TypeScript、数据库设计或调试。它们塑造模型如何处理不确定性和范围。这使它们可在不同代码库间复用。

简朴本身也是社交优势。一个团队能在两分钟内读完四条原则、不同意其一、编辑它、在 Git 中审查改动。没有隐藏的提示词平台要管理。

四项原则转化为项目行为

1. 先思后行

原始指南要求智能体声明假设、在必要时提供多种解释、质疑不必要的复杂性、在真正困惑时停下来。^[3]

项目特定的措辞会让它更强大：

改 API 契约前，识别代码库中所有消费者并声明改动是否后向兼容。
如果产品行为模糊，停下来提问；不要默默选择行为。

通用原则设定态度。具体补充告诉智能体哪里的错误假设最昂贵。

2. 简单优先

"别过度工程" 在方向上有用但难以验证。加上代码库对"简单"的本地定义：

优先选择现有工具而非新抽象。不要为单个调用点引入 service、factory 或配置开关。
只实现请求的行为；把可选后续工作列为建议而非预先构建。

这减少了一个可预测的模型倾向：解决假设的未来问题族而非当前问题。

3. 精准改动

智能体广泛阅读所以能看到附近的清理机会。但这不代表任务授权了每个清理。

每改一行都必须关联到请求。保留周围的格式和命名。
删除被你的编辑弄成未使用的导入，但改为报告无关的死代码而非删除它。

小 diff 更容易审查、测试、回滚和分配。它们也降低了智能体破坏它未理解其目的的东西的机率。

4. 目标驱动执行

"让它工作" 这样的指令留下终态未定义。把任务转化为智能体可检查的结果：

对 bug 修复，在改生产代码前用测试重现失败。迭代时跑最窄的相关检查，
完成前跑完整的项目检查。报告命令和输出。

这是自主性开始有用的地方。当成功是可观测的，智能体可对失败迭代而非在第一个看起来可信的编辑后停止。

一份项目指令图表显示命令、边界、风格和验证流入编码智能体行为

CLAUDE.md 应包含什么

Anthropic 建议在 CLAUDE.md 里保留 Claude 该在每个会话都持有的事实，而把多步或窄范围的流程转移到更有针对性的机制。^[2]有用的测试是："我会在几乎每个任务的入职讲解中重复这个吗？"

放在根文件里

一段落的项目和架构描述；
package manager 和规范的 install、dev、test、type-check、build 命令；
目录所有权和生成文件边界；
跨语言或包应用的规则；
"完成"的定义；
高频错误及其更正；
深度指导的位置。

放在其他地方

信息	更好的位置	原因
个人沙箱 URL 或本地偏好	`CLAUDE.local.md`	仅适用于一个开发者，通常应该被 Git 忽略
仅适用于 `src/api/**` 的规则	`.claude/rules/api.md` 带 `paths`	在相关时加载而非每个会话
发布或迁移流程	Skill	多步工作流仅在需要时调用
绝不能跑的命令	权限或钩子	强制不应依赖模型遵从
临时任务细节	当前提示或 issue	它们在持久上下文中会过期
长设计文档	现有文档，简洁链接	避免每次任务都付上下文代价

一份简洁的 CLAUDE.md 模板

复制这个作为起点，然后替换每个方括号项。删除不限制你项目的部分。

# 项目指令

## 项目

[一段话：这个仓库发行什么、主运行时是什么、最重要的架构边界是什么。]

## 命令

- 安装：`[命令]`
- 开发：`[命令]`
- 小范围测试：`[命令加文件或模式]`
- 完整测试：`[命令]`
- 类型检查：`[命令]`
- 构建：`[命令]`

## 编辑前

- 在提议改动前读最近的现有实现和测试。
- 声明影响公开行为、数据、安全或兼容性的假设。
- 如果请求有多个本质不同的解读，提问。

## 范围

- 只实现请求的行为。
- 优先选择现有模式和工具而非新抽象。
- 保持 diff 精准；除非必要不要重构邻近代码。
- 仅删除你的改动产生的死代码。

## 项目边界

- `[路径]` 是生成的；改 `[源路径或命令]` 代替。
- `[包]` 拥有 `[职责]`；不要在 `[其他包]` 中复制它。
- 绝不在日志或 fixture 中暴露 `[密钥或私密数据类别]`。

## 风格

- [两到五条偏离格式化工具默认或容易遗漏的规则。]
- 当没有显式规则时匹配周围文件。

## 验证

- 对 bug 修复，添加或更新在修复前会失败的测试。
- 迭代时，跑最窄的相关检查。
- 完成前，跑：`[必需命令]`。
- 报告改过的文件、跑过的命令、输出和任何未验证的风险。

## 深度指导

- API 工作：`.claude/rules/api.md`
- 数据库改动：`[skill 或文档路径]`
- 发布：`[skill 或文档路径]`

这个模板故意简朴。CLAUDE.md 不该读起来像励志宣言。它应该减少智能体否则得猜的决定。

Claude Code 如何加载多个指令文件

Claude Code 从当前工作目录向上遍历目录树，加载它找到的 CLAUDE.md 和 CLAUDE.local.md 文件。离启动目录更近的指令在上下文中出现得更晚。嵌套在工作目录下的文件在 Claude 读取那些子目录中的文件时加载。^[2]

对于 monorepo，这允许有用的层级：

repo/
├── CLAUDE.md                 # 组织范围的项目事实
├── .claude/
│   └── rules/
│       ├── testing.md        # 无范围的共享规则
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Web 特定架构和检查
│   └── worker/
│       └── CLAUDE.md         # Worker 运行时限制
└── CLAUDE.local.md           # 仅开发者的本地笔记

文件作为上下文串联而非表现得像严格的配置覆盖。矛盾规则因此可能产生不一致行为。定期审查层级并删除陈旧指令。

如何从真实失败改进文件

别试图在第一天预测每个可能的错误。从小开始，用重复的摩擦作为待做清单。

记录失败。 智能体做了什么，你期望什么？
找对层级。 这是通用指令、路径特定规则、任务流程还是硬安全控制？
写个可观测规则。 用行动和条件替换 "小心"。
在类似任务上测试。 确认行为改进而不阻止琐碎工作。
删除陈旧规则。 上下文有代价；过时指令比没有指令更糟。

Anthropic 的实用触发点令人难忘：当 Claude 犯同样错误第二次、代码审查发现智能体该知道的知识、或你在会话间重复同样更正时，加些东西。^[2]

五个要避免的 CLAUDE.md 错误

写抱负而非指令

"写优秀、鲁棒的代码" 没给出新信息。"改 packages/api 下的内容后跑 pnpm test --filter api" 可以被遵循和检查。

复制巨大通用规则书

公开模板可以提供思路，但每条无条件的行都消耗上下文、可能与项目冲突。如果有帮助就保留四个宽泛行为原则；用本地事实替换通用技术建议。

编码智能体能廉价发现的事实

你很少需要列每个目录。解释文件名不显露的边界，比如哪个包拥有授权、哪个源生成了一个检入的客户端。

把指令当成安全控制

绝不依赖 "不要读密钥" 或 "不要部署" 作为唯一保护。对硬边界用有范围的凭证、权限、沙箱和钩子。

从不审查文件

命令改变、包移动、老异常变成默认行为。分配所有权并像审查代码那样审查 CLAUDE.md。

如何知道它是否工作

避免用是否一个演示看起来印象深刻来判断文件。测量团队已经审查的工作：

每个完成任务的中位改动行数；
接触到的无关文件；
代码审查评论由代码库约定违反引起；
首次通过测试成功；
宣称完成后重开的任务；
该成为持久上下文的重复澄清。

走红的仓库建议相同的结果级别测试：更少不必要的 diff 改动、更少由过度复杂化引起的重写、实现前的澄清而非出错后的改正。^[3]

如果你对工具本身还陌生，从更宽泛的 Claude Code 使用指南开始。在安装完成、下一个问题是你的智能体每次进代码库应该知道什么时，用这篇文章。

参考资料

GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

进阶阅读

reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
reAPI. Claude model catalog. reapi.ai/models

全部文章