当一个系统的代码分散在多个仓库时，如何正确使用GitHub Copilot、Cursor、Claude Code和Codex这类AI coding assistant。
本篇文章的核心内容只有一句话：
多repo工程里，AI正确实践的第一步不是调prompt，也不是直接迁monorepo，而是先建立一个统一的Base Repo，让AI从系统入口理解全局上下文。
一个好的产品，正常需要不断迭代：吸收问题、改进自己、持续进化。
但一个好的业务架构，应该尽量不变应万变。它不应该因为工具换了、模型换了、AI特性增加了，就反复推倒重来。更合理的做法是：核心结构稳定，所有变化通过扩展、定义和插件化能力来承接。
Base Repo就是这种稳定架构。本文初稿完成于2025年11月；之后出现的各种AI能力，无论是MCP、skill、subagent、workflow、RAG、OpenSpec还是自动化归档，都可以被Base Repo承接。核心目录和协作模型不需要重做，只需要继续加扩展和定义。
flowchart LR
A["多repo系统"] --> B["上下文分散"]
B --> C["AI只能看到局部"]
C --> D["误判边界、错修问题、反复补充上下文"]
D --> E["Base Repo"]
E --> F["统一入口、统一结构、统一规则"]
F --> G["AI能按系统链路协作"]
classDef warn fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
classDef ok fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class B,C,D warn;
class E,F,G ok;
0. 背景：多repo越来越常见
单个系统的代码分散在多个仓库中，现在越来越常见。
前后端分离以后，前端是一个repo，后端是一个repo。业务继续增长以后，又会出现多个移动端、网页端、管理后台、组件库、API SDK、基础设施代码。后端也会从单体服务逐渐拆成微服务，每个服务都有自己的发布节奏、owner和权限边界。
这就是现代中大型工程的常态。
多repo拆分可以带来组织和工程上的收益：
- 团队可以独立迭代
- 服务可以独立发布
- 权限边界更清楚
- CI/CD可以按模块拆开
- 不同技术栈可以各自演进
但有一句话需要先说清楚：
组织上的提升，一定会带来效率上的磨损。
这个磨损过去主要体现在CI、发布、联调和跨团队沟通上。现在AI coding assistant进入开发流程以后，它又多了一个新的表现形式：系统上下文断裂。
flowchart TB
subgraph S["一个业务系统"]
FE["Web前端"]
IOS["iOS端"]
AND["Android端"]
API["API服务"]
MS1["用户服务"]
MS2["订单服务"]
SDK["共享SDK"]
UI["组件库"]
INFRA["基础设施"]
DOC["文档和知识库"]
end
FE --> API
IOS --> API
AND --> API
API --> MS1
API --> MS2
FE --> SDK
IOS --> SDK
AND --> SDK
FE --> UI
API --> INFRA
DOC -.-> FE
DOC -.-> API
DOC -.-> MS1
DOC -.-> MS2
classDef app fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
classDef service fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
classDef support fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
class FE,IOS,AND app;
class API,MS1,MS2 service;
class SDK,UI,INFRA,DOC support;
今天的问题就是：在这种多repo系统里，我们到底应该怎么使用GitHub Copilot、Cursor、Claude Code和Codex？
这里的核心不是“哪个AI工具更强”，而是“你有没有给AI一个正确理解系统的位置”。
1. 多repo带来的AI问题
刚开始用Cursor或者其他AI工具时，很多人都是从单repo开始的。
一个前端仓库，一个需求，一个页面。配合API文档，很快就能闭环。再往后，系统开始变复杂：多个移动端Native代码、多个后端服务、组件库、Bridge、共享SDK、权限服务、灰度系统都来了。
这就是一个0到1系统最常见的多repo阶段。
伴随组织和个人对AI使用的要求提升，上下文共享和workflow协作就变成了现实需求。
1.1 第一类问题：上下文断裂
AI assistant的工作质量，首先取决于它能看到什么。
如果AI只站在单个repo里，它看到的就是局部。如果需求跨多个repo，它就会开始猜。
flowchart LR
U["用户需求<br/>上传用户头像"] --> A["AI Session<br/>只打开前端repo"]
A --> B["能看到<br/>页面、组件、状态管理"]
A -.-> C["看不到<br/>下发规则"]
A -.-> D["看不到<br/>Native Bridge"]
A -.-> E["看不到<br/>后端API契约"]
A -.-> F["看不到<br/>存储和审核逻辑"]
B --> G["生成局部代码"]
C --> H["联调失败"]
D --> H
E --> H
F --> H
classDef seen fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
classDef missing fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
class B,G seen;
class C,D,E,F,H missing;
场景：前端需要开发上传用户头像功能。
如果AI只在前端repo中，它可能不知道：
- 头像上传由哪个服务接收
- 文件大小和格式规则在哪里
- 是否需要新加Native Bridge
- Bridge由哪个移动端repo维护
- 是否需要后端下发配置
- 是否涉及审核、缓存、CDN和灰度
最后它可能写出一个前端看起来可以运行的页面，但这不是一个完整功能。
1.2 第二类问题：依赖其他repo知识
前端开发经常依赖接口文档。接口文档如果不清楚，一个需求就会被拉长。
现在AI也一样。你让AI给表单增加一个字段，它可能知道怎么改表单，但不知道字段背后的约束。
sequenceDiagram
participant User as 用户
participant AI as AI只看前端repo
participant FE as 前端表单
participant API as 后端API
participant DB as DB schema
participant Test as 集成测试
User->>AI: 增加一个手机号字段
AI->>FE: 更新表单和payload
AI-->>User: 前端代码完成
FE->>API: 提交phone字段
API->>DB: 校验字段约束
DB-->>API: 约束不匹配
API-->>FE: 400/校验失败
FE->>Test: 集成测试失败
你可能遇到的情况是：
- AI更新了表单
- 但不知道后端校验规则
- 不知道DB schema限制
- 不知道API契约要求
- 写出的代码单独看没问题，但run不过完整链路
更典型的是：
- 前端修改通过AI CR
- 前端本地检查也过了
- 集成测试失败
- 后端接口直接拒绝
- 联调阶段出现大量返工
这不是前端AI不够聪明，而是它缺少系统链路上下文。
1.3 第三类问题：问题诊断
问题诊断比功能开发更依赖全局上下文。
例如反馈问题：
群聊笔记展示异常。
如果AI session只在IM repo中，它可能会：
- 检查IM消息体
- 检查消息渲染逻辑
- 检查本地状态
- 发现消息体正常
- 然后开始猜
但它看不到：
- 笔记API返回
- 服务端聚合逻辑
- DB里真实数据
- 服务间调用
- 权限过滤
- 灰度和配置
最后就会变成：假设、幻觉、白烧Token。
flowchart TB
BUG["群聊笔记展示异常"] --> IM["AI只看IM repo"]
IM --> M1["消息体正常"]
IM --> M2["渲染逻辑正常"]
IM --> M3["本地状态正常"]
BUG -.真实链路.-> API["笔记API"]
API --> SVC["笔记服务"]
SVC --> DB["数据库"]
SVC --> ACL["权限服务"]
SVC --> CFG["灰度配置"]
M1 --> WRONG["开始猜测<br/>消耗Token<br/>修错位置"]
M2 --> WRONG
M3 --> WRONG
classDef local fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
classDef hidden fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
classDef bad fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
class IM,M1,M2,M3 local;
class API,SVC,DB,ACL,CFG hidden;
class WRONG bad;
所以，多repo下AI的第一问题不是生成能力，而是上下文入口。
2. 问题调研：大厂怎么解决统一上下文入口
这个问题不是我们今天才遇到的。
只不过以前它表现为CI问题、构建问题、依赖问题、代码搜索问题；现在AI进入开发流程以后，它又表现为Agent缺少系统工程上下文。
所以在确定Base Repo之前，我先看了几个大厂是怎么解决类似问题的。
2.1 Google：统一代码视图和中心化研发基础设施
Google的思路很极致。
它不是先保留多repo，再想办法给AI补上下文；Google长期采用的是统一代码视图，把绝大多数软件资产放在一个超大规模代码库里，再配套一整套自研基础设施。
公开资料里提到的关键组件包括：
- Piper：Google自研的分布式源码管理系统
- CitC：Clients in the Cloud，云端工作区
- CodeSearch：代码搜索
- Critique：代码评审
- Tricorder：静态分析
- Rosie：大规模代码修改
这套体系的核心不是“一个工具”，而是统一代码视图 + 统一依赖 + 统一构建 + 统一搜索 + 统一测试 + 统一评审。
flowchart TB
G["Google研发基础设施"] --> P["Piper<br/>统一代码库"]
G --> C["CitC<br/>云端工作区"]
G --> S["CodeSearch<br/>统一搜索"]
G --> R["Critique<br/>统一评审"]
G --> T["Tricorder<br/>静态分析"]
G --> B["构建/测试系统"]
P --> V["统一代码视图"]
C --> V
S --> V
R --> V
T --> V
B --> V
V --> AI["天然适配新的AI能力<br/>因为系统入口本来就是统一的"]
classDef infra fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef value fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class G,P,C,S,R,T,B,V infra;
class AI value;
从AI角度看，这个方案非常理想。
因为AI不需要在一堆本地散落的repo里猜上下文。代码、依赖、搜索、评审、测试都已经被中心化研发基础设施管理起来了。新的AI feature出现时，只要接入这套统一入口，就天然可以获得更完整的系统上下文。
但这套方案背后的前提也很重：
- 统一源码管理系统
- 统一构建系统
- 统一代码搜索
- 统一评审系统
- 统一测试和静态分析
- 统一开发工作区
- 多年基础设施投入
这不是一个普通团队可以直接复制的方案。
2.2 Microsoft/GitHub：云端IDE和云端开发容器
一位Microsoft工程师的分享介绍过内部的AI使用完整面貌
Microsoft和GitHub的工作现场更接近“云端开发环境”
GitHub Codespaces提供云端开发环境，开发者可以通过浏览器或VS Code连接。Microsoft Dev Box提供预配置的云端开发工作站，平台团队可以把项目需要的工具、源码、依赖和预构建产物提前准备好。
开发者只需要一个浏览器，就可以工作。Microsoft后续也推出了面向本地AI开发的Surface RTX Spark Dev Box，说明它的路线更像“云端工作区 + 本地高性能开发设备”并存。
flowchart LR
DEV["开发者"] --> Browser["浏览器 / VS Code"]
Browser --> Cloud["云端开发环境"]
Cloud --> IDE["云端IDE"]
Cloud --> Container["云端容器/工作站"]
Cloud --> Repo["代码仓库"]
Cloud --> Tools["工具链和依赖"]
Cloud --> AI["AI上下文管理"]
Cloud --> CI["构建/测试/CI"]
DEV -.可选.-> Local["本地开发设备<br/>例如本地AI Dev Box"]
Local -.同步.-> Repo
classDef cloud fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef local fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
class Cloud,IDE,Container,Repo,Tools,AI,CI cloud;
class Local local;
这条路线解决的问题也很明确：
- 本地环境不一致
- 新人初始化成本高
- 多repo clone和依赖安装复杂
- 工具链版本不一致
- 安全和权限难管
- AI工作上下文无法统一
它的答案是：把“研发电脑上的入口”搬到一个可控的云端环境里。
2.3 为什么这些方案不适合我们
Google和Microsoft/GitHub的方向证明了一件事：
大型工程最终都会把开发入口从“个人电脑上的散乱本地仓库”收敛到“统一开发控制面”。
区别在于控制面的形态。
flowchart TB
Q["如何解决系统级上下文？"] --> G["Google路线<br/>统一代码视图 + 中心化研发基础设施"]
Q --> M["Microsoft/GitHub路线<br/>云端IDE + 云端容器/工作站"]
Q --> U["我们的路线<br/>Base Repo轻量控制面"]
G --> GC["投入极重<br/>适合超大规模统一工程体系"]
M --> MC["平台较重<br/>适合云端开发环境成熟团队"]
U --> UC["低侵入<br/>保留现有repo和本地开发方式"]
classDef heavy fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
classDef light fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class G,M,GC,MC heavy;
class U,UC light;
这些思路都非常有价值，但不适合直接照搬。
Google路线太重。它不是一个“建个仓库”就能获得的能力，而是长期建设出来的统一研发基础设施。
Microsoft/GitHub路线也偏重。云端IDE、云端容器、云端工作站确实可以把环境和入口统一起来，但它会引入平台建设、权限治理、成本、网络、IDE习惯和本地调试体验等问题。
我们的目标更现实：
- 不迁移monorepo
- 不强制云端IDE
- 不重做公司研发基础设施
- 不打破现有repo权限和发布模型
- 仍然让AI获得足够完整的系统上下文
所以我们需要一个更轻量的解决方案。
这个方案就是Base Repo。
3. Monorepo：老问题的老解法
这不是一个新问题。
在AI工具流行之前，类似问题早就存在。CI、构建、测试、依赖管理，都曾经被多repo拆分折磨过。
多repo太多太杂以后，CI会遇到各种问题：
- 依赖版本不一致
- 构建顺序不清楚
- 集成测试难跑
- 跨repo变更难验证
- 发布链路复杂
于是行业里出现了一个通用方案：Monorepo。
flowchart LR
A["单repo太大"] --> B["拆成多repo"]
B --> C["多repo太多太散"]
C --> D["CI和依赖管理复杂"]
D --> E["Monorepo"]
E --> F["统一构建<br/>统一依赖<br/>统一测试<br/>统一上下文"]
classDef issue fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
classDef solution fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class B,C,D issue;
class E,F solution;
AI遇到的问题和CI遇到的问题非常相似。
CI需要知道依赖关系，AI也需要知道依赖关系。
CI需要知道哪些模块要一起验证，AI也需要知道哪些repo要一起改。
CI不能只跑一个局部然后假设全局没问题，AI也不能只看一个repo然后假设系统链路成立。
3.1 Monorepo可以直接拿来用吗？
答案是：在很多已有中大型团队里，不行。
不是因为Monorepo不好，而是因为迁移成本不可控。
迁移Monorepo会涉及：
- 现有工程结构改造
- 编译流水线重写
- 部署CI/CD重写
- 团队培训
- git历史迁移
- 权限模型调整
- 工具链适配
- 本地开发体验重建
flowchart TB
M["迁移Monorepo"] --> C1["代码结构改造"]
M --> C2["CI/CD重写"]
M --> C3["权限模型变化"]
M --> C4["团队培训"]
M --> C5["工具链适配"]
M --> C6["发布流程变化"]
C1 --> R["成本高、周期长、风险不可控"]
C2 --> R
C3 --> R
C4 --> R
C5 --> R
C6 --> R
classDef cost fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
class M,C1,C2,C3,C4,C5,C6,R cost;
前面说了，几乎所有中大型团队都会遇到多repo和AI上下文问题。如果我们要找的是一个通解，那么迁移成本高的方案就不是通解。
3.2 什么时候选择Monorepo
那为什么还要讲Monorepo？
因为它告诉我们一个重要方向：统一上下文是对的。
如果你现在从0到1开始做系统，并且你是架构和工程决策者，那么可以直接选择Monorepo。
它会天然解决本文中很多问题：
- AI可以从一个仓库看全局
- CI可以统一管理依赖
- API、端、前端、共享库可以在一个变更里联动
- 分支和PR天然一致
flowchart TD
START["你是否从0到1设计系统？"] --> YES{"是否能决定工程结构？"}
YES -- "能" --> MONO["直接考虑Monorepo"]
YES -- "不能" --> BASE["使用Base Repo"]
START -- "已有多repo系统" --> EXIST{"迁移成本是否可控？"}
EXIST -- "可控" --> MONO
EXIST -- "不可控" --> BASE
classDef mono fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
classDef base fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
class MONO mono;
class BASE base;
如果已经是多repo，且迁移成本不可控，就不要为了AI强行改变整个组织和工程结构。
这时应该走Base Repo。
4. Base Repo：多repo系统的AI统一入口
按照仿生的原则，假设你有一个拥有完整开发知识的机器人。
它要在多repo系统中工作，需要什么？
它需要一个地方能看到：
- 所有相关代码
- 系统结构
- repo职责
- API契约
- 文档
- 业务知识
- MCP配置
- skill、rule、subagent
- 跨repo工作流
- 质量校验方式
这个地方就是Base Repo。
也可以叫solution root、platform root、workspace root。名字不重要，关键是它承担的角色：
Base Repo不是业务仓库，而是AI理解系统和执行跨repo任务的统一入口。
flowchart TB
subgraph BR["Base Repo"]
A["AGENTS.md<br/>系统地图"]
B["clone-repos.sh<br/>初始化脚本"]
C["mcp-config.json<br/>目录级MCP"]
D["skills / rules<br/>专属能力"]
E["docs<br/>结构化知识"]
F["workflows<br/>跨repo流程"]
G["repos/业务仓库<br/>代码区域"]
end
G --> R1["前端repo"]
G --> R2["移动端repo"]
G --> R3["后端服务repo"]
G --> R4["共享库repo"]
G --> R5["基础设施repo"]
AI["AI Coding Assistant"] --> BR
classDef root fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef repo fill:#F8FAFC,stroke:#64748B,color:#0F172A,stroke-width:1px;
class BR,A,B,C,D,E,F,G root;
class R1,R2,R3,R4,R5 repo;
4.1 为什么这是正确道路
Base Repo满足多repo AI实践的几个关键要求：
| 要求 | Base Repo怎么满足 |
|---|---|
| 纳入所有代码 | 所有repo克隆到统一repos/区域 |
| 无侵入 | 不改变原repo结构、权限、发布 |
| 快速搭建 | 一个root repo加一个clone脚本即可 |
| 工具友好 | Cursor、Claude Code、Codex、GitHub Copilot都可以从root打开 |
| 渐进迁移 | 先纳入核心repo，再逐步扩展 |
| 支持知识沉淀 | 文档、RAG材料、结构化知识都可以放在root |
| 支持扩展能力 | MCP、skill、rule、subagent、workflow都可以按目录约束 |
| 架构稳定 | 新AI特性通过新增目录、配置和脚本承接，不改核心结构 |
它的重点不是“把代码合并”，而是“把AI工作入口合并”。
也就是说，Base Repo不是为了某一个AI工具临时搭的脚手架，而是一个业务架构层面的承接面。产品可以继续变化，AI工具可以继续变化，但系统入口、知识组织、workflow和权限边界应该保持稳定。
flowchart LR
A["原始多repo"] --> B["不改代码边界"]
A --> C["不改权限模型"]
A --> D["不改发布流程"]
B --> E["增加Base Repo"]
C --> E
D --> E
E --> F["AI看到统一上下文"]
E --> G["团队本地结构一致"]
E --> H["跨repo工作流可复制"]
E --> I["新AI能力只加扩展"]
classDef keep fill:#F8FAFC,stroke:#64748B,color:#0F172A,stroke-width:2px;
classDef add fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
classDef value fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class B,C,D keep;
class E add;
class F,G,H,I value;
4.2 Base Repo包含什么
Base Repo至少应该包含这些东西：
- 默认上下文说明文件：
AGENTS.md - 初始化步骤或脚本：
clone-repos.sh - 结构说明：告诉AI每个repo是什么
.gitignore：排除业务repo区域- 文档：系统架构、接口契约、业务知识
- 项目级知识库：按领域、系统、版本渐进加载
- OpenSpec和需求仓库：按版本沉淀所有开发需求
- MCP：只在这个目录下启用的外部系统连接
- skill、rule、subagent：这个系统专属的AI能力
- 脚本基建：build、test、clean、工程生成、归档、索引更新
- workflow说明：跨repo出码、review、测试、PR规范
AI不会主动扫一个5G的大目录，然后自然理解你的系统。
你必须给它结构化入口。
mindmap
root((Base Repo))
上下文
AGENTS.md
README.md
系统结构图
代码
repos
前端
移动端
后端
共享库
知识
文档
接口说明
业务规则
渐进加载
版本归档
RAG材料
工具
MCP
skills
rules
subagents
scripts
工作流
OpenSpec
分支规范
CR规范
测试矩阵
PR合集
使用之后，团队会获得三个直接收益：
- 所有人本地repo结构完全一致。
- 所有人的AI都可以访问完整系统仓库。
- 单个workspace中可以执行跨repo变更。
5. 搭建步骤
5.1 创建Base Repo
先创建一个新的root仓库。
mkdir company-platform-root
cd company-platform-root
git init
这个仓库不直接提交业务代码，只提交工作入口、系统说明、知识库、OpenSpec、workflow、配置和脚本。业务代码仍然克隆在repos/下，并由各自repo独立管理。
5.2 定义目录结构
没有唯一标准。先放必要内容，后面需要什么再加什么。
company-platform-root/
├── .gitignore
├── AGENTS.md
├── clone-repos.sh
├── mcp-config.json
├── README.md
├── docs/
│ ├── architecture.md
│ ├── api-contracts.md
│ └── workflows.md
├── knowledge/
│ ├── index.md
│ ├── domains/
│ ├── systems/
│ └── archive/
├── openspec/
│ ├── specs/
│ ├── proposals/
│ └── changes/
├── versions/
│ ├── 1.1.0/
│ │ ├── index.md
│ │ └── requirements/
│ └── archive/
├── scripts/
│ ├── install/
│ ├── verify/
│ ├── archive/
│ └── index/
├── skills/
├── rules/
├── subagents/
└── repos/
└── .gitkeep
repos/目录用于存放克隆出来的业务repo。
knowledge/用于放项目级知识库，openspec/用于放规格和变更提案，versions/用于按版本管理需求和内部系统链接，scripts/用于沉淀确定性执行脚本。
flowchart TB
ROOT["company-platform-root"] --> CTX["AGENTS.md<br/>默认上下文"]
ROOT --> INIT["clone-repos.sh<br/>初始化"]
ROOT --> MCP["mcp-config.json<br/>外部系统连接"]
ROOT --> DOC["docs/<br/>结构化知识"]
ROOT --> KB["knowledge/<br/>项目级知识库"]
ROOT --> SPEC["openspec/<br/>规格和变更"]
ROOT --> VER["versions/<br/>需求版本归档"]
ROOT --> SCRIPTS["scripts/<br/>确定性脚本"]
ROOT --> AIEXT["skills / rules / subagents<br/>AI扩展能力"]
ROOT --> REPOS["repos/<br/>业务代码区"]
REPOS --> FE["frontend"]
REPOS --> IOS["ios"]
REPOS --> AND["android"]
REPOS --> API["api-service"]
REPOS --> SDK["shared-sdk"]
REPOS --> INFRA["infrastructure"]
classDef root fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef part fill:#F8FAFC,stroke:#64748B,color:#0F172A,stroke-width:1px;
class ROOT root;
class CTX,INIT,MCP,DOC,KB,SPEC,VER,SCRIPTS,AIEXT,REPOS,FE,IOS,AND,API,SDK,INFRA part;
5.3 配置.gitignore
root repo不应该跟踪repos/下的业务仓库。
最简单可以这样写：
repos/
如果希望保留repos/空目录，可以写成：
repos/*
!repos/.gitkeep
这样root repo只提交协调层文件，不会把业务repo内容提交进去。
5.4 在默认上下文中关联系统说明
核心文件是AGENTS.md。
它不是“项目介绍”，而是AI的系统地图。
可以先写成这样：
# 系统架构与AI协作说明
## 总览
这个workspace是公司业务系统的Base Repo。
所有业务repo都会克隆到`repos/`目录下。
AI在处理跨repo需求时，必须先阅读本文件，再判断需要访问哪些repo。
## 仓库分层
### 后端服务
- `repos/user-service`：用户、登录、权限、用户资料
- `repos/order-service`：订单、履约、订单状态
- `repos/payment-service`：支付、退款、对账
### 前端应用
- `repos/admin-web`：管理后台
- `repos/customer-web`：用户侧网页
### 移动端
- `repos/ios-app`：iOS Native代码和Bridge
- `repos/android-app`：Android Native代码和Bridge
### 共享库
- `repos/shared-api-client`：接口client和类型
- `repos/shared-ui`：Web组件库
- `repos/mobile-bridge`：端Bridge协议
### 基础设施
- `repos/infrastructure`：部署、网关、K8s、Terraform、CI/CD
## 跨repo开发原则
1. 先识别受影响repo，不要直接改代码。
2. 按依赖关系从底层到上层修改。
3. API契约变化后，必须同步更新client和端侧调用。
4. 移动端Bridge变化时，必须同时检查iOS、Android和前端调用方。
5. 出码前先给出跨repo方案，说明每个repo要改什么。
## 测试和质量
1. 每个被修改repo都要运行对应测试或类型检查。
2. 跨repo功能必须写清楚联调路径。
3. 所有PR必须互相引用。
4. 涉及非负责仓库时，只能提交review请求，不要默认合入。
AGENTS.md里至少要包含：
- 后端
- 前端
- 移动端
- 共享库
- 基础设施
- 开发工作流
- 专属MCP
- skill/rule/subagent说明
- 测试规范
- CR规范
flowchart TD
TASK["用户提出需求"] --> READ["AI读取AGENTS.md"]
READ --> MAP["识别系统地图"]
MAP --> IMPACT["判断受影响repo"]
IMPACT --> PLAN["输出跨repo方案"]
PLAN --> HUMAN{"人确认方案？"}
HUMAN -- "通过" --> CODE["按依赖顺序出码"]
HUMAN -- "调整" --> PLAN
CODE --> VERIFY["逐repo验证"]
VERIFY --> PR["创建PR合集"]
classDef ai fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
classDef gate fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
classDef done fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class READ,MAP,IMPACT,PLAN,CODE,VERIFY ai;
class HUMAN gate;
class PR done;
5.5 编写install脚本
本质上就是把新人入职后“克隆所有repo”的流程固化下来。
最简单就是几十行git clone。
#!/usr/bin/env bash
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPOS_DIR="$ROOT_DIR/repos"
mkdir -p "$REPOS_DIR"
clone_repo() {
local name="$1"
local url="$2"
local branch="${3:-main}"
if [ -d "$REPOS_DIR/$name/.git" ]; then
echo "已存在，跳过: $name"
return
fi
echo "克隆: $name"
git clone -b "$branch" "$url" "$REPOS_DIR/$name"
}
clone_repo "admin-web" "git@github.com:company/admin-web.git" "main"
clone_repo "ios-app" "git@github.com:company/ios-app.git" "main"
clone_repo "android-app" "git@github.com:company/android-app.git" "main"
clone_repo "user-service" "git@github.com:company/user-service.git" "main"
clone_repo "order-service" "git@github.com:company/order-service.git" "main"
clone_repo "shared-api-client" "git@github.com:company/shared-api-client.git" "main"
clone_repo "infrastructure" "git@github.com:company/infrastructure.git" "main"
后面可以升级成：
- 按团队选择克隆哪些repo
- 自动检查权限
- 自动安装依赖
- 自动初始化MCP
- 自动生成本地配置
但第一版只要跑起来就可以。
5.6 这个系统的MCP
MCP容易踩坑。
最大的问题是：多个系统的MCP配置互相冲突。
正确做法是：只在Base Repo目录下启用这个系统专属的MCP。
flowchart LR
A["全局MCP"] --> X["容易污染所有项目"]
B["Base Repo目录级MCP"] --> C["只服务当前系统"]
C --> D["Git平台"]
C --> E["需求系统"]
C --> F["知识库"]
C --> G["数据库只读查询"]
C --> H["日志系统"]
classDef bad fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
classDef good fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class A,X bad;
class B,C,D,E,F,G,H good;
示例：
{
"mcpServers": {
"git-platform": {
"command": "npx",
"args": ["-y", "@company/git-mcp"],
"env": {
"GIT_TOKEN": "${GIT_TOKEN}"
}
},
"knowledge-base": {
"command": "npx",
"args": ["-y", "@company/kb-mcp"],
"env": {
"KB_TOKEN": "${KB_TOKEN}"
}
}
}
}
原则：
- 不要把所有MCP全局启用
- 不要把生产写权限交给AI
- 数据库和日志默认只读
- Token走环境变量
- 按系统隔离MCP配置
5.7 skill、rule、subagent
和MCP一样，skill、rule、subagent也应该按系统隔离。
这个Base Repo可以沉淀：
- 需求拆解skill
- 跨repo影响面分析skill
- API契约检查skill
- 移动端Bridge检查rule
- 后端review subagent
- 前端review subagent
- 测试验证subagent
flowchart TB
TASK["跨repo需求"] --> SKILL["需求拆解skill"]
SKILL --> PLAN["影响面分析"]
PLAN --> FE["前端subagent"]
PLAN --> BE["后端subagent"]
PLAN --> IOS["iOS subagent"]
PLAN --> AND["Android subagent"]
PLAN --> QA["验证subagent"]
FE --> REVIEW["跨repo Review"]
BE --> REVIEW
IOS --> REVIEW
AND --> REVIEW
QA --> REVIEW
REVIEW --> OUT["PR合集 + 测试说明"]
classDef skill fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef agent fill:#F3E8FF,stroke:#9333EA,color:#581C87,stroke-width:2px;
classDef out fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class SKILL,PLAN skill;
class FE,BE,IOS,AND,QA,REVIEW agent;
class OUT out;
第一阶段不一定要把这些都建完。
但目录和边界要先设计对：这个系统的能力放在这个系统的Base Repo里。
5.8 写README
README说明root repo怎么使用。
可以很简单：
# 公司业务系统Base Repo
这个仓库是AI coding assistant处理多repo任务的统一入口。
## 初始化
```bash
./clone-repos.sh
```
## 使用方式
1. 从本目录启动Cursor、Claude Code、Codex或GitHub Copilot。
2. 跨repo需求必须先阅读`AGENTS.md`。
3. 业务代码在`repos/`下各自repo中提交。
4. root repo只提交说明、脚本、MCP配置和工作流文档。
## 新增repo
1. 更新`clone-repos.sh`。
2. 更新`AGENTS.md`。
3. 更新相关workflow文档。
也可以直接把这篇文章的内部链接贴进去。
正常情况下，让AI自己写README就行。关键是：你要先把Base Repo的定位讲清楚。
5.9 知识库、OpenSpec和需求版本归档
Base Repo还有一个更重要的作用：它可以成为整个项目AI基建的管理仓库。
这里不只是放代码入口，也要放项目知识库、OpenSpec、workflow、需求版本归档、内部系统链接和脚本化基建。
flowchart TB
BR["Base Repo"] --> KB["项目级知识库<br/>knowledge/"]
BR --> SPEC["OpenSpec<br/>openspec/"]
BR --> WF["自定义workflow<br/>workflows.md"]
BR --> VER["版本需求归档<br/>versions/"]
BR --> LINKS["内部系统链接<br/>需求、设计、PR、CI、发布"]
BR --> INFRA["AI基建<br/>scripts / skills / rules / subagents"]
KB --> LOAD["渐进加载<br/>只让当前任务需要的知识进上下文"]
VER --> INDEX["版本索引<br/>1.1.0下有多少需求，一眼可见"]
VER --> ARCH["历史归档<br/>旧版本退出默认上下文"]
INFRA --> IOS["大型工程AI基建<br/>build/test/clean/工程生成脚本"]
classDef root fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef node fill:#F8FAFC,stroke:#64748B,color:#0F172A,stroke-width:1px;
classDef value fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class BR root;
class KB,SPEC,WF,VER,LINKS,INFRA node;
class LOAD,INDEX,ARCH,IOS value;
一个推荐目录可以这样设计：
company-platform-root/
├── knowledge/
│ ├── index.md # 当前可被AI默认索引的知识入口
│ ├── domains/ # 业务领域知识
│ ├── systems/ # 内部系统说明
│ ├── rag/ # 可以进入RAG或结构化检索的材料
│ └── archive/ # 旧知识，只保留grep搜索
├── openspec/
│ ├── specs/ # 稳定规格
│ ├── proposals/ # 进行中的提案
│ └── changes/ # 已确认变更
├── versions/
│ ├── 1.1.0/
│ │ ├── index.md # 这个版本的需求总索引
│ │ ├── REQ-001-group-note/
│ │ │ ├── spec.md # 需求规格
│ │ │ ├── links.md # PRD、设计稿、接口文档、内部系统链接
│ │ │ ├── workflow.md # 本需求的AI执行流程
│ │ │ ├── repos.md # 涉及哪些repo
│ │ │ ├── prs.md # PR合集
│ │ │ └── archive.md # 完成后的归档摘要
│ │ └── REQ-002-profile/
│ └── archive/
│ └── 1.0.0/
├── scripts/
│ ├── install/
│ ├── verify/
│ ├── archive/
│ ├── index/
│ └── ios-infra/
└── workflows/
├── feature-development.md
├── ai-code-review.md
└── release-archive.md
这里有几个关键点。
第一，所有开发中的需求都要按照版本进入versions/目录。比如1.1.0这个文件夹中包含多少个需求，每个需求有哪些内部系统链接、涉及哪些repo、产出了哪些PR，都应该有索引。
第二，每个需求完成后，要按照脚本号或需求号归档。比如REQ-001-group-note完成后，archive.md里只留下最终摘要、关键链接、涉及repo、验证结果和PR合集。
第三，超过一定版本的旧文档不再进入默认上下文索引。比如定义“5个版本之前的文档”直接移动到versions/archive/和knowledge/archive/，同时从knowledge/index.md和AGENTS.md的默认索引里移除。
第四，归档不等于删除。旧文档可以被知识库吸收，也可以保留为只读资料。默认情况下AI不会加载它们，但人和AI仍然可以用grep、rg或专门的检索脚本搜索到。
flowchart LR
A["开发中需求<br/>versions/1.1.0"] --> B["完成开发"]
B --> C["生成归档摘要<br/>archive.md"]
C --> D["进入当前版本索引<br/>index.md"]
D --> E{"是否超过5个版本？"}
E -- "否" --> F["保留默认索引"]
E -- "是" --> G["移出默认上下文索引"]
G --> H["沉入knowledge/archive"]
H --> I["只通过grep/RAG/检索脚本查找"]
classDef active fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
classDef archive fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
classDef cold fill:#F8FAFC,stroke:#64748B,color:#0F172A,stroke-width:1px;
class A,B,C,D,F active;
class G,H archive;
class I cold;
这套机制本质上是在做“上下文冷热分层”：
| 层级 | 位置 | 是否默认进上下文 | 访问方式 |
|---|---|---|---|
| 当前任务 | versions/current/或当前版本需求目录 | 是 | AGENTS.md、OpenSpec、workflow |
| 近几个版本 | versions/1.x.x/ | 按需 | 版本索引、需求索引 |
| 旧版本归档 | versions/archive/ | 否 | rg、grep、归档脚本 |
| 长期知识 | knowledge/ | 按索引进入 | 知识库索引、RAG |
| 冷知识 | knowledge/archive/ | 否 | 手动搜索 |
这里需要再强调一次：Base Repo不是一个“文档目录”，而是一套AI基建控制面。
多repo工程里的AI基建可以拆成四层：常驻上下文、渐进加载、隔离执行、确定性脚本。这个分层不依赖某一种端技术；Web、iOS、Android、后端服务、基础设施都可以按这个方式组织。
- 常驻上下文：
AGENTS.md，只放系统级高频规则。 - 渐进加载：
knowledge/index.md、rules/、skills/按场景或路径加载。 - 隔离执行：build、test、clean、archive等高日志任务交给subagent。
- 确定性脚本：工程生成、版本归档、索引更新、PR合集生成都交给
scripts/。
flowchart TB
subgraph L1["常驻层"]
A["AGENTS.md<br/>系统地图 + 默认规则"]
end
subgraph L2["渐进加载层"]
B["knowledge/index.md<br/>知识库入口"]
C["rules / skills<br/>场景和路径规则"]
D["OpenSpec<br/>当前需求规格"]
end
subgraph L3["隔离执行层"]
E["subagents<br/>build / test / clean / archive"]
end
subgraph L4["确定性脚本层"]
F["scripts<br/>工程生成 / 索引更新 / 版本归档 / PR合集"]
end
A --> B
A --> C
B --> D
C --> E
D --> E
E --> F
classDef layer fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
class A,B,C,D,E,F layer;
这样，这个新仓库就不只是“多repo代码入口”，而是整个多项目工程的AI基建控制面。
6. 大项目中使用AI有什么不同
单repo中使用AI，主要是“让它帮我改代码”。
多repo中使用AI，重点变成“让它理解系统，然后按协作流程推进”。
flowchart LR
A["单repo AI"] --> A1["读局部代码"]
A1 --> A2["改文件"]
A2 --> A3["跑本地检查"]
B["多repo AI"] --> B1["读系统地图"]
B1 --> B2["判断影响面"]
B2 --> B3["给出跨repo方案"]
B3 --> B4["按依赖顺序出码"]
B4 --> B5["逐repo验证"]
B5 --> B6["生成PR合集"]
classDef simple fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
classDef complex fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
class A,A1,A2,A3 simple;
class B,B1,B2,B3,B4,B5,B6 complex;
大项目里，AI不应该直接从“写代码”开始。
正确顺序是：
- 读取系统说明
- 判断涉及哪些repo
- 识别依赖顺序
- 输出方案
- 人确认方案
- 再出码
- 再测试
- 再提交PR合集
也就是说，大项目里的AI不是一个补全工具，而是一个工程协作节点。
7. 多repo开发的正确协作方式
多repo开发原则上应该跟公司内部系统自动联动起来。
这不是说AI可以不受控地改所有代码，而是说AI应该能在一个正确的工作区中理解：
- 需求来自哪里
- 代码在哪些repo里
- 文档和契约在哪里
- 谁负责review
- 哪些测试必须跑
- PR如何关联
sequenceDiagram
participant PM as 需求/问题
participant AI as AI in Base Repo
participant KB as 文档/MCP/知识库
participant Repos as 多个业务repo
participant Human as 负责人/Reviewer
participant CI as 测试/CI
PM->>AI: 输入跨repo需求
AI->>KB: 读取规则、文档、历史知识
AI->>Repos: 搜索相关代码
AI-->>Human: 输出影响面和方案
Human-->>AI: 确认或调整
AI->>Repos: 按依赖顺序修改
AI->>CI: 运行验证命令
CI-->>AI: 返回结果
AI-->>Human: 生成PR合集和测试说明
这里的关键是：出码前必须先完成方案关联review。
尤其是不同repo由不同人负责时，AI应该先把方案穿插给相关owner看，而不是直接把所有repo改完再让大家收拾。
8. 唯一正确实践
在不迁移Monorepo的前提下，多repo工程的AI正确实践就是：
用Base Repo建立统一系统入口，并围绕它持续维护上下文、规范、工作流和质量校验。
8.1 持续维护系统上下文
系统变化时，必须同步更新AGENTS.md：
- 新增repo
- 更新API契约
- 记录新的工程模式
- 记录架构决策
- 更新跨repo工作流
还要持续做memory优化。
也就是把AI经常问、经常错、经常漏的上下文沉淀下来，让下一次不再重复解释。
flowchart LR
A["一次跨repo任务"] --> B["发现缺失上下文"]
B --> C["补充AGENTS.md"]
B --> D["补充docs"]
B --> E["补充skill/rule"]
C --> F["下一次任务更准确"]
D --> F
E --> F
F --> A
classDef loop fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
class A,B,C,D,E,F loop;
AGENTS.md越准确，AI assistant越容易做出正确判断。
8.2 明确的分支管理规范
最简单的规则：跨repo分支名全部一致。
例如：
feature/group-note-display-fix
不要出现这种情况：
IM repo: feature/group-note-fix
API repo: feature/group-note-display
iOS repo: feature/gorup-note-fix
Android repo: fix/group-note
不同人负责不同仓库时，错别字和命名不一致会让PR关联、CI验证、问题追踪都变复杂。
flowchart TB
TASK["同一个跨repo任务"] --> GOOD["统一分支名"]
TASK --> BAD["各repo分支名不一致"]
GOOD --> G1["PR易关联"]
GOOD --> G2["CI易识别"]
GOOD --> G3["问题易追踪"]
BAD --> B1["关联困难"]
BAD --> B2["容易漏PR"]
BAD --> B3["沟通成本上升"]
classDef ok fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
classDef bad fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
class GOOD,G1,G2,G3 ok;
class BAD,B1,B2,B3 bad;
8.3 workflow顺序规范
在不同repo中，要按照依赖关系从下向上迭代方案和出码。
推荐顺序：
共享工具 → API/后端 → 移动端Bridge → 端/前端 → 文档 → 基础设施
flowchart LR
A["共享工具<br/>types/schema/sdk"] --> B["API/后端<br/>contract/service/db"]
B --> C["移动端Bridge<br/>iOS/Android协议"]
C --> D["端/前端<br/>页面/交互/调用"]
D --> E["文档<br/>接口/联调说明"]
E --> F["基础设施<br/>部署/配置/监控"]
classDef layer fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px;
class A,B,C,D,E,F layer;
这个顺序不是绝对的，但原则是稳定的：
先改被依赖方，再改依赖方；先确定契约，再实现调用。
8.4 质量校验
多repo下，测试用例、CR和自动测试都可以提高“一遍OK”的概率。
Base Repo里应该维护一份验证矩阵。
| 层级 | repo | 验证命令 | 目的 |
|---|---|---|---|
| 后端 | user-service | `go test ./...` | 用户逻辑验证 |
| 后端 | order-service | `go test ./...` | 订单逻辑验证 |
| 共享库 | shared-api-client | `pnpm typecheck` | 类型契约验证 |
| Web | admin-web | `pnpm test` | 页面和交互验证 |
| iOS | ios-app | `xcodebuild test` | Native和Bridge验证 |
| Android | android-app | `./gradlew test` | Native和Bridge验证 |
AI完成变更后，至少要输出：
- 改了哪些repo
- 每个repo跑了什么验证
- 哪些验证没跑，为什么没跑
- 需要人工重点review哪里
flowchart TB
CODE["AI跨repo出码"] --> V1["后端测试"]
CODE --> V2["类型检查"]
CODE --> V3["端侧测试"]
CODE --> V4["前端测试"]
CODE --> V5["人工CR"]
V1 --> REPORT["验证报告"]
V2 --> REPORT
V3 --> REPORT
V4 --> REPORT
V5 --> REPORT
REPORT --> DECIDE{"是否可以提PR？"}
DECIDE -- "是" --> PR["PR合集"]
DECIDE -- "否" --> FIX["继续修复"]
FIX --> CODE
classDef verify fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
classDef done fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class V1,V2,V3,V4,V5,REPORT,DECIDE verify;
class PR done;
8.5 PR合集
多repo任务不要只看单个PR。
应该按日期或需求归档PR合集，罗列涉及到的repo。
示例：
# PR合集：群聊笔记展示异常修复
日期：2026-07-08
需求/问题：群聊笔记展示异常
## 相关PR
| repo | PR | 说明 | 依赖 |
|---|---|---|---|
| note-service | #123 | 修复笔记聚合接口 | 无 |
| shared-api-client | #45 | 更新笔记类型 | note-service#123 |
| im-web | #88 | 调整展示逻辑 | shared-api-client#45 |
| ios-app | #102 | 更新Bridge字段 | note-service#123 |
| android-app | #97 | 更新Bridge字段 | note-service#123 |
## 验证
- 后端接口测试已通过
- shared-api-client类型检查已通过
- Web页面验证已通过
- iOS/Android需要端侧负责人复核
flowchart TB
ISSUE["一个需求/问题"] --> SET["PR合集"]
SET --> P1["note-service#123"]
SET --> P2["shared-api-client#45"]
SET --> P3["im-web#88"]
SET --> P4["ios-app#102"]
SET --> P5["android-app#97"]
P1 --> P2
P2 --> P3
P1 --> P4
P1 --> P5
classDef set fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
classDef pr fill:#F8FAFC,stroke:#64748B,color:#0F172A,stroke-width:1px;
class SET set;
class P1,P2,P3,P4,P5 pr;
8.6 更频繁地更新repo
多repo场景下，本地仓库越旧，冲突越多。
Base Repo应该提供一键更新脚本：
#!/usr/bin/env bash
set -euo pipefail
for dir in repos/*; do
[ -d "$dir/.git" ] || continue
echo "更新 $dir"
git -C "$dir" pull --ff-only
done
目标是：
- 更少的冲突频率
- 更轻的冲突处理成本
- AI总是在相对新的上下文中工作
8.7 管理AI基建，而不是堆文档
Base Repo里一定会慢慢沉淀大量材料：需求、PRD、设计稿、接口文档、事故复盘、OpenSpec、workflow、脚本、review记录。
如果不管理，这个仓库很快会变成另一个“巨大的上下文垃圾场”。
正确做法是把它当成AI基建来治理。
flowchart TB
A["新需求进入"] --> B["创建OpenSpec提案"]
B --> C["写入版本目录<br/>versions/1.1.0/REQ-xxx"]
C --> D["补充内部系统链接<br/>PRD/设计/接口/工单"]
D --> E["绑定workflow<br/>开发/验证/CR/发布"]
E --> F["AI按索引渐进加载"]
F --> G["完成后脚本归档"]
G --> H["更新版本index"]
H --> I["超过保留窗口后<br/>退出默认上下文"]
classDef active fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
classDef archive fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
class A,B,C,D,E,F active;
class G,H,I archive;
推荐规则：
- 当前版本需求默认可索引。
- 最近5个版本保留版本索引，但不一定全部进入上下文。
- 5个版本之前的文档进入
archive/，并从默认索引中移除。 - 归档文档只通过
rg、grep、RAG或专门检索脚本查找。 - 每个需求必须有
links.md，保存所有内部系统关联链接。 - 每个需求必须有
workflow.md，说明AI应该怎么跑这类需求。 - 每个版本必须有
index.md，列清楚这个版本包含多少需求、状态如何、涉及哪些repo。
版本索引可以长这样：
# 版本 1.1.0
## 需求列表
| 需求号 | 名称 | 状态 | 涉及repo | 链接 |
|---|---|---|---|---|
| REQ-001 | 群聊笔记展示修复 | 已完成 | im-web、note-service、ios-app、android-app | ./REQ-001-group-note/links.md |
| REQ-002 | 用户资料手机号字段 | 开发中 | user-service、shared-api-client、admin-web | ./REQ-002-profile/links.md |
## 当前版本默认进入上下文的材料
- ./REQ-001-group-note/archive.md
- ./REQ-002-profile/spec.md
- ./REQ-002-profile/workflow.md
这样做的价值是：AI不用每次重新理解历史，也不会被所有历史拖垮。
当前需求拿当前上下文，近版本拿索引，旧版本只在需要时搜索。
9. 前后对比
9.1 使用Base Repo之前
flowchart TB
U["用户提出跨repo需求"] --> A["AI只打开单repo"]
A --> B["局部搜索"]
B --> C["局部修改"]
C --> D["集成失败"]
D --> E["人工补上下文"]
E --> F["再开新session"]
F --> B
classDef bad fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px;
class A,B,C,D,E,F bad;
典型表现：
- 手动切换repo
- 手动复制上下文
- AI只能在单个repo内工作
- 容易遗漏跨repo依赖
- 简单变更也需要多轮解释
- 问题诊断容易修错位置
9.2 使用Base Repo之后
flowchart TB
U["用户提出跨repo需求"] --> A["AI从Base Repo启动"]
A --> B["读取AGENTS.md"]
B --> C["判断影响面"]
C --> D["输出跨repo方案"]
D --> E["人确认"]
E --> F["按依赖顺序修改"]
F --> G["逐repo验证"]
G --> H["PR合集"]
classDef good fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class A,B,C,D,E,F,G,H good;
变化点：
- 一个workspace包含所有核心repo
- AI有系统地图
- 可以跨repo追踪调用链
- 能按依赖关系出码
- PR和验证可以成套管理
- 新人也能用同一套结构理解系统
10. 注意事项
10.1 权限不要失控
大家申请非负责仓库权限时，应该以只读、报告问题、提交review建议为主。
也就是：
- 可以读
- 可以分析
- 可以提建议
- 可以提交PR
- 不默认拥有合入权限
AI也是一样。
它可以帮助跨repo分析和出码，但合入仍然要遵循原仓库owner和CR规则。
10.2 workflow中必须要求CR
多repoAI出码不能绕过CR。
尤其涉及这些内容时：
- 权限
- 支付
- 用户隐私
- 数据库写入
- 端Bridge
- 基础设施
- 灰度和开关
必须由对应owner review。
10.3 独立负责项目可以穿插方案review
不同repo仍然可以独立负责。
Base Repo不是要打破责任边界，而是让AI在出码前能把方案关联起来。
正确方式：
- AI先输出跨repo影响面。
- 各repo owner先review方案。
- 方案确认后再出码。
- 出码后再做代码CR。
flowchart LR
PLAN["跨repo方案"] --> O1["前端owner review"]
PLAN --> O2["后端owner review"]
PLAN --> O3["移动端owner review"]
PLAN --> O4["基础设施owner review"]
O1 --> OK{"方案通过？"}
O2 --> OK
O3 --> OK
O4 --> OK
OK -- "通过" --> CODE["AI出码"]
OK -- "调整" --> PLAN
CODE --> CR["代码CR"]
CR --> MERGE["按repo独立合入"]
classDef gate fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px;
classDef done fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px;
class OK,CR gate;
class MERGE done;
10.4 文档也是代码
无代码的知识也要包含进Base Repo。
不适合分散在各自仓库的系统知识，可以沉到Base Repo：
- 业务流程
- 接口文档
- 架构图
- 领域词汇
- 端Bridge协议
- 事故复盘
- 联调指南
- 常见问题
如果后续接RAG，也可以把这些材料作为结构化知识入口。
11. 总结
多repo工程的AI正确实践，是提供一种实用方式，让AI coding assistant在多repo系统中获得完整上下文，同时避免大规模monorepo迁移。
这个方案的关键点是：
- 创建一个协调层，也就是Base Repo。
- 用克隆脚本建立统一workspace。
- 用
AGENTS.md描述系统地图和协作规则。 - 用
knowledge/、openspec/、versions/管理项目知识、需求规格和版本归档。 - 用脚本、skill、rule、subagent承接大型工程里的AI基建。
- 保持原有repo独立，不改变已有发布和权限模型。
- 让AI assistant可以跨repo理解系统结构。
- 支持团队以统一方式搭建和使用AI工作区。
可以从最核心的几个repo开始，先建立简单的Base Repo和AGENTS.md，用一个真实跨repo任务验证效果，再逐步扩展到更多仓库、MCP、skill、rule、subagent和外部系统。
目标不是第一天就做到完美。
目标是先建立一个可维护的统一入口，让AI assistant不再只能基于单个repo猜测完整系统。
Base Repo的关键价值，是让AI能力变化变成“扩展问题”，而不是“重构问题”。新能力来了，就新增MCP、skill、workflow、脚本、索引规则或归档规则；核心业务repo、权限模型和发布流程不需要被反复打穿。
flowchart LR
A["第一步<br/>核心repo + AGENTS.md"] --> B["第二步<br/>真实任务验证"]
B --> C["第三步<br/>补齐workflow"]
C --> D["第四步<br/>接入MCP和skill"]
D --> E["第五步<br/>形成团队标准"]
classDef step fill:#E0F2FE,stroke:#0284C7,color:#0F172A,stroke-width:2px;
class A,B,C,D,E step;
最后一句话：
不要让AI在单个repo里猜系统。给它一个Base Repo，让它从系统入口开始工作。
