📌 标签：#多仓库 #微服务 #依赖管理 #跨仓库协作 #企业级
现代企业的代码库很少是单个 Git 仓库。微服务、前端+后端分离、共享库、协议定义……代码可能分散在几十甚至上百个仓库中。Claude Code 默认只认识当前目录所在的仓库，当你的任务需要跨越多个仓库时（比如“修改用户服务的 API，同时更新 API 网关和前端调用”），AI 就会因为看不到其他仓库的代码而“瞎”了。本篇教你如何让 Claude Code 理解多仓库之间的依赖关系，安全地进行跨仓库的代码分析和修改。
1. 多仓库协作的三大挑战
| 上下文缺失 | AI 只能看到当前仓库，不知其他仓库如何使用当前仓库的 API | 人工提供信息，或手动在其他仓库中搜索 | 通过 MCP 同时加载多个仓库，或让 AI 读取依赖图谱 |
| 跨仓库修改 | 一次变更需要同时修改多个仓库（如升级共享库版本） | 人工顺序修改，容易遗漏 | AI 可以生成跨仓库的 PR 列表，或通过脚本批量执行 |
| 构建顺序 | 仓库之间存在依赖关系，必须先构建 A 再构建 B | 依赖人工维护构建顺序或使用工具（如 Bazel） | AI 分析依赖图，输出正确的构建顺序 |
核心思想：让 AI 看到整个系统的“依赖地图”，而不是单个仓库的局部信息。
2. 理解仓库间依赖的几种方式
2.1 方式一：单一 CLAUDE.md 索引所有仓库
在团队维护一个元仓库（或一个专门的文档仓库），包含一个 CLAUDE.md 文件，列出所有相关仓库及其职责、依赖关系、公共 API 端点。
# 集团项目仓库索引
## 用户服务 (user-svc)
– Git: git@github.com:company/user-svc.git
– 主要 API: GET /users/{id}, POST /users, PUT /users/{id}
– 依赖: 无
– 被以下仓库依赖: api-gateway, frontend-web, mobile-app
## API 网关 (api-gateway)
– Git: git@github.com:company/api-gateway.git
– 依赖: user-svc, order-svc, payment-svc
– 出口: 对外暴露 /api/v1/*
## 共享 Proto 定义 (proto-repo)
– Git: git@github.com:company/proto-repo.git
– 包含: user.proto, order.proto
– 被所有 gRPC 服务依赖
当你在 Claude Code 中询问“修改用户服务的返回字段时，需要同步修改哪些仓库？”，AI 可以读取这个索引文件，给出答案。
优点：简单、不依赖工具。
缺点：依赖人工维护，容易过时。
2.2 方式二：使用依赖关系图文件
很多构建系统（如 Bazel、Pants、Lerna、Nx）可以导出依赖图。你可以定期生成一个 deps.json，让 Claude Code 读取。
例如，使用 nx graph –file=deps.json 导出 Nx 项目的依赖图。然后告诉 AI：
claude –print "根据 @deps.json，如果要修改 shared/ui/button 组件，哪些应用会受影响？"
AI 解析 JSON，输出受影响的应用列表。
优点：自动化生成，与构建系统同步。
缺点：需要构建系统支持，非通用。
2.3 方式三：通过 MCP 动态拉取多个仓库
配置 MCP 服务器，让 Claude Code 能够动态克隆和读取其他仓库。例如，编写一个简单的 MCP 服务器 multi-repo-mcp，提供工具：
- search_repos(pattern): 在所有仓库中搜索代码。
- read_from_repo(repo_name, file_path): 读取指定仓库的文件。
- get_dependents(repo_name): 返回哪些仓库依赖该仓库。
Claude Code 可以在需要时调用这些工具，实时获取跨仓库信息，而不需要提前下载所有仓库代码。
优点：按需获取，信息最新。
缺点：需要开发和维护 MCP 服务器；每次调用有网络延迟。
3. 实战场景一：分析跨仓库影响范围
假设你要修改 user-svc 中 GET /users/{id} 接口的返回值，增加一个 phone 字段。需要知道哪些服务依赖这个字段。
3.1 步骤
让 AI 读取依赖索引：
根据 @company-repos.md，哪些仓库调用 user-svc 的 GET /users/{id}？
AI 输出：
根据索引，api-gateway、frontend-web、mobile-app 都调用了该接口。需要同步更新它们对响应数据的解析。
进一步要求：
请检查 api-gateway 仓库中的代码，找出具体使用 user.id 的地方，并生成修改建议。
AI 通过 MCP 工具（或要求你手动提供路径）读取 api-gateway 仓库的相关文件，输出具体文件和行号。
3.2 手动辅助方案
如果没有 MCP，你可以让 AI 生成一个脚本，批量 grep 所有本地已克隆的仓库：
#!/bin/bash
# search_across_repos.sh
for repo in ~/work/*-svc; do
echo "=== $repo ==="
grep -n "users/" $repo/src/ –include="*.js" || true
done
运行后将输出交给 AI 分析。
4. 实战场景二：跨仓库的批量修改
你需要将所有仓库中的 axios 升级到 1.x，并且修改调用方式（如 axios.post(url, data, config) 的参数变化）。
4.1 使用 Claude Code 生成每个仓库的 PR
提示词：
我有一个项目，包含以下仓库：user-svc, order-svc, api-gateway。每个仓库的根目录都在 ~/work/<repo>。请为每个仓库生成一个独立的 shell 脚本，用于：
1. 升级 package.json 中的 axios 版本到 1.6.0
2. 运行 `npm install`
3. 修改所有 axios 调用，将 `axios.post(url, data, config)` 改为 `axios.post(url, data, { …config, … })`（假设具体规则）
4. 运行测试，如果测试通过则提交 PR
AI 会输出三个脚本，每个脚本针对一个仓库。你可以在每个仓库目录下执行脚本，或进一步自动化。
4.2 使用 GitHub Actions 矩阵策略
生成一个 GitHub Actions workflow，使用 strategy.matrix 并行处理多个仓库：
name: Upgrade Axios Across Repos
on: workflow_dispatch
jobs:
upgrade:
strategy:
matrix:
repo: [user–svc, order–svc, api–gateway]
steps:
– uses: actions/checkout@v4
with:
repository: company/${{ matrix.repo }}
token: ${{ secrets.CROSS_REPO_TOKEN }}
– run: npm install axios@1.6.0
– run: claude ––print "修改 axios 调用方式…" ––allowed–tools Edit,Bash
– run: |
git commit -am "chore: upgrade axios to 1.6.0"
git push origin HEAD:upgrade-axios
– run: gh pr create –title "chore: upgrade axios" ––body "Auto–generated by Claude"
然后让 Claude Code 帮你生成这个 YAML 文件。
5. 维护依赖关系的自动化
为了让 AI 始终拿到最新的依赖关系，可以将依赖分析集成到 CI 中，定期更新 deps.json 并提交到元仓库。
示例脚本（使用 tsc + 自定义解析）：
// generate-deps.ts
import { execSync } from 'child_process';
import fs from 'fs';
const repos = ['user-svc', 'order-svc', 'api-gateway'];
const deps = {};
for (const repo of repos) {
const packageJson = JSON.parse(fs.readFileSync(`../${repo}/package.json`, 'utf-8'));
deps[repo] = {
dependencies: Object.keys(packageJson.dependencies || {}),
devDependencies: Object.keys(packageJson.devDependencies || {}),
};
}
fs.writeFileSync('deps.json', JSON.stringify(deps, null, 2));
然后在 .github/workflows/update-deps.yml 中每天运行并提交。
6. 多仓库的 CLAUDE.md 继承
每个仓库可以有自己的 CLAUDE.md，但公共的部分（如公司代码规范、通用架构原则）应该集中维护。可以通过 include 机制（非原生，用约定实现）：
在仓库的 .claude/CLAUDE.md 中写：
# 项目特定配置
## 公共规范
请参考 <https://raw.githubusercontent.com/company/common-claude/main/CLAUDE.md> 中的内容。
但 AI 不会自动下载 URL。你可以写一个脚本，在 claude 启动前将公共内容预置到环境变量或本地文件。或者使用 MCP fetch 工具（如果配置了）让 AI 主动拉取。
更简单的做法：在公司内部搭建一个简单的 HTTP 服务，提供公共 CLAUDE.md，然后在每个仓库的 CLAUDE.md 中写 请访问 http://internal/…，并人工训练 AI 养成“先 fetch 再遵循”的习惯。
7. 跨仓库的原子性变更与回滚
在多仓库场景下，一次功能变更往往需要多个仓库同时修改。如果部分仓库修改失败或部署失败，可能导致系统不一致。
策略：
- 使用 feature branch 跨仓库：在每个仓库创建同名分支（如 feature/add-phone-field）。AI 可以生成脚本批量创建分支。
- 使用 Changeset 或同步 PR：工具如 changesets 可以管理跨仓库的版本发布。AI 可辅助生成 changeset 文件。
- 回滚：通过 Git 的 revert 可以逐个仓库回滚。AI 可以生成回滚脚本，或利用第 40 篇的检查点机制。
8. 案例：微服务重构中的多仓库协作
背景：将 user-svc 从 RESTful 改为 gRPC，需要同时修改 api-gateway 的适配层和 frontend-web 的调用方式。
Claude Code 辅助流程：
分析影响：
根据 @repos-index.md，列出所有直接调用 user-svc REST 接口的仓库。
生成新接口定义：
为 user-svc 生成 gRPC proto 文件，保持与现有 REST 接口相同的功能。
生成适配层（在 api-gateway 中）：
在 api-gateway 中生成一个适配器，将新的 gRPC 调用转成旧的 REST 格式，以便前端逐步迁移。
为前端生成迁移指南：
生成一个迁移脚本，将 frontend-web 中对 /users/${id} 的 fetch 调用改为调用新的 gRPC-gateway 端点。
生成 PR 列表：
为每个需要修改的仓库生成 PR 描述和变更清单，并按依赖顺序排列（先改 user-svc，再改 api-gateway，最后改 frontend-web）。
验证：
在每个仓库中运行测试，并模拟端到端调用，确保新旧接口行为一致。
整个过程，AI 扮演了架构师、发布经理和开发者的多重角色。
9. 与现有工具的集成
- Bazel / Buck：AI 可以读取 BUILD 文件，理解目标间的依赖，输出影响分析。
- Lerna / Nx：AI 可以解析 nx.json 和项目图，指导增量构建。
- Git Submodules：如果使用子模块，Claude Code 默认会跳过 .git 目录，但你可以要求它读取子模块的 commit 信息。
10. 下篇预告
多仓库理解是技术层面的挑战。企业落地还需要考虑文化层面：如何让团队接受统一的 AI 开发规范？如何定制适合企业的 CLAUDE.md 模板？下一篇我们将学习 企业定制 CLAUDE.md 模板：打造企业级代码规范与 AI 行为对齐。
👉 下一篇： 企业定制CLAUDE.md模板：打造企业级代码规范与AI行为对齐
思考题（自测理解）
多仓库协作让 AI 从“单仓库助手”升级为“系统架构师”。下一篇，我们把视野从代码提升到企业级规范。
