一、 Monorepo 下 AI 开发的致命痛点（Why）

在 Monorepo（多个应用与多个共享库共存于同一代码仓库）环境下，如果缺乏严格的工程治理，AI 开发极易引发毁灭性的**“跨项目污染与隐式耦合”**：

1. 非法横向依赖（Cross-App Leaks）：
   • AI 在编写 apps/app-A 时，由于上下文检索到了 apps/app-B 中的现成函数或组件，会顺手编写 import ... from '../app-B'。这种行为会瞬间破坏应用的独立打包、版本发布与运行环境隔离。
2. 底层破坏性回折（Cascading Breakage）：
   • 当 AI 为了满足当前正在调试的应用需求而修改共享包 packages/core 时，往往忽略了仓库中其他依赖该包的子系统，导致意外引入破坏性变更（Breaking Changes）。
3. 上下文迷失与 Token 浪费（Context Pollution）：
   • 整个单库规模庞大，AI 检索代码时若缺乏边界约束，会将无关应用的同名文件或过时逻辑读入上下文，不仅迅速耗尽 Token 额度，还会诱发严重的代码幻觉。

因此，多项目 Monorepo 是最能发挥 AI 治理效力、也是最需要这套规则体系的工程场景。

---

二、 架构模型与目录骨架（How）

Monorepo 治理的核心哲学是：“全局定物理边界，局部定业务自治”。

推荐目录结构

my-monorepo/
├── AGENTS.md                          # 【全局公理】包管理工具(如 pnpm)、单向依赖流契约、跨项目引用禁令
├── .agents/
│   ├── notes/                         # 【全局基建 ADR】跨包共享协议、构建工具链升级、公用架构决策
│   │   ├── README.md
│   │   ├── proposed/
│   │   ├── implemented/
│   │   └── rejected/
│   └── skills/
│       └── affected-test/             # 引导 AI 仅跑 Affected 变动测试 (如 pnpm --filter ...[origin/main])
│           └── SKILL.md
│
├── apps/                              # 独立业务应用集
│   ├── web-portal/
│   │   ├── AGENTS.md                  # 【局部自治】Web 端专属技术栈规则、渲染策略与样式约束
│   │   └── .agents/notes/             # 该 Web 站点的专属功能演进与决策记录
│   └── mobile-app/
│       ├── AGENTS.md                  # 【局部自治】跨端/移动端专属状态管理与平台通信协议
│       └── .agents/notes/             # 移动端业务架构决策
│
├── packages/                          # 跨项目共享包/库
│   ├── ui/                            # 共享组件库
│   │   └── AGENTS.md                  # 声明式规约：严禁反向依赖任何 apps/ 下的业务代码
│   └── utils/                         # 通用基础工具
│       └── AGENTS.md
│
└── scripts/
    ├── check-boundaries.mjs           # 静态检测各 App 与 Package 之间的拓扑合法性
    └── check-agent-contracts.mjs      # 检查各子项目规则文档是否合规健全

---

三、 落地 Monorepo 的三大铁律

1. 严格的单向依赖契约（声明于 Root AGENTS.md）

• 垂直单向流：apps/* 仅可单向依赖 packages/*，绝对严禁反向依赖；
• 横向绝对隔离：apps/app-A 严禁直接依赖 apps/app-B；
• 公共逻辑抽包审查：当多个应用需要复用某逻辑时，必须显式抽取至 packages/*，并经过跨项目影响范围（Blast Radius）评估。

2. “就近加载”的局部上下文隔离（Local Context Isolation）

• 当 AI 在特定子项目（如 apps/web-portal/）中工作时，只加载当前子项目的 AGENTS.md 与根目录基础公理；
• 禁止 AI 检索和读取其他无关 App 的规则与历史 Notes，确保 Token 纯净、注意力高度聚焦、逻辑高内聚。

3. 机器代码门禁替代口头警告（Guardrails as Code）

• 依赖防腐阻断：在 CI 或预提交脚本中配置 dependency-cruiser 或 ESLint no-restricted-paths。一旦检测到跨 App 导入或反向依赖，构建立即报错阻断；
• 影响面增量验证（Affected Verification）：配合 Turborepo、Nx 或 pnpm filter 机制，编写专用的 affected-test Skill，引导 AI 仅执行受波及工程的增量测试（例如：pnpm test --filter=...[origin/main]），杜绝在单库中动辄运行全仓数万条测试。

---

四、 架构决策记录 (ADR) 的双层协同机制

在多项目单库中，ADR 应当分层维护，避免全局 Notes 臃肿杂乱：

层级	物理路径	记录范围与职责
全局 ADR	/.agents/notes/	影响全仓库的基础设施决策、Node/包管理器版本升级、跨包共享契约变更、通用依赖引入等。
应用局部 ADR	/apps/<app-name>/.agents/notes/	该业务应用内部的不可逆架构决策（如专属状态机演进、路由策略变更、独立 API 契约）。

---

五、 Monorepo 下 AI 验证与工作流标准

1. 增量测试引导技能（affected-test）

   • 告知 AI 如何精准获取自 origin/main 以来受影响的 Workspace；

   • 示例执行命令：

     # 基于 pnpm 过滤器执行受影响包的测试
     pnpm --filter "...[origin/main]" test

2. 纯文档修改免测机制
   • 若改动仅涉及 Markdown 文档、注释或非代码配置，严格豁免跨包构建与增量单测，防止 CI 资源与 Token 浪费。