前后端使用不同测试命令的仓库，适合把共同约定留在根目录，把模块要求写成路径规则。根目录说明每次都需要知道的事实，paths 规则说明处理某类文件时才需要的要求。

先列出规则的作用范围

假设项目包含 src/api/ 和 src/ui/。可以采用以下结构：

repo/
  CLAUDE.md
  .claude/rules/
    api.md
    ui.md
  src/api/
  src/ui/

根目录写仓库用途、实际包管理器、常用测试入口，以及所有模块共同遵守的要求。不要把每个历史问题都放进常驻文件。

为 API 目录写一条规则

.claude/rules/api.md 示例：

---
paths:
  - "src/api/**/*.ts"
---

修改 API 时检查输入校验和错误响应。
复用本目录已有的错误类型。
在交付说明中列出新增或修改的 API 测试。

paths 相对项目 .claude 所在目录解析。Claude 对匹配文件进行读取、写入或编辑时，规则按需加载。前端文件使用自己的 paths，避免把服务器规范带入所有界面修改。

按两次观察确认加载

  1. 从项目根目录启动 Claude Code，运行 /context all，查看根目录 Memory files。
  2. 让 Claude 读取一个真实的 API 文件，确认路径规则和回答中的适用要求。
  3. 换一个前端文件，核对 UI 规则，查看有没有过期或矛盾条目。
  4. 记录文件路径和测试结果，再交给团队审阅。

若团队已有 AGENTS.md，先确定项目默认加载条件，避免在两种文件中维护互相矛盾的副本。当前版本支持直接读取 AGENTS.md，也支持通过 CLAUDE.md 导入。

长会话后检查局部规则

当前文档说明，根目录规则在压缩后重新注入；路径规则和子目录 CLAUDE.md 会按需加载。压缩后切回 API 修改时，先读取目标文件，再确认适用约定。

必须在所有任务中持续遵守的规则应放到全项目位置。文件访问和命令授权在权限设置中管理。

常见问题

Q: 根目录规则要写多长？

A: 官方建议每个 CLAUDE.md 尽量控制在 200 行以内，重点保留每次都需要的命令和约定。

Q: paths 相对哪个目录？

A: 项目规则以包含 .claude 的目录为基准，例如示例中的 repo。

Q: 规则文件能按子目录分类吗？

A: .claude/rules/ 中的 Markdown 会递归发现，可以按主题和模块组织。

Q: 为什么启动时没看到 API 规则？

A: 带 paths 的规则按匹配文件加载，读取 API 文件后再检查。

Q: 同时写“用 npm”和“用 pnpm”会怎样？

A: 指令冲突会影响一致执行，应按项目当前实际工具保留唯一约定。

Q: 压缩后还要重贴所有规则吗？

A: 根目录规则会重新注入，局部规则按需恢复。先读取当前模块文件并核对，再决定是否补充。

参考资料