目 录
4.1 上下文污染（Context Pollution）——最核心的问题
一、claude.md是什么？
1.1本质定义
CLAUDE.md 是一个放在项目根目录（或用户全局目录 ~/.claude/）的 Markdown 文件。Claude Code 在每次会话启动时自动读取它，并将其注入到 system prompt 中，不需要任何额外配置。
技术本质：System prompt 的持久化自定义扩展。 不需要用户每次对话都手工注入，而是通过文件系统自动加
参考：Anthropic 官方文档 — Give Claude context: CLAUDE.md and better prompts | Claude Code Docs — How Claude remembers your project
1.2 和 AGENT.md、MEMORY.md 的区别
| 文件 | 谁在读 | 何时生效 | 作用域 |
|---|---|---|---|
| CLAUDE.md | Claude 主 agent | 当前项目的所有会话 | 项目级 |
| AGENT.md | 子 agent | 当主 agent 派生 agent 执行子任务时 | 子任务级 |
| MEMORY.md | Claude 主 agent | 所有会话、跨项目 | 用户级 |
三者本质相同——都是注入行为层，区别仅在于作用范围和触发时机。
参考：Claude Code Docs — 探索 .claude 目录
1.3 核心理解
"CLAUDE.md 是在不改变原有训练好的 prompts 内，注入新的规则约束准则。"
它不是给 AI 喂数据，而是给 AI 装方向盘。没有方向盘车也能开，只是方向不对；没有 CLAUDE.md AI 也能干活，只是可能走偏。
二、它能做什么
2.1 正确用法：行为规则层
CLAUDE.md 真正该承载的是不依赖具体项目状态的通用行为准则，不是项目的"数据快照"。
循环跳脱规则（防死循环）：
多步骤任务中，若某一步重试 3 次失败，跳过该步继续执行下一步，
在结果中注明哪些步骤被跳过及原因。价值：防止 AI 在死胡同里空烧 token，赋予 AI 它不具备的"元认知"——AI 默认不会主动跳过卡住的那一步。
静默验证规则（减少中断）：
每次修改代码后自动跑 lint → 类型检查 → 测试。
不再每步询问"是否执行？"价值：IDE 里每步都要弹窗问你，CLI 全托管模式下一口气跑完。减少了上下文碎片化——每次中断再恢复，AI 都要重新定位"我在干什么、改了什么"。
已知陷阱记录：
修改 src/api/ 下的类型文件后，注意 openapi-generator 的自动生成文件可能被覆盖。价值：踩过的坑记录下来，下次自动绕开。
2.2 一句话判断标准
每一条 CLAUDE.md 规则，都应该能回答："为什么我必须告诉 AI 这个？AI 自己不可能知道吗？"
- AI 自己能读目录结构 → 不需要写
- AI 自己能读 package.json / tsconfig.json → 不需要写
- AI 不知道你项目里哪些坑反复出现 → 值得写
- AI 不知道你的代码风格取舍 → 值得写
参考：CLAUDE.md Examples and Best Practices 2026 | Morphllm | CLAUDE.md: The Complete Guide to Configuring Claude Code (2026)
三、市面上在吹嘘什么
3.1 两类人
真诚但盲目的人：他们确实在自己的项目里受益了，但没意识到受益的原因是自己的项目有足够多的上下文积累（踩过的坑、磨合出来的规则），而不是模板本身。分享出来，别人拿去用，效果差很多——规则脱离了它生长的土壤。
纯粹卖概念的人：把"AI 配置"包装成新风口，出模板、出课程、出"必装清单"。核心卖点是确定性——"用这套模板，AI 就不会乱写了"——但这个确定性本质上不成立。
3.2 典型的营销话术 vs 实际情况
| 吹嘘的 | 实际情况 |
|---|---|
| "5 个 skills 让你的效率翻 10 倍" | 零项目零配置开局注入一堆通用指令，反而增加噪声 |
| "这套 CLAUDE.md 模板适用于所有项目" | 一个模板的适用半径只限于它诞生时的那个项目 |
| "装上就能让 AI 听你的" | AI 不遵守规则时，用户的第一反应是加更多规则——恶性循环 |
3.3 心理暗示引导结果论
"这不叫开发，这叫心理暗示引导结果论。" —— 很多人得到的不是真正的效率提升，而是"我配好了"的完成感。真正缺的环节是验证反馈——代码有测试和 CI 来衡量，CLAUDE.md 有没有拖慢效率，没有指标给你看。
四、存在的问题
4.1 上下文污染（Context Pollution）——最核心的问题
恶性循环：
加载 CLAUDE.md（大量项目快照）→ AI 读真实代码（发现 CLAUDE.md 过时了）→
花 token 对比、诊断差异 → 决定以实际代码为准 → 延迟多步后才开始干正事数据支撑：有开发者追踪 430 小时 Claude Code 使用，发现只有 27% 的 token 在做实际工作。CLAUDE.md 膨胀占了约 14% 的浪费。
参考：Audit and optimize initial context window budget for Claude Code sessions · Issue #404 | CLAUDE.md instructions wrapped in "may or may not be relevant" disclaimer · Issue #22309
4.2 信息过期——比没有更糟糕
- 没有自动过期机制 —— 文件写进去就一直生效，但项目会变
- 信噪比下降 —— 人倾向于往里面加东西但很少删
- 正向反馈缺失 —— 写错了不会有报错，过期了也不会有告警
结果：过期文件比没有文件更糟糕。 没有 CLAUDE.md 时，AI 至少不会主动走向错误的方向；有了过期的，它可能忠实地执行已经不存在的约定。
参考：The CLAUDE.md Memory System - Optimization Guide | SFEIR Institute
4.3 重复冗余——隐形 token 消耗
真实案例：一个 634 行的 CLAUDE.md 中，同一规则出现 3-5 次，约 200-300 行是冗余的，浪费 35-40% 的上下文 token。每轮对话都要为重复内容付费。
参考：Generated CLAUDE.md guidelines are excessively repetitive · Issue #58 · knowns-dev/knowns
4.4 小任务配大指令——成本倒挂
改一个 API 参数、加一段 20 行的逻辑——如果臃肿的 CLAUDE.md 占了大量上下文，加载成本 > 节省的纠错成本，它是负资产。
4.5 AI 本身会忽略过期规则
有用户记录 756 次 AI 偏离 CLAUDE.md 规则。AI 的自我分析："我的训练把'有帮助'理解为'生成东西'，而不是'遵守流程'。" 往 CLAUDE.md 里加更多话并不能解决遵守问题，只会让文件更臃肿。
参考：Model Overrides Documented Protocols Even When Context Is Present (756 Deviations) · Issue #16162
4.6 "放 AI 自己读得到的东西"反模式
AI 可以自己读目录结构（ls）、读配置（package.json）、搜索代码（grep）。把这些写进 CLAUDE.md 等于：消耗 token 存一份可能过期的副本 + 让 AI 花费额外 token 对比差异 + 冲突时多一轮诊断。
参考：AI Optimization: CLAUDE.md Refactoring & Context Files · Issue #107 · dcgoodwin2112/dkanClientTools | CLAUDE.md | Developing with AI Tools | Steve Kinney
五、怎么优化和写
5.1 核心原则：精简，不断删
推荐长度：
- 项目级 CLAUDE.md：50-80 行，上限 120 行
- 用户级：30-40 行
- 二者合并：上限 150 行
删的原则：
- AI 能自己读到的 → 删
- 跟 README 重复的 → 删
- 标准语言规范 AI 本来就知道的 → 删
- 模糊指令（"写好的代码""遵守最佳实践"）→ 删
- 已废弃的约定 → 删
- 同一规则出现超过一次 → 删
参考：CLAUDE.md Examples and Best Practices 2026 | Morphllm | refactor: Simplify CLAUDE.md Files (Follow Official Best Practices) · Issue #62 · kcenon/claude-config | GitHub - drona23/claude-token-efficient
5.2 行为规则占 70%
| 类别 | 占比 | 示例 |
|---|---|---|
| 行为规则（命令、约束、流程） | ~70% | "改接口后必须 lint 类型检查" |
| 项目上下文（AI 无法从代码推断） | ~20% | "这个项目是 monorepo，api 和 web 是独立包" |
| 外部引用 | ~10% | "API 文档参考 docs/api-spec.md" |
5.3 实用的规则模板
循环跳脱：
多步骤任务中，若某一步重试 3 次失败则跳过并继续执行下一步，
在最终结果中注明哪些步骤被跳过。静默验证：
每次修改代码后自动：lint → 类型检查 → 相关测试。
任一步失败则修复后重跑全流程，直到全部通过。已知陷阱：
修改 src/api 类型后：注意 openapi-generator 自动生成文件可能被覆盖。
先备份再改动，完成后对比差异。5.4 推荐目录结构
.claude/
settings.json ← Hook 配置（确定性验证——必执行）
rules/
testing.md ← paths: ["**/*.test.ts"]（处理测试文件时才加载）
api-routes.md ← paths: ["src/api/**/*.ts"]
CLAUDE.md ← 核心行为规则（50-80 行）5.5 Hook：取代 CLAUDE.md 中的确定性规则
Hook 写在 .claude/settings.json 里，是确定性的（AI 无法绕过），不像 CLAUDE.md 是建议性的（AI 可能忽略）。
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"command": "npx tsc --noEmit && npx eslint --fix \"$CLAUDE_FILE_PATH\""
}]
}
}含义：每次 Claude 改了文件，自动跑类型检查和 lint 修复。不需要 AI "记得"——Hook 强制执行。
| CLAUDE.md | Hook | |
|---|---|---|
| 本质 | 建议性 | 确定性（强制执行） |
| AI 能不遵守吗 | 能 | 不能 |
| 适合放什么 | 行为偏好、流程约定 | lint、格式化、类型检查 |
参考：Claude Code power user customization: How to configure hooks | Claude Code Hooks: The Complete Guide to Automating Your Workflow | Felo Search Blog | Claude Code Hook Examples | Steve Kinney
5.6 维护节奏
- 每次 Claude 犯同一个错误两次 → 这是一个行为规则缺失的信号，写入
- 每次项目约定变更 → 同步更新
- 每季度扫一眼 → 删除过时条目
- 不要等到需要大修时才动 → 每次改一点，保持活跃修剪
六、一个独特的视角：从 TA 接口到 CLAUDE.md
6.1 本质是同一件事
我之前做 TA 接口生成：
prompts.md / .py → 注入 system prompt → 生成 TA →
跑测试用例验证准确率CLAUDE.md：
CLAUDE.md → 注入 system prompt → 指导 AI 行为 →
跑验证 → 踩坑后修正底层逻辑完全一样，只是工具标准化了。 这不是新概念。
6.2 市面缺的内容：一个验证闭环
CLAUDE.md 现在没有：
- lint 来检查 CLAUDE.md 内容是否过时
- CI 来验证规则是否真的被遵守了
- 指标来量化每条规则的 token 成本 vs 收益
如果有一天 CLAUDE.md 能像代码一样跑 CI、跑评测，噪声才会减少。
七、总结
- CLAUDE.md 是方向盘，不是燃料。 AI 不需要你喂项目数据，它自己会读。它需要你告诉它往哪走。
- 行为规则永不过期，项目快照必定过期。
- 越短越好。 50-80 行的项目级 CLAUDE.md 是甜蜜点。
- 一句话判断：AI 自己不可能知道吗？ 不能 → 写。能 → 删。
- 确定性的事用 Hook，不要用 CLAUDE.md。 lint、类型检查、格式修复——Hook 强制执行。
- 过期 CLAUDE.md 比没有更坏。 没有时 AI 至少不会走错误的方向。
- 零项目零配置不要照搬模板。 先跑出来，踩了坑，再把教训写进去。
市面上关于 CLAUDE.md 的讨论，多数在制造信仰和寻找安慰。真正有用的方向是：让 AI 的行为规则有验证、有迭代、有生命周期控制。 在一些测试接口生成带来的闭环思维——测试、准确率、成本收益核算——远比那些"一键提效"的模板更有价值。
扫一扫
727
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
