TL;DRCLAUDE.md不是给人读的文档是给模型读的工程规格。它控制 Claude Code 的行为边界每次会话都被全量加载到上下文。写得好省掉反复提醒写得差浪费 Token 还不生效。CLAUDE.md 是工程规格不是文档大多数团队第一次写CLAUDE.md会本能地抄一段 README 进去——项目介绍、技术栈、团队使命。这些信息对人有用对模型几乎没用。模型不关心你们的愿景它关心的是跑什么命令、改哪些文件、遵守什么边界、不能碰什么东西。CLAUDE.md的本质是一份机器可读的行为规格。它有以下工程属性•每次会话全量加载无论任务大小CLAUDE.md 的全部内容都会被注入上下文。这意味着每一行都在持续消耗 Token 预算。•层级覆盖用户级~/.claude/CLAUDE.md→ 项目级./CLAUDE.md→ 子目录级subdir/CLAUDE.md后者覆盖前者。跨项目通用的偏好放用户级项目特定的放项目级。•支持文件导入other-file.md语法可以把外部文件内容内联进来。适合拆分长规则到独立文件。•不是强制策略CLAUDE.md 是上下文不是策略引擎。模型可能会忽略其中的规则。真正需要强制的安全边界要用 Hooks 实现见第 22 篇。理解这一点很关键CLAUDE.md 里的规则是建议不是约束。你在里面写不要改 .env模型多数时候会遵守但不是 100%。如果某条规则违反了就必须中断操作那它属于 Hooks 的管辖范围。一个常见的误解是CLAUDE.md 写得越详细Claude Code 就越听话。实际上CLAUDE.md 的效果遵循一个倒 U 型曲线——太少的信息让模型无从遵循太多的信息让模型失去焦点。最佳区间在 60 到 120 行之间。低于 60 行缺少关键约束超过 120 行规则之间互相干扰遵循率开始下降。后文的 Token 预算分析和失败案例会展开这个论点。另一个误解是CLAUDE.md 可以替代 README。不能。README 是给人看的描述项目是什么、为什么这么做CLAUDE.md 是给模型看的描述怎么操作、不能做什么。一个好的检验标准如果删掉 CLAUDE.md 里某段话模型的行为是否会改变如果不会那段话就不该在那里。三个真实的 CLAUDE.md不是模板是实际在用的配置。三个项目三种技术栈三种关注点。A. TypeScript API 服务这个项目的核心需求是分层架构约束——Claude Code 必须知道每一层该干什么、不能干什么否则它会在 route handler 里写业务逻辑。# CLAUDE.md## Commands- Install:pnpminstall- Dev:pnpmdev - Test:pnpmtest(unit),pnpmtest:e2e(integration)- Lint:pnpmlint - Typecheck:pnpmtypecheck - DB migrate:pnpmprisma migrate dev## Architecture- src/routes/ — Express route handlers, thin layer, delegate to services - src/services/ — Business logic, no HTTP imports - src/repositories/ — Database access only, no business logic - src/models/ — Prisma-generated types only, never edit manually - src/utils/ — Shared helpers, no side effects## Rules- Routes MUST NOT contain business logic - Services MUST NOTimportfrom express - Repositories are the only layer that touches prisma client - All new endpoints need integration testsintests/e2e/ - Use zodforrequest validation, never trust req.body directly## Safety- Do not edit prisma/schema.prisma without explicit approval - Do not modify migrations after they#x27;ve been applied- Do nottouch.env files - Do not runpnpmprisma migrate reset## Testing- Run relevant unit tests after editingservicefiles - Run integration tests after adding endpoints - Testcommandforsingle file:pnpmvitest run src/services/user.test.ts关键设计Architecture 段落用一句话定义每个目录的职责和限制。Rules 用 MUST NOT 做硬边界声明。Testing 段落不只说要测试而是明确给出什么操作触发什么测试。B. React 前端Next.js前端项目的关注点不一样组件复用、样式约束、路由结构、SSR 边界。# CLAUDE.md## Commands- Install:pnpminstall- Dev:pnpmdev - Build:pnpmbuild - Lint:pnpmlint - Typecheck:pnpmtypecheck - Test:pnpmtest## Architecture- app/ — Next.js App Router, page.tsx layout.tsx only - components/ui/ — Primitive components(Button, Input, Dialog), no business logic - components/features/ — Feature-specific composite components - lib/ — Shared utilities and hooks, no React components - lib/api/ — API client functions, generated from OpenAPI spec - styles/ — Global styles and Tailwind config## Rules- Use Tailwind classes only, no inline styles, no CSS modules - Import components from /components/ui, neverwriterawbuttonorinput- Server Components by default,adduse clientonly when state/effects needed - Data fetchinginServer Components or Server Actions, notinuseEffect - Form mutations use Server Actions, not API routes - Do not create new API routes unless explicitly asked## Safety- Do not edit tailwind.config.ts without approval - Do not modify next.config.js without approval - Do notinstallnew UI libraries without checkingifexisting components suffice - Do nottouchlib/api/ — it is auto-generated## Testing- Runpnpmtestafter modifying components - Testfilecolocated: ComponentName.test.tsx next to ComponentName.tsx - Prefer testing-library, no Enzyme关键设计Rules 段落明确默认 Server Component按需加 use client——这是 Next.js 项目最容易出错的地方。Safety 里不要装新 UI 库防止 Claude Code 动不动引入 shadcn 新组件。C. Python ML 服务ML 项目有独特的约束数据管线、模型文件、实验可复现性。# CLAUDE.md## Commands- Install: pipinstall-e.[dev]- Dev: python-msrc.main - Test: pytest tests/-v- Lint: ruff check src/ - Format: ruffformatsrc/ - Train: python-msrc.train--configconfigs/default.yaml - Evaluate: python-msrc.evaluate--checkpointcheckpoints/latest.pt## Architecture- src/data/ — Data loading and preprocessing pipelines - src/models/ — Model architectures, PyTorch nn.Module only - src/training/ — Training loops, loss functions, schedulers - src/evaluation/ — Metrics, visualization, report generation - configs/ — YAML config files, one per experiment - notebooks/ — Exploration only, neverimportfrom notebooks into src/## Rules- All data paths go through configs, no hardcodedfilepathsinsource- Model changes must be backward compatible with saved checkpoints - Use PyTorch, not TensorFlow - Usetypehints everywhere, run mypy before committing - Do not modify configs/default.yaml — create a new configforexperiments - Keep notebooks stateless:clearall outputs before committing## Safety- Do not delete or modify files under checkpoints/ - Do not run training without specifying a configfile- Do not modify src/data/loader.py without running full pipelinetest- Do not push large model files(100MB)togit## Testing- Run pytest after modifying any src/file- Test data pipeline separately: pytest tests/test_data/ - Integrationtestafter model changes: pytest tests/test_training/ - Single file: pytest tests/test_data/test_loader.py-v关键设计ML 项目最大的坑是可复现性。Rules 里的所有数据路径走 configs和模型变更必须向后兼容 checkpoint直接防止 Claude Code 破坏实验可复现性。Safety 段落的不要删 checkpoints 目录下的文件看似简单但这类规则如果只在 CLAUDE.md 里声明而没有 Hooks 兜底一旦模型认为删除旧 checkpoint 是清理空间的合理操作损失不可逆。三个例子的共同模式回看这三个配置可以发现一个共同结构。每个 CLAUDE.md 都包含五个段落每个段落的职责固定Commands回答怎么跑。列出安装、开发、测试、lint、类型检查的完整命令。不给这些信息Claude Code 会猜——它可能猜对用 npm 代替 pnpm也可能猜错用 jest 代替 vitest。一旦猜错后续所有操作都建立在错误的工具链上。Architecture回答东西在哪。用一句话描述每个关键目录的职责和限制。这不是给人看的架构文档是给模型的导航图。没有它模型会通过搜索推断结构——读 ten 个文件来猜目录职责浪费数千 tokens还可能猜错。Rules回答怎么写。用 MUST / MUST NOT 做明确的约束声明。关键是具体不要写注意代码质量要写Services MUST NOT import from express。前者是人的价值观后者是机器可执行的条件判断。Safety回答不能碰什么。列出所有禁止修改的文件和禁止执行的命令。这些规则需要 Hooks 兜底——CLAUDE.md 里列出是为了让模型理解原因Hooks 里拦截是为了确保执行。Testing回答怎么验证。不只说要测试而是明确什么操作触发什么测试命令。给单文件测试命令尤其重要——没有它Claude Code 会跑全量测试一个 2000 个测试的仓库等两分钟消耗大量 Token 在测试输出上。内容分层策略什么放哪里CLAUDE.md 不是唯一的行为配置点。Claude Code 有三层规则载体各有不同的加载时机和 Token 成本。|内容类型|放在哪里|加载时机|Token 成本|适用场景|| — | — | — | — | — ||命令和构建步骤|CLAUDE.md|每次会话|高每次全量加载|所有项目都需要||全局架构规则|CLAUDE.md|每次会话|高|分层架构、编码规范||按路径的编码规则|.claude/rules/|匹配路径时|中按需加载|monorepo 不同 package||特定任务流程|Skill|触发任务时|低仅任务期间|复杂工作流如部署||长脚本和模板|Skill resources|明确引用时|最低|代码生成模板、提示词|决策逻辑•每个开发者都需要知道的命令、架构、安全边界→CLAUDE.md•只有改某个目录时才需要知道的UI 组件规范、API 风格→.claude/rules/•只有执行特定任务时才需要知道的部署流程、数据迁移→ Skill错误做法把所有规则都塞进 CLAUDE.md。一个 400 行的 CLAUDE.md 里可能有 200 行只在改某个子目录时才有用但它们每次会话都在消耗 Token。详见后文失败案例。正确做法CLAUDE.md 保持精简建议 120 行以内路径特定规则拆到.claude/rules/见第 05 篇任务流程封装为 Skill见第 08 篇。Token 预算分析CLAUDE.md 不是免费的。每次会话启动它的全部内容都会被注入上下文。以下是基于实际使用估算的 Token 消耗CLAUDE.md 行数 → 大致 Token 消耗 ├──30行 → ~500 tokens ├──50行 → ~800 tokens ├──80行 → ~1200 tokens ├──120行 → ~1800 tokens ← 推荐上限 ├──200行 → ~3000 tokens ├──400行 → ~6000 tokens ← 已是负担 └──600 行 → ~9000 tokens ← 严重影响任务空间加上其他上下文开销总上下文预算构成Claude Sonnet, 200K tokens ├── 系统提示词内置 ~3K tokens ├── 用户级 CLAUDE.md ~800 tokens如果配置了 ├── 项目级 CLAUDE.md ~1500 tokens120 行 ├── Rules 文件按需加载 ~200-500 tokens匹配的文件 ├── Auto memory ~200-1000 tokens ├── 用户消息 ~1K tokens ├── 工具调用 结果 ~5K-50K tokens任务复杂度决定 ├── 历史对话 ~10K-100K tokens会话长度决定 └── 剩余可用于任务推理 → 越多越好关键洞察CLAUDE.md 从 30 行增长到 120 行Token 成本只从 500 增长到 1800还在可接受范围。但从 120 行增长到 400 行成本跳到 ~6000而增加的 280 行规则主要是一些低频场景的注意事项被模型遵循的概率反而下降了——因为规则太多模型无法在大量指令中维持对每一条的注意力。建议上限CLAUDE.md ≤ 120 行控制 Token 消耗在 2000 以内。超出的内容考虑拆到.claude/rules/或 Skill。这里有一个反直觉的发现Token 消耗的增长是线性的但规则遵循率的下降是指数级的。从 80 行增加到 120 行遵循率可能只从 88% 降到 82%但从 120 行增加到 200 行遵循率可能从 82% 骤降到 65%。原因是注意力稀释——模型面对 200 行指令时很难在前 80 行的架构规则和后 120 行的边缘场景注意事项之间合理分配注意力权重。结果往往是高频规则被正确遵循低频规则被完全忽略而中间地带比如测试要求处于不确定状态。这意味着 CLAUDE.md 优化的核心不是怎样塞更多规则而是怎样让最重要的规则最突出。实用的做法把最关键的 5-8 条规则放在 Rules 段落的前三行。模型对指令列表的开头部分注意力最高。质量度量怎么知道你的 CLAUDE.md 有没有用CLAUDE.md 不是写了就完了。它是一份运行中的工程规格需要度量效果。以下是四个可操作的指标|指标|定义|度量方法|目标值|| — | — | — | — ||遵循率|Claude Code 遵守规则、不需要额外提醒的会话比例|跑 10 个任务数一数需要手动纠正几次|≥ 80%||重复提问率|Claude Code 询问 CLAUDE.md 中已有答案的问题的比例|记录每次会话中的问题检查是否已在 CLAUDE.md 中|≤ 10%||越界率|Claude Code 违反明确声明的边界Safety 段落的比例|检查修改的文件是否触达 Safety 列表|≤ 5%||首次正确率|第一次生成就符合架构规则、不需要返工的代码比例|统计需要二次修改的原因区分需求不清和规则违反|≥ 70%|度量方法不需要复杂工具。连续用 Claude Code 完成一周的任务记录每次需要手动纠正的情况就能得到这些指标的粗略估计。更简单的方法让 Claude Code 在每个任务结束时输出一份简短的规则遵循自检——它认为自己遵循了哪些规则、违反了哪些规则、有哪些规则不确定怎么执行。虽然自检不完全可靠但它的不确定项通常指向 CLAUDE.md 里表述模糊的段落。诊断规则• 遵循率低 → 规则表述太模糊Claude Code 不知道怎么执行。改写为具体指令。• 重复提问率高 → CLAUDE.md 缺少关键信息。把被反复问到的问题补充进去。• 越界率高 → Safety 规则只在 CLAUDE.md 里没有被 Hooks 强制。把最关键的边界移到 Hooks。• 首次正确率低 → Architecture 描述不准确或不完整。让 Claude Code 复述架构看它理解了什么。CLAUDE.md vs Hooks边界决策CLAUDE.md 是建议层Hooks 是执行层。一条规则放在哪里取决于违反后果的严重程度。|规则类型|CLAUDE.md|Hooks|原因|| — | — | — | — ||编码风格用 Tailwind、用 zod|主要位置|不需要|违反后果低上下文提示足够||架构分层route 不写逻辑|主要位置|可选补充|违反后果中等CLAUDE.md 多数有效||文件保护不改 schema、不改 .env|列出文件|必须配合|违反后果高不能只靠模型自律||测试要求改代码后跑测试|描述期望|PostToolUse 提醒|双保险上下文提示 事件触发||命令权限不能跑 reset、drop|不需要|主要位置|后果严重且可枚举直接阻断||工作流步骤部署流程、发布检查|描述流程|不需要|流程性内容上下文足够|核心原则违反后果可接受的规则放 CLAUDE.md违反后果不可接受的规则必须用 Hooks 兜底。很多团队的现状是只在 CLAUDE.md 里写了不要改生产数据库但没有 Hooks 拦截。这在 90% 的情况下够用因为模型确实会遵守写在 Safety 段落里的规则。但那 10% 的失败场景——模型认为某个任务显然需要改数据库、绕过了 CLAUDE.md 的建议——造成的后果可能远超你愿意承受的范围。所以判断标准不是模型通常会遵守吗而是如果模型不遵守后果有多严重。严重到不可接受的必须加 Hooks。举个例子你在 CLAUDE.md 里写了不要改 .env 文件。大部分时候 Claude Code 会遵守。但偶尔它会认为某个任务必须修改 .env 才能完成然后就改了。如果你真的不能承受 .env 被修改的后果就在 Hooks 里加一个 PreToolUse 拦截{hooks:{PreToolUse:[{matcher:Write|Edit,command:bash -c #x27;echo\$TOOL_INPUT\| jq -r .file_path | grep -q\\\.env\ echo BLOCK: .env files are protected || true#x27;}]}}这样即使模型决定要改 .envHooks 也会在写入前拦截。CLAUDE.md 是提示Hooks 是保障。失败案例400 行的 CLAUDE.md这是一个真实的场景。一个 8 人团队在 monorepo 里维护前端Next.js、后端NestJS、共享组件库和数据库迁移四个 package。他们把所有规则都写进根目录的 CLAUDE.md大概 400 行包括• 前端组件规范只在改packages/ui/时有用• 后端 API 设计指南只在改apps/api/时有用• 数据库迁移流程只在改packages/db/时有用• 部署步骤只有发布时有用• Code Review 检查清单只有提 PR 时有用• 通用编码规范任何时候都有用问题出在两个层面Token 浪费400 行 CLAUDE.md 消耗约 6000 tokens。一个修前端按钮样式的任务不需要后端 API 设计指南、数据库迁移流程和部署步骤但这些内容全被加载了。规则遵守率下降更严重的问题是规则太多之后 Claude Code 的遵循率反而下降。测试数据40 行 CLAUDE.md 时遵循率约 85%400 行时降至约 60%。原因不是模型能力不够而是信号稀释——400 条指令里找到和当前任务相关的 20 条比 40 条里找到 20 条困难得多。模型在大量无关规则中无法维持对所有规则的注意力。修复方案修改前 根 CLAUDE.md400行所有规则混在一起 修改后 根 CLAUDE.md80行命令、全局架构、通用安全边界 ├── .claude/rules/frontend.md — 前端组件规范匹配 apps/web/**, packages/ui/** ├── .claude/rules/backend.md — 后端 API 设计指南匹配 apps/api/** ├── .claude/rules/database.md — 数据库迁移流程匹配 packages/db/** ├── .claude/rules/deploy.md — 部署步骤匹配 deploy/**, scripts/** └── Skill: code-review — Code Review 检查清单触发时加载修改后常规前端任务的上下文加载根 CLAUDE.md1200 tokens frontend rules400 tokens 1600 tokens。相比之前的 6000 tokens节省了 73%。遵循率回升到约 80%。教训CLAUDE.md 的价值不在于写了多少规则而在于当前任务相关的规则有多突出。规则越多不等于越好。精简、分层、按需加载才是正确策略。更深一层的教训是这个团队犯的错误不是写了太多规则而是没有对规则做优先级排序。400 行里的每一条单独看都是合理的但它们没有区分每次都需要和偶尔需要。当一个前端开发者让 Claude Code 改按钮颜色时它不应该被后端数据库迁移流程干扰。分层加载的本质是把谁在什么时候需要什么这个工程判断显性化。如果你正在评估自己团队的 CLAUDE.md 是否过长可以做一个简单测试随机选一个任务跑之前先问 Claude Code根据 CLAUDE.md这个任务需要注意哪些规则如果它列出了很多和你当前任务无关的规则说明 CLAUDE.md 需要拆分。落地检查清单按顺序执行• [ ]CLAUDE.md≤ 120 行。如果超过把路径特定的规则拆到.claude/rules/见第 05 篇• [ ] 包含五个核心段落Commands、Architecture、Rules、Safety、Testing• [ ] Commands 段落覆盖安装、开发、测试、类型检查、lint• [ ] Architecture 段落用一句话描述每个关键目录的职责和限制• [ ] Rules 段落用 MUST NOT / MUST 做明确约束不用应该“尽量”• [ ] Safety 段落列出所有不能碰的文件和不能跑的命令• [ ] Testing 段落明确什么操作触发什么测试附上单文件测试命令• [ ] 让 Claude Code 复述项目结构确认准确验证 Architecture 段落是否有效• [ ] 跑三个任务统计重复提问率和越界率• [ ] Safety 里的关键规则已用 Hooks 兜底见第 22 篇• [ ] 没有 README 级别的背景描述——项目介绍、团队愿景、技术选型理由不属于 CLAUDE.md交叉引用•第 05 篇rules路径特定规则的写法和组织方式CLAUDE.md 超长时的拆分目标位置•第 22 篇hooks确定性控制层Safety 规则的强制执行机制CLAUDE.md 建议的兜底保障•第 00 篇运行时模型四层架构中的记忆层定位CLAUDE.md 在上下文预算中的具体位置和压缩行为一个实际的工作流把以上内容串起来一个团队从零开始配置 CLAUDE.md 的推荐流程第一步让 Claude Code 自助生成草稿。在一个已有项目里运行阅读仓库结构生成一份 CLAUDE.md 草稿包含 Commands、Architecture、Rules、Safety、Testing 五个段落。它会基于实际代码给出一个合理的起点。第二步人工审查和修正。Claude Code 生成的草稿通常在 Commands 和 Architecture 上比较准确因为它真的读了代码但在 Rules 和 Safety 上往往遗漏团队的隐性约定。把那些所有人都知道但没人写下来的规则补进去。第三步验证。跑三个不同类型的任务修 bug、加功能、重构观察 Claude Code 是否遵循规则。如果它反复违反某条规则不是它不听话是那条规则表述不够具体。改写后重新验证。第四步度量。一周后检查遵循率、重复提问率、越界率。如果越界率超过 5%把对应的 Safety 规则加到 Hooks。第五步迭代。项目在演进CLAUDE.md 也要跟着更新。每次新增一个重要目录、变更测试框架、或者修改部署流程时同步更新对应的段落。