CLAUDE.md 实战手册 2026：前后端分仓项目的 AI 治理指南

CLAUDE.md 实战手册 2026：前后端分仓项目的 AI 治理指南

作者：CodeGateway 团队 发布：2026-06-01 ｜ 最后更新：2026-06-01 预计阅读时长：13 分钟

TL;DR：CLAUDE.md 是 Claude Code 每次会话启动时都会读取的文件，是随项目一起走的持久化上下文。但它是上下文，不是强制配置：真要拦住某个动作，靠的是 hook 或 permissions.deny，而不是 CLAUDE.md 里写一句话。当团队维护多个前后端分离的独立仓库时，难点不在于写好一个文件，而在于跨不共享 git 根目录的仓库同步统一标准——这种情况下 Claude 没法靠目录向上遍历找到它们。本手册讲清楚加载顺序、按搭建顺序梳理的 Claude Code "harness"、可直接抄的前端仓（React）和后端仓（Go/FastAPI）CLAUDE.md 模板、跨独立仓共享标准的四种做法、.claude/rules/ 路径作用域、跨仓 API 契约同步、用 managed policy 做轻量治理、leader 关心的 token 成本杠杆与 ROI 测算，以及如何给整个团队一个统一的 Claude Code 接入端点。

目录

1. CLAUDE.md 是上下文，不是配置

2. CLAUDE.md 的加载顺序

3. 按搭建顺序看 harness

4. 前后端分仓：落地手册

5. 用 `.claude/rules/` 做路径作用域

6. 跨独立仓共享标准

7. 每个文件都要精简

8. 成本这一面：精简上下文，可量化的 ROI

9. 可扩展的轻量治理

10. 随模型演进维护 CLAUDE.md

11. CLAUDE.md vs AGENTS.md vs .cursor/rules

12. 验证 Claude 到底加载了什么

13. 五个常见错误

14. 给整个团队一个统一端点

15. FAQ

CLAUDE.md 是上下文，不是配置

很多团队用 CLAUDE.md 时，期待它能"强制"执行规则。它做不到。按 Anthropic 官方文档的说法，CLAUDE.md 和 auto memory 都"在每次会话开始时加载。Claude 把它们当作上下文，而不是强制配置。要无视 Claude 的判断、硬性拦住一个动作，请用 PreToolUse hook"。

这条区别直接决定了团队该怎么治理 AI 编程：

• 行为引导 → CLAUDE.md：约定、架构、"声明完成前先跑测试套件"、"API handler 放在 src/api/handlers/"。

• 硬性强制 → settings：拦命令或路径用 .claude/settings.json 里的 permissions.deny；隔离 agent 用 sandbox.enabled；锁定模型供应商用 env。

所以 CLAUDE.md 是你把每次都要重新解释的东西写下来的地方。官方的判断标准很实在：当 Claude 同一个错误犯第二次、code review 抓出一个 Claude 本该知道的点、或者一个新同事需要同样的上下文才能上手时，就该往 CLAUDE.md 里加。如果某条内容是多步流程、或只在代码库某个角落才用得上，它该进 skill 或路径作用域 rule——而不是那个每次会话都加载的文件。

CLAUDE.md 的加载顺序

Claude Code 读取 CLAUDE.md 的方式是从当前工作目录向上遍历目录树，把找到的所有文件拼接起来——根目录在前、当前目录在后，所以越具体的指令越靠后被读到。没有覆盖，全部成为上下文。

一共四个作用域，由宽到窄加载：

多仓场景下有两条机制要记住：

• 越近越优先，靠位置实现：同一目录内 CLAUDE.local.md 拼在 CLAUDE.md 之后；跨目录树越深的文件越靠后，所以它说了算。要有意识地利用这点。

• 子目录文件按需加载：工作目录之上的文件启动时全量加载；子目录里的文件只在 Claude 读到该子树文件时才加载。大仓库就是靠这个把 token 预算控制住——无关上下文永远不进窗口。

从 /init 开始。Claude 会分析仓库、生成一份初始 CLAUDE.md，带上它发现的构建命令、测试说明和约定。设 CLAUDE_CODE_NEW_INIT=1 可走交互式流程：用 subagent 探索代码库，在写入任何文件前先给你一份可审阅的方案。如果已有 CLAUDE.md，/init 会提建议而不是覆盖。

按搭建顺序看 harness

Anthropic 关于 Claude Code 规模化的指南里有一句值得在动笔写 CLAUDE.md 之前先记牢：harness（外壳）和模型一样重要。harness 由五个扩展点组成，搭建顺序很关键，因为每一层都建立在上一层之上。

还有两个能力补全这套：LSP 集成（符号级导航，让 Claude 顺着函数找到真正的定义，而不是 grep 一个名字然后猜）和 subagents（独立上下文，探索某个子系统后只把结论返回主线程，保持主线程聚焦）。

CLAUDE.md 排第一，因为它是其他一切默认依赖的那一层。但注意官方对每一层点名的最常见错误：把该放别处的东西塞进 CLAUDE.md。多步流程该进 skill；"提交前必须跑"的规则该进 hook——它无视 Claude 的判断照样执行，这是 CLAUDE.md 的一句话保证不了的。CLAUDE.md 只放真正每次会话都适用的内容。

前后端分仓：落地手册

绝大多数团队的真实处境是这样的：一个 React/Next.js 前端仓 和一个 Go 或 FastAPI 后端仓，各有自己的 git 根目录，并排 clone 在本地。官方的大型代码库指南是围绕 monorepo 写的，而当你拆成独立仓时，有一条假设悄悄失效了：

Claude 会自动向上遍历目录树，加载沿途每一个 CLAUDE.md。

在两个独立 git 根之间，根本没有可以向上遍历进去的目录。frontend/CLAUDE.md 和 backend/CLAUDE.md 永远看不到彼此。于是手册拆成两个问题：(a) 让每个仓自身足够好；(b) 共享必须共享的东西（见 §6）。

每个仓一份聚焦的 root CLAUDE.md

好的 CLAUDE.md 描述意图和约束，而不是 Claude 自己就能发现的命令。控制在 200 行以内。前端仓：

# 前端 Web 应用

Next.js 15（App Router）、TypeScript、Tailwind、TanStack Query、Vitest。
通过 REST 调用独立仓 `payments-api` 后端。

## 约定
- 组件：`components/` 下 PascalCase。Hooks：`hooks/` 下 `useFoo`。
- 服务端状态只走 TanStack Query——不要再复制一份进客户端 store。
- 每个边界（表单、API 响应、env）都用 Zod 校验。
- API 调用走 `lib/api/` 客户端；不要在组件里直接 `fetch`。

## 测试纪律
- 声明完成前：`pnpm typecheck && pnpm test --run`。
- 带逻辑的 UI 要有 Vitest 测试，不只是快照。

## 不要做
- 不要再加第二个状态管理库；只用 TanStack Query + Zustand。
- 不要动 `src/generated/`——它从后端 OpenAPI spec 重新生成。

后端仓：

# payments-api

FastAPI + SQLAlchemy 2.0（async）、Postgres、Python 3.12。为 Web 应用提供服务。

## 架构
- `app/api/v1/` 里的路由保持薄：解析、调 service、返回。
- 业务逻辑在 `app/services/`，DB 模型在 `app/db/models.py`。
- 每个公开端点都声明 Pydantic `response_model`。

## 测试纪律
- 声明任务完成前跑 `uv run pytest -q`。
- 新端点至少要有一个 TestClient 集成测试。
- 测试里绝不调真实模型供应商——要 mock。

## 不要做
- 不要手改数据库；每次 schema 变更都走 Alembic 迁移。
- 不要在没标注前端契约影响的情况下改 `response_model`。

注意两份文件都点了对方仓和两者之间的契约。这个交叉引用，正是真正的多仓问题的起点。

把测试和 lint 命令限定在适用范围

一条能直接迁移的 monorepo 经验：Claude 只改了一个服务却跑整套套件，会"导致超时，并把上下文浪费在无关输出上"。分仓后这点天然成立——但在单个仓内部，如果你有 web/ 和 mobile/ 两个 package，就把各自的命令写进各目录的 CLAUDE.md，让 Claude 只跑相关的那部分。

同时跨两个仓工作

当前端改动需要后端的 API 上下文时，你不用复制任何东西。把 Claude 指向兄弟仓，并把它的 CLAUDE.md 一起拉进来：

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../payments-api

--add-dir 授予对兄弟目录的访问权；环境变量告诉 Claude 同时加载那个仓的 CLAUDE.md、.claude/rules/*.md 和 .claude/CLAUDE.md。这样一来，前端会话就理解了后端的约定，而你不用维护一份重复拷贝。

用 .claude/rules/ 做路径作用域

一旦 CLAUDE.md 开始变长，就把情景化的引导挪进 .claude/rules/。每个文件管一个主题，用 paths: frontmatter 字段做作用域，使它只在 Claude 碰到匹配文件时才加载——其余时候不占上下文。

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

# 前端 API 客户端规则

- 每个客户端方法都用对应的 Zod schema 校验响应。
- 用共享的 `ApiError` 类型抛错；不要抛原始 fetch 错误。
- 客户端从后端 OpenAPI spec 生成；不要手改 `src/generated/`。

your-repo/
├── .claude/
│   ├── CLAUDE.md            # 精简：指针 + 关键的坑
│   └── rules/
│       ├── code-style.md    # 每次会话加载（无 paths）
│       ├── api-client.md    # 只在 src/api/** 时加载
│       └── testing.md       # 测试约定

没有 paths 字段的 rule 每次会话加载，优先级与 .claude/CLAUDE.md 相同；带 paths 的只在 Claude 读到匹配文件时触发。glob 模式如你所料——src/**/*.{ts,tsx}、tests/**/*.test.ts，支持花括号展开。

要让一个大前端仓保持"可读"，这是杠杆最高的一招：root CLAUDE.md 保持一屏的定位说明，详细规则在相关时才精准浮现。

跨独立仓共享标准

这是 monorepo 指南跳过、却是治理前后端分仓 AI 编程核心的部分。共有四种机制，由轻到重：

1. 用户级 rules（`~/.claude/rules/`）：适用于本机所有项目的个人约定——在项目 rules 之前加载，所以项目 rules 仍然优先。适合个人偏好，不适合团队标准。

2. 把一份共享 rules 目录符号链接进每个仓：维护单一事实源，再链进去。.claude/rules/ 会正常解析符号链接：

# 一份共享标准仓，链进前端和后端
ln -s ~/org-standards/security.md      frontend/.claude/rules/security.md
ln -s ~/org-standards/security.md      backend/.claude/rules/security.md
ln -s ~/org-standards/api-contract.md  frontend/.claude/rules/api-contract.md
ln -s ~/org-standards/api-contract.md  backend/.claude/rules/api-contract.md

改一次 ~/org-standards/security.md，每个链接进去的仓都会拿到更新。把 org-standards 做成独立 git 仓（或 submodule），让标准本身也被版本化、被审阅。

3. 用 `@` 从 home 导入：已提交的 CLAUDE.md 可以用 @path 语法拉进个人或共享文件（最大深度四跳）：

# 个人 + 共享偏好
- @~/.claude/org-standards/security.md

4. Managed policy（组织级杠杆）：通过 MDM、组策略或 Ansible 把一份 CLAUDE.md 部署到 managed-policy 位置——或者把内容直接写进 managed-settings.json：

{ "claudeMd": "不要直接 push 到 main。\nAI 生成的代码走和人写代码一样的 PR review。" }

managed-policy CLAUDE.md 适用于本机每次会话、每个仓，且无法被个人设置排除。这正是你想要的——那些必须处处生效的规则（安全、合规、"AI 代码与人写代码同等 review"），无论开发者此刻在你十个仓里的哪一个，都照样适用。

跨仓契约：前后端共享一份 API 契约：共享类型、请求/响应 schema、错误码。一旦漂移，Claude 会自信地按后端早已不再返回的结构去写前端调用。给契约定一个家——多数团队从后端 OpenAPI spec 生成前端客户端——并在两个仓里都放一份简短的 api-contract.md rule（从同一源符号链接），说明契约住在哪、以及"它是生成的，绝不手写"这条规则。这一条共享 rule，就能挡掉一整类自信却错误的跨仓改动。

每个文件都要精简

CLAUDE.md 每次会话都全量加载，不管多长——所以长度是对每次对话的直接征税，而且越长的文件实测越降低遵循度（重要规则淹没在噪声里）。官方目标：每个文件 200 行以内。

落地纪律：

• root 文件只放指针和关键的坑：每个顶层目录一行描述，加上 Claude 老犯的那三个错。其余都会沦为噪声。

• 如果 Claude 没那条指令也做对了，删掉那条指令。

• 多步流程 → skill。路径相关的细节 → 带 paths 的 .claude/rules/。每次必跑 → hook。

• 块级 HTML 注释在内容进入 Claude 之前会被剥掉，所以你可以留给人类维护者看的备注而不耗 token。

还有个相关机制：auto memory。它和 CLAUDE.md 分开，Claude 会把自己的笔记（构建怪癖、调试发现、它摸索出的偏好）存进每个仓独立的 memory 目录；其 MEMORY.md 索引的前 ~200 行每次会话加载。CLAUDE.md 是你写来引导行为的；auto memory 是 Claude 写来给自己记的。跑 /memory 可以浏览、编辑或关闭它。

成本这一面：精简上下文，可量化的 ROI

对 leader 来说，这一切底下的问题是钱：AI 编程烧 token，token 是一项开支。让人安心的是，本手册里几乎每条实践同时也是省钱杠杆——而少数会抬高消耗的做法，往往用省下的工程师时间把成本赚回来。

token 花在哪、什么能省。 CLAUDE.md 每次会话全量加载，每个开发者都加载。这让臃肿的 root 文件成为整套配置里最可控的一项经常性成本。本指南里的每个机制，都在把 token 挡在主上下文之外：

一个粗略测算：把 root CLAUDE.md 从约 600 行裁到约 180 行，每次会话省下大约几千 input token。一个 20 人团队每天若跑约 40 次会话，每天就重复约 800 次——这种固定浪费不管那些行有没有帮上忙都照付，正是会累积成实打实月度账单的那种数字。

有意识地花的 ROI。 不是每个 token 都该砍。贵的那个 token，是花在盲目导航、然后返工上的。一个只读 subagent 在主 agent 动手前先把子系统摸清楚，会花 token——但挡掉了一次错上下文的改动，以及本会用来兜底的那轮 review。Anthropic 自己的观察很直接：在代码库配置上投入的团队，结果更好。 对 leader 真正重要的算式，不是孤立看 token，而是 token 对工程师时间：一次 agent 会话花几美分；一个工程师小时贵几个数量级；一次错误合并更贵。如果好上下文把三轮迭代的任务变成一轮，这笔花费早已回本好几倍。

所以治理目标不是"把 token 降到最低"，而是让每个 token 产出的有用工作最大化：砍掉浪费（臃肿上下文、盲目导航、改一行却跑整套测试），把钱投在会复利的地方（一份精炼的 CLAUDE.md、LSP、探索型 subagent）。

让成本看得见。 你没法优化看不见的东西。最常见的成本失控会话，都能追到一个具体原因——一份 900 行的 CLAUDE.md、一个没配的 .ignore 让 Claude 去读 node_modules、只动一个服务却加载了整个 monorepo。按开发者、按仓的用量可见性，能把"我们 AI 账单很高"变成"是这个仓的 root 文件有问题"。这份可见性本身就是一根治理杠杆——也是把团队接到一个统一端点的又一个理由（见给整个团队一个统一端点）。

可扩展的轻量治理

治理好 AI 编程不需要一套企业级项目，需要的是几个有意识做出的决定。Anthropic 在成功落地中观察到的模式可以压缩成这几条：

• 指定一个 DRI：一个人负责 Claude Code 配置——settings、权限策略、plugin 集、CLAUDE.md 约定——并负责保持它们最新。没人来沉淀"什么有效"，好配置就停留在小圈子里、采用率触顶。更大的组织会把这个角色正式化为 agent manager（PM/工程师复合角色）。

• 把强制和引导分开：用 managed permissions.deny 拦工具、命令、路径；managed-policy CLAUDE.md 留给行为和合规引导。settings 无论 Claude 怎么想都由客户端强制执行；CLAUDE.md 引导行为，但不是硬墙。

• AI 代码走和人写代码一样的 review：这是一条 CLAUDE.md/流程规则，不是工具开关——写进 managed policy，让它跨每个仓都成立。

• 从窄开始，按信心扩展：先定一组获批的 skills 和 plugins、必经的 review、有限的初始权限，再逐步放开。最顺的落地都在早期就把工程、安全、治理三方拉到一起共同定需求。

针对前后端分仓，把获批的配置打包成 plugin（捆绑 skills + hooks + MCP）通过 managed marketplace 分发，新工程师第一天装上就和所有人有同样的上下文与护栏——在两个仓里都是。

随模型演进维护 CLAUDE.md

CLAUDE.md 不是写一次就完。为今天模型写的指令，可能反过来拖累未来的模型：一条让 Claude 把每次重构都拆成单文件改动的规则，也许帮过旧模型稳住，却会拦住新模型本来能做好的协调式跨文件编辑。

把配置当成会衰减的东西来对待：

• 每三到六个月复审一次 CLAUDE.md、嵌套文件和 .claude/rules/，每次重大模型发布后、或感觉性能触顶时再复审。

• 像审文档改动一样，在 pull request 里 review CLAUDE.md 的修改。

• 加一个 Stop hook，让它拿到会话记录、在暴露出的缺口还新鲜时提议 CLAUDE.md 更新。这是 hook 最高价值的用法：不只是防错，而是让配置自我改进。

• 删掉那些为补旧模型短板而写、如今新模型已无此短板的 rule 和 hook——短板没了，它们就是纯开销。

CLAUDE.md vs AGENTS.md vs .cursor/rules

如果团队同时跑多个编码 agent，你会碰到同一个想法的三个文件名。每个 agent 只读自己的文件，但内容纪律可以干净地迁移。

Claude Code 读 CLAUDE.md，不读 AGENTS.md。如果你的仓已经为别的 agent 用了 AGENTS.md，别复制——导入它：

@AGENTS.md

## Claude Code
`src/billing/` 下的改动用 plan 模式。

符号链接也行（ln -s AGENTS.md CLAUDE.md），不过 Windows 上需要管理员或开发者模式，所以 @AGENTS.md 导入是更通用的选择。在已有 AGENTS.md 的仓里跑 /init，它会读取并把相关部分折进生成的 CLAUDE.md。单一事实源，没有会腐烂的分叉拷贝。

（Codex CLI 这一侧的完整故事，见我们的 AGENTS.md 层级实战手册。）

验证 Claude 到底加载了什么

用上几个月后，几乎每个团队都至少有一份 CLAUDE.md 的规则没在加载——一个路径怪癖、一个放错位置的文件、一个被随意化解的冲突。要验证，别假设：

• 跑 /memory 列出当前会话加载的每一个 CLAUDE.md、CLAUDE.local.md 和 rules 文件。没列出来的，Claude 就看不到。

• 更深的调试用 InstructionsLoaded hook，它精确记录哪些指令文件加载了、何时、为什么——对路径作用域 rule 和懒加载的子目录文件尤其有用。

• /compact 之后，project-root 的 CLAUDE.md 会从磁盘重新读取并重新注入；嵌套子目录文件不会被重新注入，直到 Claude 下次读到该子树的文件。如果某条指令在压缩后"消失了"，它要么只在对话里给过，要么住在一个还没重新加载的嵌套文件里。

指令冲突时 Claude 可能随意挑一个——所以上面那轮维护不是可选的卫生工作，而是你保持整套层级可信的方式。

五个常见错误

1. 把 CLAUDE.md 当强制：它是上下文。任何必须发生的事——拦路径、提交前必跑——是 hook 或 permissions.deny。

2. 一个巨大的 root CLAUDE.md：超过约 200 行，遵循度下降。把细节推进路径作用域 rule 和 skill；root 保持一屏定位。

3. 写命令而不是意图："Run pnpm test" 在你改脚本名时就烂了。"声明完成前跑测试套件" 不会。

4. 以为独立仓共享上下文：不共享——没有公共 git 根可向上遍历。用符号链接 rule、@ 导入或 managed policy 显式共享标准。

5. 从不复审：配置随模型变强而衰减。每 3–6 个月、每次重大模型发布后复审一次；删掉新模型已让其多余的内容。

给整个团队一个统一端点

治理也有计费这一面。当两个仓里十几个开发者各自跑 Claude Code，你会想要一个地方看用量、一张账单——而不是十几张个人卡、零可见性。把 Claude Code 指向 CodeGateway 这个 Anthropic 兼容端点：

export ANTHROPIC_BASE_URL=https://api.codegateway.dev
export ANTHROPIC_API_KEY=cg-...   # 来自你的 CodeGateway 控制台
claude

你的 CLAUDE.md、rules、hooks、skills 和 subagents 行为完全不变——CodeGateway 在 API 层，上面那套 harness 原封不动。你得到的是团队级的东西：每个开发者用自己的 key 登录，网关聚合计费，你拿到整个团队一个用量看板，不用自建代理。当开发者处在要求 API 流量经由获批网关的企业网络后面时，这也是设置单一自定义端点的干净做法。

计费沿用与直连相同的按 token 模型，外加一个透明的阶梯倍率，团队用量越大倍率越低——见 定价 和 阶梯倍率详解。

FAQ

Q：会话中途改了 CLAUDE.md，Claude 会重新读吗？ project-root 的 CLAUDE.md 在 /compact 后会重新读取，但要干净地让改动生效，开个新会话。嵌套子目录文件会在 Claude 下次读到该子树文件时重新加载。

Q：怎么跨独立的前端、后端仓共享标准？ 四种，由轻到重：用户级 ~/.claude/rules/、符号链接一份共享 rules 目录、用 @ 从 home 导入、或部署一份 managed-policy CLAUDE.md。只有 managed policy 是不能被单个开发者关掉的。

Q：放 CLAUDE.md、`.claude/rules/` 还是 skill？ 每次会话都需要的（构建命令、架构）放 CLAUDE.md。只在部分代码树才重要的，放带 paths: 的 .claude/rules/。只是偶尔需要的多步流程，做成 skill。

Q：我的 CLAUDE.md 太长了怎么办？ 裁到 200 行以内。把路径相关内容挪进 .claude/rules/（只在匹配文件时加载）。注意 @ 导入有助于组织、但不减小上下文——被导入文件启动时仍全量加载。

Q：大仓里怎么不让别的团队的 CLAUDE.md 也加载进来？ 在 .claude/settings.local.json 里用 claudeMdExcludes（按绝对路径做 glob 匹配）。managed-policy 文件是例外——它永远不能被排除。

Q：CLAUDE.md 够满足合规要求吗？ 不够。CLAUDE.md 引导行为，但不被强制。把 managed CLAUDE.md 里的行为引导，与 managed settings 里的硬控制（permissions.deny、sandbox.enabled），再加上"AI 生成代码与人写代码完全同等 review"的流程，三者配合。

相关资料

• AGENTS.md 层级实战手册 2026——本指南的 Codex CLI 对应篇

• OpenAI Codex CLI 完整参考 2026

• Claude Code vs Cursor vs Copilot

• 错误排查（401 / 429 / 500）

• 阶梯倍率详解 · 定价

官方参考

• Claude 如何记住你的项目（CLAUDE.md 与 memory）

• Claude Code 在大型代码库中如何工作

• 使用 CLAUDE.md 文件

• 在 monorepo 或大型代码库中配置 Claude Code