CLAUDE.md 编写六大铁律：让 AI 真正成为守规矩的开发队友
你精心撰写了 CLAUDE.md 并放在项目根目录，甚至花了一下午整理完整的团队编码规范，但 Claude 生成的代码依然错误百出。这种感觉就像把一本厚厚的员工手册塞给新同事，人家翻了第一页就扔到了一边。
问题的根源不在于你 "有没有写"，而在于你 "怎么写"。到 2026 年，CLAUDE.md 已经和.gitignore 一样，成为项目的基础设施级文件。但社区中四分之三的开发者都没有意识到：Claude 不遵守你的规则，不是因为它不想听，而是你的文件写法本身，不满足 "能被 AI 正常读取、解析和遵循" 的格式与密度要求。
铁律①：严格控制在 200 行以内（官方明确要求）
Anthropic 官方文档明确指出："每个 CLAUDE.md 文件的目标长度控制在 200 行以内。更长的文件会消耗更多上下文，降低规则遵循率。"
CLAUDE.md 会在每个会话开始时作为上下文注入加载。它不是有硬校验的配置文件，每多一行都会消耗上下文窗口的信号密度。文件越长、规则越多越密集，Claude 对底部规则的遵循率就会呈可测量的下降趋势 —— 这不是 token 溢出导致的，而是有效信号被淹没在了噪声里。
表格
| 常见表现 | 本质原因 |
|---|---|
| Claude 反复违反你明明写过的规则 | 规则过于分散、文件太长、矛盾指令互相抵消 |
| Claude 问的问题答案就在 CLAUDE.md 里 | 关键信息埋在段落中，没有被结构化扫描到 |
| 修改了 CLAUDE.md 但 Claude 像没看见 | 可能是没有开启新会话或执行 /compact 重载，但更常见的是内容写得不可验证 |
解决方案：项目复杂就拆分规则。使用.claude/rules/目录做路径限定加载（只在操作匹配的文件时才加载对应规则），或用@path/to/file.md引用机制把长内容拆出去。需要注意的是，引用进来的内容仍然会在会话启动时进入上下文，因此这不是 "省 token 的魔法"，而是 "提升组织可读性的工程手段"。
铁律②：只写 Claude 猜不到的内容
官方给出的筛选标准非常明确："打造一个简短且信号密集的文件。" 只有那些 Claude 每次会话都必须知道、且无法从代码本身推断出来的事实，才值得写进 CLAUDE.md。
表格
| ✅ 值得写入（有效信号） | ❌ 不值得写入（无效噪声） |
|---|---|
| 构建、测试、代码检查的确切命令（用 pnpm 不用 npm，用 vitest 不用 jest） | 标准语言语法规范（TypeScript 如何导入，Claude 本身就知道） |
| 非默认的项目约定（API 处理器放在 src/api/handlers/，不用 Redux 用 Zustand） | 长篇 API 文档（Claude 能直接读代码，让它自己去读） |
| 三句话讲清架构（核心组件 + 通信方式） | "写整洁的代码"" 高内聚低耦合 " 这类空话，无法验证 |
| 硬约束和禁区（永远不要写入 config / 目录，不要编辑自动生成的文件） | 逐文件描述功能（"user.ts 负责用户管理"——Claude 读完文件自然就知道） |
| 每个新人都会踩的已知坑 | 更新日志和团队路标（过期的信息比没有更糟） |
黄金检验标准：对每一行内容问自己："如果我把这行删掉，Claude 会不会因此做错事？" 如果不会，就果断删掉。
请记住：CLAUDE.md 不是 README，更不是 GitHub Wiki。它是给 AI 的入职简报，不是给人看的展示页面。
铁律③：规则必须像断言一样 —— 可验证、不模糊
❌ 错误示例："命名要有意义"、"错误处理要健壮"
✅ 正确示例："API 方法文件名必须以.api.ts 为后缀"、"所有 fetch 调用必须包含 try/catch，并返回 {success, data, error} 格式"官方原文强调："具体、简洁、结构良好的指令效果最好"。一条好的规则必须满足三个条件：
- 可验证：Claude 写完代码后，能够自己判断是否符合规则
- 具体：不使用形容词（"优雅"" 干净 "），而是明确模式（2 空格缩进、Api 后缀、src/api/handlers/ 目录）
- 一事一议：一条规则只解决一件事，不写包含多个要求的大道理段落
铁律④：路径描述含糊等于没写
这是 Monorepo 场景下最致命的问题。你在根目录 CLAUDE.md 中写了全局规则，但 frontend / 和 api / 目录有不同的约定。如果不使用路径限定，Claude 进入子目录时可能只会遵循根规则，模块级的特殊要求会直接失效。
官方给出的解决方案不是 "把更多内容塞进根文件"，而是两层加载机制：
- 子目录 CLAUDE.md（如 frontend/CLAUDE.md）：当 Claude 读取该子目录的文件时按需加载，而不是在会话一开始就全部加载
- .claude/rules/ + 路径前缀：规则按 glob 模式匹配，只在操作匹配文件时加载，大幅节省上下文
示例目录结构：
plaintext
.claude/rules/
├── testing.md
└── frontend-react.md
frontend-react.md 文件开头：
yaml
paths:
- "frontend/**/*.{tsx,jsx}"
路径歧义的后果就是：你明明设置了规则，但 Claude 一进入深层子模块就会 "选择性失忆"。
铁律⑤：分层存放，别让个人习惯污染项目文件
CLAUDE.md 有三层加载体系，从通用到具体依次生效：
表格
| 层级 | 文件位置 | 存放内容 | 是否提交到 Git |
|---|---|---|---|
| 全局个人 | ~/.claude/CLAUDE.md | 你的个人偏好（"我用 pnpm"、"用中文回复"） | ❌ 不绑定项目 |
| 项目级核心 | <仓库根目录>/CLAUDE.md | 架构、约定、命令、禁区 | ✅ 必须提交 |
| 项目级私有 | <仓库根目录>/CLAUDE.local.md | 你在本项目的个人实验偏好 | ❌ 加入.gitignore |
| 子目录级 | <子目录>/CLAUDE.md | 模块特定规则（按需加载） | ✅ 按需提交 |
Monorepo 特别提醒：如果根目录写了 "必须使用 jest"，而子包 package-a/CLAUDE.md 写了 "必须使用 vitest"，两条冲突规则会让 Claude 随机选择一个，或者表面遵从而实际混用。解决方案是：统一的测试框架决策写在根目录，差异部分写在子目录的.claude/rules/ 中并使用路径限定。
铁律⑥：每次 Claude 犯错，就把教训写进 CLAUDE.md（形成闭环）
这才是 CLAUDE.md 从 "死文档" 变成 "活的团队经验库" 的关键。
官方支持两种便捷的更新方式：
- 在会话中直接按 #键（或以 #开头输入），Claude 会询问你要追加到哪个 CLAUDE.md 文件，并自动补全格式
- 直接说："记住这个规则：____" 或 "把这条添加到 CLAUDE.md"，Claude 会自己整理措辞写入
每次 AI 犯错→你纠正→一条可验证规则入库→下次同一个错误绝不会再犯。这正是 Anthropic 所倡导的："把它当作一份活的入职文档，而不是一份静态的规范说明书。"
官方推荐：干净的项目根 CLAUDE.md 模板
markdown
## 技术栈
- Node 20 / TypeScript / Express
- pnpm (禁止使用npm)
## 常用命令
- 开发: `pnpm dev`
- 测试: `pnpm test`
- 构建: `pnpm build`
## 项目结构
- `src/api/handlers/` — API路由处理器
- `src/models/` — 数据库模型
- `src/config/` — **禁止手动编辑（自动生成/由环境变量驱动）**
## 硬性规则（CLAUDE必须严格遵守）
1. ❌ 永远不要直接修改`src/config/`或`prisma/schema.prisma`文件
2. ✅ 所有新的API处理器必须放在`src/api/handlers/`目录，文件后缀为`.handler.ts`
3. ✅ 所有API响应必须遵循格式：`{ success: boolean, data?: unknown, error?: string }`
4. ✅ 在建议提交前必须运行`pnpm test`
## 已知坑点
- `pnpm prune`会删除`node_modules/.cache/`目录，执行后必须重新运行`pnpm install`
- 预发布环境读取带`STAGING_`前缀的环境变量，而非`PROD_`前缀
## 扩展规则（按需加载）
- 前端开发规范 → @.claude/rules/frontend.md
- 测试策略 → @.claude/rules/testing.md
结语
CLAUDE.md 的价值不在于它有多厚，而在于每一行的 "信号密度"。简短、具体、可验证、持续更新 —— 这四个条件同时满足，Claude 才会真正像一个 "读过员工手册且严格照做" 的可靠队友。
对于需要大规模、稳定使用多模型 AI 服务的开发者和企业来说，UseAIAPI提供了一站式的接入解决方案。平台聚合了 Claude、ChatGPT、Gemini、DeepSeek 等全球主流前沿 AI 大模型，提供稳定可靠的企业级定制化服务，无需复杂配置即可快速接入使用。平台推出了极具竞争力的优惠政策，全线服务最低可享官方定价 5 折，大幅降低了高强度开发和内容生产场景下的使用成本，让更多用户能够以更低的门槛享受到先进 AI 技术带来的效率提升。