# Claude Code 多目录项目怎么写规则？根目录与 paths 条件示例

前后端共用仓库时，Claude Code 的全项目规则和局部规则可分别放在根目录 CLAUDE.md 与 .claude/rules。本文用 API 和前端目录说明 paths 匹配、按需加载、导入和冲突检查，并提供启动后与读取目标文件后的核对步骤。示例帮助缩短常驻指令，保留模块约定，同时检查压缩后局部规则的恢复方式。有 AGENTS.md 时先查加载条件。

原页面：https://ccmaxplan.com/articles/claude-code-monorepo-instructions-layout

发布时间：2026-11-10T01:56:00.700312+00:00

更新时间：2026-11-10T01:56:00.700312+00:00

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

## 先列出规则的作用范围

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

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

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

## 为 API 目录写一条规则

`.claude/rules/api.md` 示例：

```markdown
---
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: 根目录规则会重新注入，局部规则按需恢复。先读取当前模块文件并核对，再决定是否补充。

## 参考资料

* [Claude Code 项目指令与记忆](https://code.claude.com/docs/en/memory)
* [Claude Code 上下文与压缩](https://code.claude.com/docs/en/context-window)