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 エージェントを活用します：

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 が依存関係の正しい順序でマージされます
• チームがリポジトリをまたぐ影響を把握できます