multi-repo

多仓库编排技能

目的

当功能跨越仓库边界时，协调多个仓库中的原子变更。跟踪依赖关系、管理关联 PR，并在破坏性变更传播之前检测出来。

何时使用此技能

适用于：

• 需要在多个仓库中协调更新的变更
• 管理仓库依赖图
• 创建需要一起合并或按顺序合并的关联 PR
• 检测会影响依赖仓库的破坏性变更
• 微服务或替代单体仓库的架构

不适用于：

• 单仓库变更（使用默认工作流）
• 分叉／同步操作（直接使用 git）
• 仅涉及文档的变更
• 不存在跨仓库依赖关系的变更

存储位置

所有多仓库数据均存储在 ~/.amplihack/.claude/data/multi-repo/ 中：

• dependencies.yaml - 仓库依赖图
• linked-prs.yaml - 当前活跃的关联 PR 集合
• breaking-changes.log - 已检测到的破坏性变更历史记录

依赖图格式

依赖图使用简单的 YAML：

# .claude/data/multi-repo/dependencies.yaml
version: "1.0"
repositories:
  my-org/api-server:
    depends_on: []
    exposes:
      - type: api
        name: REST API v2
        contract: openapi.yaml

  my-org/web-client:
    depends_on:
      - repo: my-org/api-server
        type: api
        version: ">=2.0"
    exposes: []

  my-org/mobile-app:
    depends_on:
      - repo: my-org/api-server
        type: api
        version: ">=2.0"
    exposes: []

核心操作

操作 1：初始化依赖图

何时： 首次设置多仓库跟踪时

流程：

1. 如果 ~/.amplihack/.claude/data/multi-repo/ 目录不存在，则创建该目录
2. 使用当前仓库创建初始的 dependencies.yaml
3. 提示输入已知依赖项（此仓库依赖的仓库）
4. 提示输入已知依赖方（依赖此仓库的仓库）
5. 保存并显示依赖图

命令： “初始化多仓库依赖关系”

操作 2：添加仓库依赖关系

何时： 注册新的依赖关系时

流程：

1. 读取当前的 dependencies.yaml
2. 验证两个仓库是否存在（通过 gh CLI）
3. 添加包含类型和版本约束的依赖项
4. 更新依赖方仓库的条目
5. 保存更改

示例：

"Add dependency: my-org/web-client depends on my-org/api-server for REST API"

操作 3：检测破坏性变更

何时： 创建会修改公共接口的 PR 之前

流程：

1. 识别当前分支中已更改的文件
2. 检查变更是否涉及对外公开的契约（API 规范、架构、导出项）
3. 在依赖图中查找依赖方
4. 对每个依赖方：
   • 克隆／获取最新代码（如果在本地，则使用 worktree）
   • 检查依赖方是否使用受影响的接口
   • 报告潜在的破坏
5. 生成影响报告

输出：

Breaking Change Impact Report
=============================
Changed: my-org/api-server/openapi.yaml
  - Removed endpoint: DELETE /users/{id}
  - Modified field: User.email now required

Affected Dependents:
  - my-org/web-client (uses DELETE /users/{id})
  - my-org/mobile-app (no impact detected)

Recommendation: Coordinate changes with my-org/web-client

操作 4：创建关联 PR

何时： 跨多个仓库进行原子变更时

流程：

1. 用户指定要更新的仓库集合
2. 按顺序处理每个仓库（遵循依赖图）：
   • 创建 worktree 或切换到对应仓库
   • 使用共同前缀创建功能分支
   • 进行更改
   • 创建 PR，并附上集合中其他 PR 的链接
3. 在 linked-prs.yaml 中跟踪关联 PR
4. 在 PR 描述中添加交叉引用

关联 PR 格式：

# .claude/data/multi-repo/linked-prs.yaml
linked_sets:
  - id: "auth-v2-migration"
    created: "2025-11-25T10:00:00Z"
    status: "pending"
    prs:
      - repo: my-org/api-server
        pr: 123
        status: "merged"
        merge_order: 1
      - repo: my-org/web-client
        pr: 456
        status: "approved"
        merge_order: 2
      - repo: my-org/mobile-app
        pr: 789
        status: "open"
        merge_order: 3

操作 5：协调合并顺序

何时： 合并一组关联 PR 时

流程：

1. 从 linked-prs.yaml 中读取关联 PR 集合
2. 确认所有 PR 均已获批／准备就绪
3. 按依赖顺序合并（先合并上游）
4. 每次合并后等待 CI 通过
5. 更新关联 PR 状态
6. 报告完成情况

合并顺序逻辑：

1. 没有依赖项的仓库最先合并
2. 有依赖项的仓库在其依赖项合并后再合并
3. 循环依赖：报错（健康的依赖图中不应存在循环依赖）

与 Worktree Manager 集成

跨本地仓库工作时，使用 worktree-manager agent：

1. 对依赖图中的每个本地仓库：
   • 使用 git worktree add 创建隔离的工作区
   • Worktree 位于 ./worktrees/{repo-name}-{branch}/
2. 在各个 worktree 中进行协调变更
3. 从各个 worktree 提交并推送
4. PR 合并后清理 worktree

与 PM Architect 集成

对于复杂的多仓库项目：

1. 使用 backlog-curator 跟踪跨仓库事项
2. 使用 workstream-coordinator 管理多仓库工作流
3. 将关联的 PR 映射到单个工作流事项
4. 将破坏性变更检测结果纳入路线图规划

理念契合

极致简洁：

• 基于 YAML 的依赖图（无需数据库）
• 利用现有的 git 和 gh CLI 工具
• 尽量精简技能的功能范围

杜绝废话，注重实效：

• 所有操作从第一天起即可使用
• 没有“计划中”的功能——只有当前可用的功能
• 破坏性变更检测会实际检查代码

模块化设计：

• 技能独立完整
• 数据以简单文件的形式存储
• 可独立使用，也可与 PM Architect 搭配使用

示例

示例 1：API 破坏性变更

**场景：**更新 API 端点签名

User: "I need to change the /users endpoint from GET to POST"

Skill Response:
1. Detected change to api-server/openapi.yaml
2. Scanned dependents:
   - web-client: Uses GET /users in 3 locations
   - mobile-app: Uses GET /users in 2 locations
3. Impact: HIGH - 5 usages across 2 repositories

Recommended approach:
1. Add POST /users endpoint (non-breaking)
2. Create linked PRs to update web-client and mobile-app
3. Deprecate GET /users with sunset date
4. Remove GET /users after clients migrate

示例 2：协同发布功能

**场景：**涵盖 3 个仓库的新身份验证流程

User: "Implement OAuth2 across api-server, web-client, and mobile-app"

Skill Response:
1. Created linked PR set: "oauth2-implementation"
2. Dependency order: api-server -> web-client, mobile-app (parallel)
3. Created branches:
   - api-server: feat/oauth2-backend
   - web-client: feat/oauth2-frontend
   - mobile-app: feat/oauth2-mobile
4. PRs created with cross-references:
   - api-server#123 (merge first)
   - web-client#456 (after #123)
   - mobile-app#789 (after #123)

局限性

• 依赖图按工作区划分（非集中式）
• PR 操作需要已通过身份验证的 gh CLI
• 破坏性变更检测采用启发式方法（可能会遗漏运行时变更）
• 不支持循环依赖（也不应存在循环依赖）

成功标准

• 跨仓库变更得到原子化协同
• 在破坏性变更引发生产问题之前检测出来
• PR 按正确的依赖顺序合并
• 团队能够了解跨仓库的影响