CLAUDE.md Best Practices, 2026

作为被广泛使用的 artifact，CLAUDE.md 已经两岁了。过去十二个月，围绕它的做法变化很大。2024 年的做法是把所有东西倒进一个长文件里，然后祈祷。2025 年的做法是按 section 拆开，然后稍微少祈祷一点。2026 年的做法，来自几百个公开项目、Hashimoto / OpenAI / LangChain 关于 agent harness 设计的讨论，以及同时跑 Claude Code、Cursor、Codex 的团队给出的操作经验，开始收敛成更有纪律的一套。下面是 2026 年初这些做法的样子。

从 2024 到现在，什么变了

有三件事重塑了实践。第一，agents 自己更会少读多推断，所以 CLAUDE.md 里需要的“convention documentation” 变少了。第二，agents 对冲突和过期规则的处理变差了。部分原因是它们更信这个文件，所以一条过期规则会污染更多决定。第三，多 agent workflow 变常见了。同一个项目在一个 sprint 里会被 Claude Code、Cursor、Codex 都碰过，这意味着 CLAUDE.md / AGENTS.md / .cursor/rules 必须对齐，不能各自变成一个小王国。

实际效果是：CLAUDE.md 比以前更短，比以前更严格，而且越来越常和并行文件（AGENTS.md、.cursor/rules、.codex/instructions）一起写，并保持一致。

当前共识：八条规则

这些 practices 通过了“我见过的运行良好的项目里，超过一半都这么做”的门槛。它们不是普遍真理。但如果你在选要采用哪些 practices，这些回报最好。

规则一：控制在 250 行以内。 超过这个长度，人和 agent 都会 skim-read。这个上限不是随便定的；它跟 agent 会话开始时能吸收多少内容有关，而且不应烧掉超过 5% 的 context budget。很多 2026 年开头超过上限的项目，后来都重写变短了。

规则二：每条规则都必须可证伪。 “Write good code” 不可证伪。“All async functions must have a timeout” 可以。2025 年那种软指令（“consider doing X”）已经不受欢迎了。agents 要么把软规则当硬规则，要么完全忽略，而这种不确定性比两者都糟。把每条规则写成硬规则，或者删掉。

规则三：每条规则都配执行层。 只活在 CLAUDE.md 里的规则是愿望。2026 年的做法是每条规则都有明确执行层：hook、CI check、linter rule，或者明确的 “advisory only” tag。advisory tag 很重要：它告诉 agent（也告诉贡献者）这条是偏好，不是 guard，从而校准执行强度。

规则四：捕捉决定，不是行为。 “Use TypeScript strict mode” 描述的是项目当前行为，agent 可以从 tsconfig.json 读到。“We use TypeScript strict because we got burned by an any cascade in Q3 2024” 捕捉的是决定和理由，这是 agent 不能从代码里读到的。2026 年的文件更偏向后者。

规则五：让 CLAUDE.md 和并行文件对齐。 如果项目有 AGENTS.md，两份文件不能互相冲突。.cursor/rules、.codex/instructions 和任何其他 harness file 也一样。推荐做法是让 CLAUDE.md 成为 canonical source，其他文件要么 symlink，要么从它生成，要么 include 它。手动跨文件维护，是每个多工具项目最终出问题的失败模式。

规则六：明确沟通风格。 写清 agent 应该用什么语言沟通、什么语气、要多详细。“English, terse, no preamble before tool calls” 就是一条完整指令。没有这条，agent 会选自己的默认值，而它可能不符合团队偏好，并且成本会一场会话一场会话累积。

规则七：维护一个明确的 principles section。 三到七条 principles，每条一句 rationale。Principles 是没有其他规则适用时会用到的规则。没有它们，agent 的 defaults 会接管，而那些 defaults 不一定符合项目。有了它们，edge cases 会更像你自己会处理的方式。

规则八：每季度 review。 放进 calendar，不是含糊地“以后看看”。即使你不主动 edit，文件也会漂，因为项目周围在变。季度 review 能在漂移变成事故前抓住它。

已经被淘汰的 anti-patterns

有些 2024 年很常见的做法，现在已经被认为有害。还在这么做的项目，其实是在和自己的文件打架。

第一是 kitchen-sink section。一个 “Coding Standards” section 写 200 行，想覆盖所有可能 pattern。这类 section 从来没人完整读，而且软规则太多，会稀释真正严格的规则。2026 年的替代品，是一个 20 行的 “Language & Style” section，只写 linter 不能执行的规则。

第二是 philosophy section。几段关于团队价值观、使命、设计哲学的话。写起来很舒服，但没有行动价值。2026 年的做法是删掉它们，或移到单独的 values doc。

第三是 historical archive。章节里解释项目过去做过什么，从什么迁过来，试过什么又放弃了。这对人类 onboarding 有用，对 agents 反而有害，因为 agent 有时会把已经放弃的方法当成当前选项。

第四是 meta-section。关于 CLAUDE.md 自己的规则，比如“keep this file under 200 lines” 或 “every rule should be falsifiable”。这些属于团队关于 CLAUDE.md 的文档，不属于 agent 会话开始时要读的文件。告诉 agent 这个文件的写作规则，对 agent 没帮助。

第五是 duplicated rule。同一条规则出现在两个 section，因为两个人没看到对方的 edit，都加了一遍。AgentLint 现在能抓这种问题，多数跑它的团队都删掉了之前积累的重复项。

一份 2026 形状的 CLAUDE.md skeleton

这是 2026 年新写文件时已经变成默认的结构：

## Project (1 paragraph)
What it is. Stack. Audience.

## Non-negotiables (5-10 rules)
Hard process rules. Each falsifiable. Each enforced.

## Language & Style (5-15 rules)
Things the linter cannot enforce. Type policy. Imports.
Naming conventions the linter does not cover.

## Operational Notes (5-15 rules)
Surprising facts about the environment. Symlinks. Flaky CI steps.
Tokens that expire. Services that need warm-up.

## Communication (3-5 rules)
Language. Tone. Verbosity. Markdown vs plain.

## Principles (3-7 rules with rationale)
The rules that apply when no other rule applies.

## Enforcement (auto-generated or hand-maintained)
Mapping of rule → hook / CI step / "advisory only" tag.

这就是 AgentLint 的 --init command 生成的 skeleton。项目自己的规则放进去；skeleton 本身保持在 100 行以内。

2027 可能会去哪里

有两个趋势已经清楚到值得标记。第一个是 machine-readable CLAUDE.md。一些项目开始试 structured frontmatter 和 YAML-tagged sections，让 tooling 可以确定性 parse 这个文件。AgentLint 和类似 linters 会受益；agents 也许最终会受益。风险是这个文件变成穿着 markdown 衣服的 config file，丢掉了 CLAUDE.md 一开始有价值的 prose readability。

第二个是 CLAUDE.md as a contract。一些项目把 CLAUDE.md 作为 PR contract 的一部分：每个 PR 要么通过当前文件，要么修改这个文件。这把文件当成 versioned commitment，而不只是 living document。还很早，证据混合，值不值得这份 friction 还不好说。

现在，在 2026 年，有纪律的 defaults 就是上面这些。短。可证伪。被执行。跨工具对齐。每季度 review。AgentLint 做最后一遍扫。做到这些的团队，CLAUDE.md 明显在承重；没做到的团队，文件会安静地漂进 dead-letter pile。你要站在哪一边，自己选。