CLAUDE.md 越写越长，用三个问题把规则拆开

项目根目录的 CLAUDE.md，一开始只有几行，用着用着越写越长：全局命令、服务层规则、完整的发布流程，还有上周某次测试失败留下的临时经验，全堆在里面。

结果是，哪怕只改一个页面，Claude Code 每次也要读一遍和这个任务无关的内容；更麻烦的是，有些写进去的“规定”只是文字，并没有真正拦住什么。

整理的难点在于，这些内容都真实有用，舍不得删，又说不准该放到哪里。放错了，要么该加载的规则没有加载，要么该保留的约束在拆分中悄悄丢了，文件变短了，反而更不可靠。

好用的办法，是动手之前先对每一条内容问三个问题：

• 它对哪些任务或路径成立？
• 它是事实、规则还是一套多步骤的方法？
• 它要靠模型理解，还是必须由程序执行？

答案不同，去处就不同：根文件、带路径条件的 rules、auto memory、Skill 和 Hook 各有分工。

开头那五条混在一起的内容，正好拿来逐条归位；paths 怎样按需加载，空泛的规则怎样改成能执行的，整理完怎样用三个场景检验，也顺着这个例子说清楚。

01 分层前先问三个问题

这三问可以帮助我们判断同一主题需要哪些层次。例如“提交前确认验证状态”是一条协作规则；怎么收集状态是流程；实际阻断某个违规提交是门禁。分层时分别写清这三种职责，避免重复复制同一段话。

02 根 CLAUDE.md 放什么

CLAUDE.md 是提供给 Claude Code 的项目说明与协作约定。根文件适合写每次会话都应成立、对行动有实质影响的信息：

• 常用 build、test、lint、dev 命令；
• 关键目录和全局架构边界；
• 代码风格、命名约定和明确禁止事项；
• 不明显却常影响执行的环境要求；
• 修改后与提交前的验证原则；
• 压缩时保留哪些状态的 Compact Instructions。

详细 API 手册、长篇业务背景和低频迁移记录通常可保留读取入口，按需查阅。逐条检查：删去或后置这条信息，是否会让日常任务失去必要方向？需要时再读的资料可以保留入口；后果严重的全局限制，即使低频也应保留。第一次写根文件可以先看新手如何给 Claude Code 定规则。

删减以必要性为准，行数只作参考。能从代码直接确认的信息可简写，难以发现的环境条件和跨模块边界则应明确说明。

文字规则通过上下文影响行为，属于说明层面的约定。把禁止修改敏感文件的要求写在这里，能说明协作边界；要落实访问限制，还需权限或其他覆盖相应动作的控制。

03 把规则写成可执行的样子

规则需要指向可观察的行为。例如：

请写高质量代码。

“高质量”缺少本项目的判断依据。可以改成具体的依赖约束：

修改 `server/` 或 `domain/` 时，必须保持依赖方向：API -> 服务 -> 端口 <- 适配器。`domain/` 不得 import `adapters/`。

修改范围和禁止的依赖方向明确后，可以通过导入检查核对是否违反规则。检查 TypeScript 语法树（AST）也能识别相应导入；重点是让规则有可观察的判断依据。

同样，把：

注意测试。

改为：

修改课程 schema 后，运行项目规定的课程校验命令，并执行覆盖受影响字段的 schema 测试。

便明确了触发条件与动作；落到实际仓库时，仍需补上已核实的命令与测试入口，只写“运行相关测试”仍可能让执行者选错范围。

反复纠正同一种错误，说明可能值得固化；先确定作用范围，再决定写入根说明还是局部规则。项目变化后也要重新核对：旧命令删除后，规则写得再强硬也跑不起来。

04 用 paths 按需加载规则

.claude/rules/ 把说明拆成主题文件；paths 决定一条规则是否按文件路径加载。文件移入这个目录后，是否按需加载取决于 paths：按官方 Memory 文档，未配置 paths 的规则会在会话开始时加载。

例如，下面的结构先按主题整理文件，方便维护：

CLAUDE.md
  全项目长期协作契约

.claude/rules/server.md
  服务层代码边界

.claude/rules/course.md
  课程文件规则

.claude/rules/frontend.md
  前端组件和样式规则

要让服务规则只在相关路径出现时加载，还需在 server.md 顶部加入 YAML 条件。下面是一个完整的小示例：

---
paths:
  - "server/**/*.ts"
  - "domain/**/*.ts"
---

# Service and Domain Rules

- Keep domain logic independent of adapters.
- Do not import adapters from domain files.

这里的路径模式选择 server/ 和 domain/ 中的 TypeScript 文件。Claude 读取匹配文件时会加载规则；按路径加载只提供说明，工具调用的门禁需另行配置。目录改名或扩展名变了，模式也要跟着更新。

迁移后，在匹配和不匹配路径的会话中核对实际加载，并结合 /context 与读取记录检查。占用降低只说明少加载了东西，条件是否正确还要看：应加载的规则能到达，无关细节不再持续出现。

05 区分经验与正式规则

auto memory 用来保存工作中积累的偏好与经验，例如某类本地测试需要 Redis，或用户偏好先看方案。

经验带有环境和时间条件，核对之后才适合成为项目政策。本机测试因 Redis 未启动而失败，只支持这次观察；确认它是团队共同依赖后，再写入正式测试规范。固化前应核对适用范围和当前有效性。

记忆进入上下文后仍要靠模型解释执行，和 CLAUDE.md 一样只是说明，强制执行要靠相应控制。需要固化时，确认谁受约束、在哪些条件下有效，再提升为相应规则；同一经验只保留一个版本，位置统一。敏感账号或环境信息只记录获准且必要的部分，凭据不属于经验说明。

06 为压缩保留关键状态

长会话中的口头约定可能在摘要中丢失。Compact Instructions 是写在 CLAUDE.md 中的压缩指导，帮助模型决定哪些内容优先保留；它只是指导，具体保留什么仍由模型取舍。

## Compact Instructions

Preserve in priority order:

1. Architecture decisions and reasons.
2. Modified files and key changes.
3. Current verification status.
4. Open risks, TODOs, and rollback notes.
5. Verification commands, exit states, key errors, unrun checks, and full log locations.

这个顺序优先保留决定与原因，因为丢失原因容易重复已排除方案；保留改动与验证状态，因为接手者需要知道什么已做、什么未证实；保留风险、下一步与回滚说明，因为它们决定如何继续和恢复。

工具结果可以保留结论、退出状态、关键错误和原始日志位置。把几千行测试输出缩成“测试通过”之前，要确认究竟哪些测试通过，哪些没运行；否则压缩会把局部证据夸大成整体结论。

“保留重要内容”缺少选择标准，按任务列出状态更可用。涉及重要决定、失败尝试或复杂回滚时，还可以先写可审查的 HANDOFF.md，具体写法见越聊越乱，该清空、压缩还是交接。

07 规则、流程与门禁如何配合

一条常驻规则可以是：

提交前必须确认测试和 lint 状态。

它规定提交前应满足什么协作要求。发布检查 Skill 组织取得证据的方法，例如检查分支、测试、版本和变更日志，区分通过、失败、未运行与阻塞；检查结束后，提交或发布仍需另行授权。

Hook 则在实际覆盖的事件上执行具体动作，例如在工具调用前检查受保护操作，或在编辑后运行 formatter。三者各自说明负责的部分，并引用共同流程。

落实这些示意要求时，要选对事件和检查对象。比如通过 PreToolUse 检查 Claude Code 即将调用的提交命令，覆盖的只是这一条路径；要求所有提交路径都执行，就用覆盖该范围的 Git 或 CI 检查。文件编辑后的 formatter 已是事后处理。

这样三层各就各位：规则说明长期要求，Skill 收集并解释证据，Hook 在覆盖的事件上执行程序动作。三者可以引用同一检查脚本或约定，避免各自复制一套逐渐偏离的标准。

08 回到开头那五条

逐条判断时，先说明使用条件，再决定放置位置：

第四条是上周的经验，先核对当前测试是否仍依赖 Redis，以及适用于哪个环境，再决定怎么保留。信息性质随事实确认而变化，放置位置也可能随之调整。

迁移前先保留原要求的含义，迁移后再清除旧位置中的重复正文。其他位置可以留下读取入口，但不各自维护另一套略有差异的标准。例如根文件规定提交前必须核对验证状态，Skill 只描述怎么收集状态，Hook 只执行它负责的检查；三者共用同一个“通过”的定义。

还要防止按路径加载遗漏任务触发场景。假如用户要求发布前检查，但全过程没有读取某个源码目录，那个目录的 paths 规则可能始终没有机会加载。此时应让发布 Skill 或全局入口明确指向所需规范。文件匹配解决文件场景，任务入口解决“要做哪类工作”的场景。

09 用三个场景验收迁移

整理完成后，可以对照三种场景核对：

1. 普通页面改动。查看全局协作原则是否可见，是否加载了不需要的服务层专用细节。
2. 读取 domain 文件。确认路径规则能够加载，并检查禁止导入的表述是否完整。
3. 启动发布检查。确认流程入口能取得验证要求，不依赖恰好读到某个目录。

这些场景核对的是规则可达性和任务适用性。规则加载之后，还要检查动作是否遵循要求；Markdown 说明本身只是说明，访问控制要另行配置。

如果目录从 domain/ 改成了 src/domain/，规则正文可能完全正确，只是路径条件过期，规则没机会加载。此时修复加载条件即可。如果根文件要求“测试通过才能发布”，局部说明却允许忽略测试失败，问题则是含义冲突，哪条有效由人来定。

迁移是否成功，要看必要约束是否保留、相关任务能否取得要求，以及重复标准是否收束。文件变短是结果之一，迁移是否成功要看这三项检查。