3.1　以合适的层级、作用域和模块结构配置 CLAUDE.md

这一条考什么

考你是否理解 CLAUDE.md 的层级（用户级、项目级、目录级）以及哪一层会通过版本控制共享给团队；能否用 @import 把标准文件模块化地引入各个包的 CLAUDE.md，用 .claude/rules/ 把一个臃肿的 CLAUDE.md 拆成主题文件；以及在行为不一致时用 /memory 排查到底加载了哪些记忆文件。

核心概念

三个层级

Claude Code 启动时会把 CLAUDE.md 当作“记忆”加载进上下文，来源分层：

• 用户级：~/.claude/CLAUDE.md。只对你本人生效，跨所有项目。适合个人偏好（如“回复用中文”“我习惯 pnpm”）。它不在仓库里，不会通过版本控制分享给同事。
• 项目级：仓库根目录的 CLAUDE.md 或 .claude/CLAUDE.md。提交到 Git，所有团队成员共享。适合团队规范：构建命令、架构说明、编码约定、测试标准。
• 目录级：子目录中的 CLAUDE.md（如 packages/billing/CLAUDE.md）。当 Claude 在该目录下读取或编辑文件时按需加载，适合只对某个包生效的约定。

Claude Code 还会从当前工作目录向上逐级查找 CLAUDE.md。层级越具体，越贴近当前工作，多个层级的内容会一起进入上下文。

最常考的诊断：指示放错了层级

典型场景：老成员用起来一切正常，新成员加入后 Claude 不遵守团队规范。原因往往是规范写在了老成员自己的 ~/.claude/CLAUDE.md 里，从未进入仓库。修复：把团队规范移到项目级 CLAUDE.md（或 .claude/rules/）并提交，个人偏好留在用户级。

@import：模块化引用

CLAUDE.md 中可以用 @路径 引入其他文件，相对路径相对于当前 CLAUDE.md 所在位置解析，也支持 @~/... 的家目录路径。被引入的文件还能继续 import（有最大递归深度限制）。代码块和行内代码中的 @ 不会被当作 import。

# packages/payments/CLAUDE.md

本包处理支付与退款，所有金额以分（整数）存储。

@../../docs/standards/error-handling.md
@../../docs/standards/pci-logging.md
@../../docs/standards/api-conventions.md

# packages/web-ui/CLAUDE.md

@../../docs/standards/accessibility.md
@../../docs/standards/react-components.md

关键点是有选择地引入：熟悉各包的维护者根据领域知识决定每个包需要哪些标准。支付包需要 PCI 日志规范，前端包需要无障碍规范，彼此不必加载对方的内容，既节省 token 也减少无关指令的干扰。

.claude/rules/：按主题拆分

当根目录 CLAUDE.md 膨胀到几百行、什么都往里塞时，可以拆到 .claude/rules/ 目录下的多个 Markdown 文件：

.claude/
  rules/
    testing.md
    api-conventions.md
    deployment.md
    security.md
CLAUDE.md          # 只保留项目概览和最核心的命令

每个文件只讲一个主题，便于维护、审查和定位“哪条规则导致了这个行为”。没有 paths 前置信息的规则文件会像项目 CLAUDE.md 一样在启动时加载；带 paths 的则按文件路径条件加载（见 3.3）。

/memory：排查加载了什么

在会话中运行 /memory，可以看到当前会话加载了哪些记忆文件（用户级、项目级、目录级、规则文件等），并可直接打开编辑。当出现“同一个仓库，两个人得到的行为不一样”或“Claude 好像没看到某条规范”时，先用 /memory 确认：

• 这条规范所在的文件是否真的被加载了？
• 是否存在用户级文件里与项目规范冲突的指令？
• 目录级 CLAUDE.md 是否因为当前工作不在该目录而尚未加载？

正确做法与反模式

• 正确：团队规范放项目级 CLAUDE.md 或 .claude/rules/ 并提交；个人偏好放 ~/.claude/CLAUDE.md。反模式：把团队约定写在自己的用户级文件里，再奇怪“新人为什么收不到”。
• 正确：各包的 CLAUDE.md 用 @import 只引入与本包相关的标准文件。反模式：把所有标准全文复制进每个包，或在根 CLAUDE.md 里一次性 import 全部标准。
• 正确：把巨型 CLAUDE.md 拆成 testing.md、api-conventions.md、deployment.md 等主题文件。反模式：持续往一个文件里追加，直到没人能维护。
• 正确：行为不一致时先用 /memory 检查加载的文件。反模式：直接在提示里加“IMPORTANT/MUST”等加强语气，而不排查配置层级。

常见陷阱

• “让新成员自己在 ~/.claude/CLAUDE.md 里配置一遍”：能用但不可维护、不同步，正确答案是放进版本控制的项目级配置。
• 把目录级 CLAUDE.md 当作全局生效：子目录的 CLAUDE.md 是按需加载的，Claude 没碰那个目录时它可能不在上下文中。
• 用更强硬的措辞替代结构修复：题干说“规则时有时无”时，选项里“改成全大写 MUST”是干扰项；先查层级和加载情况。
• 混淆 CLAUDE.md 与硬性约束：CLAUDE.md 是指导性上下文，不是强制机制。题目要求“绝不允许编辑某目录”时，应该用 settings 里的 permissions.deny 或 hooks，而不是只写进 CLAUDE.md。
• 一次性任务也写进 CLAUDE.md：只为某次任务参考几个模块，直接在提示里用 @文件 引用即可，不必把它们升级成永久的项目约定。

实操练习

目标：亲手复现“指示放错层级”的问题，并用 /memory 诊断、用 @import 和 .claude/rules/ 修复。

1. 在 ~/.claude/CLAUDE.md 写一条“所有 API 返回 snake_case 字段”，模拟老成员的私有配置。
2. 在仓库中新建一个分支，切换到另一个用户（或临时重命名 ~/.claude/CLAUDE.md）模拟新成员，启动 Claude Code 让它写一个 API handler，观察字段命名。
3. 运行 /memory，确认该规则不在新成员的加载列表中。
4. 把规则移动到 .claude/rules/api-conventions.md 并提交；为 packages/payments/CLAUDE.md 添加 @import。
5. 重新启动会话，用 /memory 确认加载列表，并再次生成 handler。

mkdir -p .claude/rules docs/standards packages/payments
cat > .claude/rules/api-conventions.md <<'EOF'
# API 约定
- 所有 JSON 响应字段使用 snake_case
- 错误响应统一为 {"error": {"code": "...", "message": "..."}}
EOF

cat > docs/standards/pci-logging.md <<'EOF'
# PCI 日志规范
- 禁止记录完整卡号，只记录后四位
EOF

cat > packages/payments/CLAUDE.md <<'EOF'
本包处理支付，金额一律用整数分。
@../../docs/standards/pci-logging.md
EOF

claude    # 进入后运行 /memory 查看加载的文件

检查结果：/memory 中能看到项目规则文件；在 packages/payments 下工作时，Claude 生成的日志代码只打印卡号后四位。

自测清单

• 用户级、项目级、目录级 CLAUDE.md 分别在哪里？哪一层会通过 Git 分享给同事？
• 新同事反映 Claude 不遵守团队规范，你会先检查什么？如何修复？
• @import 的路径如何解析？为什么要按包“有选择地”引入标准文件？
• 什么时候应把 CLAUDE.md 拆分到 .claude/rules/？拆分后的好处有哪些？
• /memory 能帮你回答哪些排查问题？