CLAUDE.md 是建议性的，不是强制性的——Claude 会"尽量遵守"，但不是每次都完美执行。理解这个前提，才能写出真正有效的 CLAUDE.md，而不是写了一堆规则 Claude 却视而不见。本文结合官方 Best Practices 和社区实践，给出 10 个可以立即改善遵从度的建议。
为什么 Claude 有时"忽视" CLAUDE.md？
首先澄清两个误解：
误解 1：Token 太多了所以没读到 事实：100 行 CLAUDE.md ≈ 500-2000 Token，Claude Code 有 200K 上下文窗口，Token 不是问题。
误解 2：规则需要更强调，多写几遍 事实：重复本身没用，问题在于规则的质量，而不是数量。
真实原因：
研究表明，LLM 可以可靠遵循约 150-200 条独立指令。Claude Code 内置系统 Prompt 已占用约 50 条配额，你的有效预算约为 100-150 条。超过这个数量，不是 Token 溢出，而是注意力降级——Claude 在众多规则里"忘记"了一些。
另外，Claude Code 系统 Prompt 明确说 CLAUDE.md 内容"可能相关，也可能不相关"，Claude 有权根据任务判断哪些规则适用。这是设计行为，不是 Bug。
10 个最佳实践
1. 只写 Claude 不能自己推断的内容
最常见的浪费：写 Claude 读代码就能知道的事。
# ❌ 写了也没用（Claude 能从代码结构推断）
- 这是一个 TypeScript 项目
- 我们使用 React 进行前端开发
- 代码在 src/ 目录里
# ✅ 真正有价值（Claude 无法从代码猜到）
- 构建命令：npm run build（不是 npm build）
- 测试需要在 CI 环境变量下运行：MOCK_PAYMENTS=true npm test
- 不要修改 src/legacy/ 目录（外部团队维护，有单独 Review 流程）测试方法：让一个新同事看代码，他能自然发现的事，不用写；他要问你的事，写进去。
2. 具体到可以验证
# ❌ 模糊（Claude 不知道怎么执行）
- 写好测试
- 保持代码整洁
- 遵循最佳实践
# ✅ 具体（可以验证是否执行了）
- 每个新函数必须有对应的单元测试，测试文件放在 __tests__/ 同名目录
- 函数长度不超过 40 行；超过则拆分
- 使用 `npm run lint` 检查代码，确保 0 错误原则：如果你无法判断 Claude 是否"执行"了这条规则，那这条规则太模糊。
3. 把常用命令写进去
# ✅ 构建和测试命令（这类信息价值很高）
## 常用命令
- 开发服务器：`npm run dev`（端口 3000）
- 测试：`npm test`（需要 `.env.test` 文件）
- 全量测试含覆盖率：`npm run test:coverage`
- 类型检查：`npx tsc --noEmit`
- Lint：`npm run lint`
- 构建：`npm run build`
- 数据库迁移：`npx prisma migrate dev`
- 数据库重置：`npx prisma migrate reset`Claude Code 首次进入项目时不知道你的命令结构。与其每次会话都重新告诉它，不如一次写进 CLAUDE.md。
4. 控制文件长度在 200 行以内
长 CLAUDE.md 的问题不是 Token，是遵从度下降：
规则数量 vs 遵从率（经验估算）：
50 条规则 → ~95% 遵从
100 条规则 → ~85% 遵从
200 条规则 → ~70% 遵从
400 条规则 → ~50% 遵从（实际上和没有差不多）
解决方案：
对每条规则问："去掉这条，Claude 会犯什么具体的错？"
- 能说出具体错误 → 保留
- 说不上来 → 删掉
- 规则很重要但很长 → 用
.claude/rules/路径限定，只在相关文件上加载
5. 用路径限定规则（.claude/rules/）
不需要在所有文件上生效的规则，不要放在主 CLAUDE.md 里：
.claude/
└── rules/
├── testing.md # 测试规范（无 paths，全局）
├── code-style.md # 代码风格（无 paths，全局）
├── api-security.md # API 安全（paths: src/api/**）
├── react-patterns.md # React 规范（paths: src/components/**/*.tsx）
└── sql-safety.md # SQL 安全（paths: **/*repository*.ts）
---
paths:
- "src/api/**/*.ts"
---
# API 开发规范
- 所有请求体必须用 Zod Schema 验证
- 禁止在 SQL 查询里拼接用户输入（必须用参数化查询）
- 返回 4xx 错误时，记录 warn 级别日志这个规范只在 Claude 读取 src/api/ 下的 TypeScript 文件时加载，不占用处理前端代码时的上下文空间。
6. 分清 CLAUDE.md、Hooks 和 Skills 的职责
三者分工清晰，不要混淆：
# 把以下内容放哪里？
"每次修改 .ts 文件后自动运行 ESLint"
→ Hooks（PostToolUse），不是 CLAUDE.md
原因：这是"每次都必须发生"的操作，用确定性的 Hook
"代码风格要遵循 Airbnb 规范"
→ CLAUDE.md，然后 ESLint 用 Hooks 强制检查
原因：风格是建议性的，ESLint 是强制性的
"如何部署到 staging 环境"
→ Skills（/deploy-staging），不是 CLAUDE.md
原因：这是一个步骤化流程，不是常驻规则CLAUDE.md 里有 Hooks 已经处理的规则 = 发出矛盾信号：
Claude 认为"我应该运行 ESLint"（CLAUDE.md 说的），Hook 已经自动运行了 ESLint，Claude 又手动运行一次。有时 Claude 会问"ESLint 已经通过了（Hook 运行的），我还需要再运行吗？"——这种混乱来自规则重复。
7. 利用 CLAUDE.local.md 放个人专属配置
# CLAUDE.local.md（加入 .gitignore，不提交）
## 我的本地环境
- 数据库：postgresql://localhost:5432/myapp_dev
- Redis：redis://localhost:6379
- 本地 Stripe 测试密钥：sk_test_...（实际上不要把密钥放进文件！）
- 跳过需要 Stripe 的测试（本地没有真实密钥）
## 调试偏好
- 遇到问题先看 src/utils/logger.ts 里的日志
- 本地环境的测试账户：admin@local.dev / test1234
## 我正在处理的功能
- 当前分支：feature/search-v2
- 相关文档：docs/search-architecture.md（正在更新）团队成员共享 CLAUDE.md，你的个人专属环境信息放 CLAUDE.local.md，互不干扰。
8. 在重要规则前加触发词
有些规则要在特定情况才生效，明确触发条件：
# ❌ 无条件规则（Claude 可能每次都遵守，哪怕不必要）
- 使用错误边界包裹组件
# ✅ 有条件规则（只在相关时才生效）
- 创建新的 React 页面组件时，必须用 ErrorBoundary 包裹
- 修改 src/api/ 时，务必检查是否需要更新 openapi.yaml
- 提交数据库变更时，确认 prisma/migrations/ 已更新9. 用 @import 拆分大文档
# CLAUDE.md（保持精简，作为索引）
# 项目概述
我们是一个 B2B SaaS 平台。主要模块见下方链接。
## 详细规范（按需查看）
- 代码规范：@.claude/docs/code-standards.md
- 数据库约定：@.claude/docs/database-conventions.md
- API 设计规范：@.claude/docs/api-design.md
- 测试策略：@.claude/docs/testing-strategy.md
## 常用命令
（少量最重要的命令...）
## 关键约定
（最重要的 10-15 条规则...）注意：@import 的文件在启动时内联展开，不是懒加载。如果导入的文件总 Token 量很大，还是要控制。用 .claude/rules/ 的路径限定规则才是真正的懒加载。
10. 定期维护：删除过时规则
CLAUDE.md 容易只增不减。设置一个定期审查节奏（比如每个 Sprint 末）：
审查问题：
- 这条规则现在还有效吗？（技术栈变了吗？）
- 我们真的还在执行这个约定吗？
- 有没有新的规则需要加进来？（Claude 在上周犯了什么新错误？）
# CLAUDE.md 文件头部（可选）
<!--
最后审查：2026-05-13 | 下次审查：2026-06-13
维护人：@your-github-username
行数：87 / 200 目标
-->这个注释在 CLAUDE.md 里不会被 Claude 读取（HTML 注释会被 Claude Code 过滤），但帮助人类维护者知道什么时候该审查。
快速检查清单
写完 CLAUDE.md 后，用这个清单验证：
- 每条规则：删掉它，Claude 会犯什么具体的错？（说不出来就删）
- 总行数 < 200 行
- 构建/测试/Lint 命令是否写了？
- 有没有把 Hooks 应该做的事写进来？（重复了就删 CLAUDE.md 里的）
- 有没有把 Skills 应该做的流程写进来？（移到 Skills）
- 个人专属配置（本地数据库、测试账户）是否在
CLAUDE.local.md而不是CLAUDE.md？ - Monorepo 场景：子包是否有各自的 CLAUDE.md？
- 有没有 6 个月以上没更新的规则？
来源：Claude Code 官方文档 - Memory | morphllm - CLAUDE.md Best Practices | Claude Code Best Practices | 整理：ClaudeEagle