- Claude Codeはマルチリポジトリ開発で横断的なコード変更・依存関係の追跡が可能
- CLAUDE.mdにリポジトリマップを記述することで、AIが文脈を正確に把握し精度が向上
- マイクロサービス間のAPI整合性チェックやスキーマ同期を自動化できる
「マイクロサービスが10個以上に分かれていて、API変更のたびに関連リポジトリを一つずつ修正するのが大変」——複数リポジトリで開発しているチームなら、誰もが感じる課題です。
Claude Codeは複数リポジトリを横断した開発作業を効率化する強力なツールです。 CLAUDE.mdにリポジトリマップを記述しておけば、リポジトリ間の依存関係を理解したうえでコード変更を提案してくれます。
この記事では、Claude Code完全攻略シリーズ Ep.61として、マルチリポジトリ開発における設定・運用・実践テクニックを網羅的に解説します。
- マルチリポジトリ開発でClaude Codeを活用するための準備と設定
- CLAUDE.mdによるリポジトリマップとコンテキスト設計
- マイクロサービス間のAPI整合性チェック自動化
- モノレポ vs マルチリポジトリの判断基準とClaude Codeの使い分け
- SES現場でのマルチリポジトリ案件における実践的ワークフロー
マルチリポジトリ開発の課題とClaude Codeの位置づけ
なぜマルチリポジトリ開発は難しいのか
マルチリポジトリ構成は、チームの独立性やデプロイの自由度を高める一方で、以下の課題を生みます。
- API契約の不整合: サービスAのレスポンス形式を変更したのに、サービスBのクライアントコードを更新し忘れる
- 依存関係の把握困難: どのリポジトリがどのリポジトリに依存しているか、全体像が見えにくい
- 横断的な変更のコスト: 共通スキーマの変更時、10個以上のリポジトリを順番に修正する必要がある
- テスト環境の整合性: 各リポジトリが異なるバージョンのライブラリを使っていて統合テストが失敗する
Claude Codeがマルチリポジトリ開発を変える
Claude Codeは単一リポジトリ内での作業ツールと思われがちですが、適切に設定すれば複数リポジトリを横断して文脈を理解し、整合性のとれたコード変更を提案できます。
具体的には次のようなワークフローが可能です。
- リポジトリAでAPIスキーマを変更 → Claude Codeがリポジトリ Bのクライアントコードに必要な変更を特定
- 共通ライブラリの更新 → 影響を受ける全リポジトリの変更点をリストアップ
- マイクロサービス間のインテグレーションテスト設計 → サービス境界を理解したテストケース生成
マルチリポジトリ向けCLAUDE.md設計
リポジトリマップの記述
マルチリポジトリ開発でClaude Codeを最大限活用するための鍵は、CLAUDE.mdにリポジトリマップを記述することです。
# CLAUDE.md - E-Commerce Platform
## リポジトリマップ
このプロジェクトは以下のマイクロサービスで構成されています:
### コアサービス
- `user-service` (Go) - ユーザー認証・プロフィール管理
- API: REST (OpenAPI 3.1)
- DB: PostgreSQL
- Port: 8001
- `product-service` (TypeScript/Node.js) - 商品カタログ管理
- API: GraphQL
- DB: MongoDB
- Port: 8002
- `order-service` (Java/Spring Boot) - 注文処理
- API: REST + gRPC
- DB: PostgreSQL
- Port: 8003
### 共通ライブラリ
- `shared-types` - TypeScript型定義（全フロントエンドで共有）
- `proto-definitions` - gRPCプロトコル定義
- `event-schemas` - Kafka/EventBridgeイベントスキーマ
### 依存関係
order-service → user-service (REST)
order-service → product-service (gRPC)
frontend → shared-types
全サービス → event-schemas (Kafkaイベント発行)このようにリポジトリ間の関係を明示しておくと、Claude Codeは変更の影響範囲を正確に推測できます。
コンテキストウィンドウを意識した設計
Claude Codeのコンテキストウィンドウには限りがあるため、複数リポジトリの情報を詰め込みすぎないことが重要です。
推奨アプローチ:
## 他リポジトリ参照のルール
- APIスキーマ変更時: `../proto-definitions/` を参照して整合性チェック
- 型定義の追加時: `../shared-types/src/` の既存型を確認
- イベント発行時: `../event-schemas/v2/` のスキーマに準拠
## このリポジトリ固有のルール
- テストカバレッジ80%以上を維持
- APIエンドポイント追加時はOpenAPI specを先に更新各リポジトリのCLAUDE.mdにはそのリポジトリ固有の情報を中心に記述し、他リポジトリとの連携ポイントだけを参照として記述するのがベストプラクティスです。
実践テクニック：マルチリポジトリでの作業パターン
パターン1: API変更の伝播
最も頻繁に発生するマルチリポジトリの作業パターンです。
ステップ1: API仕様の変更
# proto-definitionsリポジトリで作業
cd ~/projects/proto-definitions
claude "UserServiceのGetUserレスポンスにemail_verifiedフィールド（bool型）を追加してください。
後方互換性を維持し、既存フィールドのfield numberは変更しないでください。"ステップ2: 影響範囲の特定
# Claude Codeに影響分析を依頼
claude "proto-definitionsのUser messageにemail_verifiedを追加しました。
以下のリポジトリで必要な変更を特定してください:
- ../user-service (gRPCサーバー実装)
- ../order-service (gRPCクライアント)
- ../frontend (型定義の更新)
各リポジトリでの変更内容をファイル名と概要で一覧にしてください。"ステップ3: 各リポジトリでの実装
# user-serviceで実装
cd ~/projects/user-service
claude "proto-definitionsの更新に合わせて、GetUserレスポンスに
email_verifiedフィールドを含めるよう実装を更新してください。
DBスキーマのマイグレーションも生成してください。"パターン2: 共通ライブラリの一括更新
共有ライブラリのバージョンアップ時、全リポジトリを一括で更新するパターンです。
# ワークスペースルートで作業
cd ~/projects
claude "shared-typesパッケージのv2.3.0がリリースされました。
以下の変更があります:
- UserType enumにGUESTを追加
- OrderStatus enumからPENDINGを廃止（AWAITING_PAYMENTに統合）
以下のリポジトリで必要な更新を特定し、各リポジトリのpackage.jsonと
関連コードを修正するスクリプトを生成してください:
- frontend/
- admin-dashboard/
- order-service/"パターン3: クロスサービスのデバッグ
マイクロサービス間で発生するバグのデバッグにClaude Codeを活用するパターンです。
claude "以下のエラーが本番環境で発生しています:
order-serviceのログ:
'Error: user-service returned 404 for userId: abc123'
しかしuser-serviceのログではabc123のユーザーは正常に存在しています。
考えられる原因を分析してください。以下を確認してください:
1. order-serviceからuser-serviceへのリクエストパス構築ロジック
2. user-serviceのルーティング設定
3. API Gatewayやプロキシの設定"モノレポ vs マルチリポジトリの判断基準
Claude Codeでの使い分けマトリクス
| 判断基準 | モノレポ向き | マルチリポジトリ向き |
|---|---|---|
| チーム規模 | 50人以下 | 50人以上 |
| サービス数 | 10以下 | 10以上 |
| 言語の統一性 | 統一されている | バラバラ |
| デプロイ頻度 | 週1-2回 | サービスごとに異なる |
| Claude Code活用度 | 最大限活用可能 | 設定で補完が必要 |
| コンテキスト共有 | 自動で全体把握 | CLAUDE.mdで明示が必要 |
ハイブリッドアプローチ
現実的には、コアサービスはマルチリポジトリ、共通ライブラリはモノレポというハイブリッド構成が多く見られます。
projects/
├── shared-monorepo/ # モノレポ（共通ライブラリ群）
│ ├── packages/
│ │ ├── types/
│ │ ├── utils/
│ │ └── ui-components/
│ └── CLAUDE.md # モノレポ用の設定
├── user-service/ # 独立リポジトリ
│ └── CLAUDE.md # shared-monorepoを参照
├── order-service/ # 独立リポジトリ
│ └── CLAUDE.md
└── workspace-claude.md # ワークスペース横断設定Claude Codeでこのハイブリッド構成を扱う場合、ワークスペースルートに横断設定ファイルを置くのが効果的です。
マルチリポジトリでのCI/CD連携
Claude Codeを使ったPR自動レビュー
マルチリポジトリ環境では、一つのPRが他のリポジトリに影響を与える可能性があります。GitHub ActionsとClaude Codeを連携させたCI/CDパイプラインを構築することで、この問題を自動検知できます。
# .github/workflows/cross-repo-check.yml
name: Cross-Repository Compatibility Check
on:
pull_request:
paths:
- 'src/api/**'
- 'proto/**'
jobs:
compatibility-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Checkout dependent repos
run: |
git clone https://github.com/org/order-service ../order-service
git clone https://github.com/org/frontend ../frontend
- name: Run Claude Code compatibility analysis
run: |
claude --print "このPRで変更されたAPIスキーマが
../order-service と ../frontend に与える影響を分析し、
互換性の問題があればレポートしてください。"依存関係の自動更新フロー
# renovate.jsonやDependabotの設定と合わせて
# Claude Codeで依存関係の更新PRを自動生成
claude "shared-typesの最新バージョンv2.4.0に更新するPRを
以下のリポジトリそれぞれに作成してください:
- user-service
- order-service
- frontend
各PRには以下を含めてください:
1. package.jsonの更新
2. 型定義の変更に対応するコード修正
3. テストの修正
4. CHANGELOGの更新"マルチリポジトリ開発でのClaude Codeベストプラクティス
1. コンテキストの階層化
レベル1（常に読み込み）: 現在のリポジトリのCLAUDE.md
レベル2（必要時に参照）: リポジトリマップ（依存関係の概要）
レベル3（明示的に指示）: 他リポジトリの具体的なコード2. APIスキーマをSingle Source of Truthにする
マルチリポジトリ開発では、APIスキーマを一箇所で管理することがClaude Codeの精度を大きく左右します。
- OpenAPI仕様書: REST APIの場合
- Protocol Buffers: gRPCの場合
- GraphQL Schema: GraphQL APIの場合
- AsyncAPI: イベント駆動アーキテクチャの場合
## CLAUDE.md内の参照設定
APIスキーマは以下のリポジトリで一元管理:
- REST API: https://github.com/org/api-specs
- gRPC: https://github.com/org/proto-definitions
- Events: https://github.com/org/event-schemas
コード変更時は必ず上記スキーマとの整合性を確認すること。3. 変更ログの統一フォーマット
複数リポジトリにまたがる変更を追跡するため、統一されたコミットメッセージとCHANGELOGフォーマットを定めましょう。
feat(user-service): add email_verified field to GetUser response
Related changes:
- proto-definitions#123: Add email_verified to User message
- order-service#456: Update user client to handle new field
- frontend#789: Display email verification status
Breaking: No4. ワークスペース横断のサブエージェント活用
Claude Code SDKのサブエージェント機能を使えば、複数リポジトリの変更を並列で実行できます。
// ワークスペース横断更新スクリプト
import { claudeCode } from '@anthropic-ai/claude-code';
const repos = ['user-service', 'order-service', 'frontend'];
const results = await Promise.all(
repos.map(repo =>
claudeCode({
prompt: `${repo}のdependenciesを[email protected]に更新し、
破壊的変更への対応コードを生成してください`,
options: {
cwd: `/projects/${repo}`,
maxTurns: 10
}
})
)
);SES現場でのマルチリポジトリ案件の実務
マルチリポジトリ案件の典型的な構成
SES案件でマルチリポジトリ構成に出会うのは、主に以下のような現場です。
- 大規模Webサービス: フロントエンド、BFF、バックエンドAPI、バッチ処理がそれぞれ独立
- 金融系システム: セキュリティ要件により各コンポーネントが隔離されている
- EC/小売り系: 商品管理、在庫管理、決済、配送が別チーム別リポジトリ
参画初日のセットアップ戦略
新しいSES現場に参画した初日に、Claude Codeを使ってマルチリポジトリ環境を素早く理解する方法です。
# 1. 全リポジトリをクローン
for repo in user-service order-service product-service frontend; do
git clone [email protected]:client-org/$repo.git
done
# 2. Claude Codeでアーキテクチャ俯瞰図を生成
claude "以下のリポジトリの構成を分析し、
アーキテクチャの全体像をMarkdownで整理してください:
- user-service/
- order-service/
- product-service/
- frontend/
各サービスの言語、フレームワーク、DB、API形式、
サービス間の依存関係を一覧にしてください。"
# 3. CLAUDE.mdを生成
claude "分析結果をもとに、各リポジトリのCLAUDE.mdを生成してください。
リポジトリマップと依存関係を含めてください。"スキルセットと単価の目安
マルチリポジトリ・マイクロサービス開発のスキルを持つSESエンジニアの単価は、一般的なWeb開発案件と比較して高い傾向にあります。
| スキルレベル | 単価目安（月額） | 求められるスキル |
|---|---|---|
| ジュニア | 55〜70万円 | 単一サービスの開発・保守 |
| ミドル | 70〜90万円 | 複数サービスの連携開発 |
| シニア | 90〜120万円 | アーキテクチャ設計・全体最適化 |
| リード | 120〜150万円 | 技術選定・チーム横断調整 |
Claude Codeを活用してマルチリポジトリ開発の効率を上げられるエンジニアは、現場での評価が高く単価アップにもつながります。
スキーマ駆動開発とClaude Code
OpenAPIファーストのワークフロー
マルチリポジトリ環境での開発効率を最大化するには、スキーマファースト（API仕様を先に定義してからコードを実装する） アプローチが有効です。
# 1. OpenAPIスキーマを先に定義
claude "ユーザープロフィール更新APIのOpenAPI 3.1仕様を作成してください。
以下の要件を含めてください:
- PATCH /users/{userId}/profile
- リクエスト: displayName, bio, avatarUrl（いずれもoptional）
- レスポンス: 更新後のUserProfileオブジェクト
- エラー: 400, 401, 404, 422"
# 2. スキーマからサーバー/クライアントコードを自動生成
claude "作成したOpenAPIスキーマから以下を生成してください:
- user-service用のGoハンドラースケルトン
- frontend用のTypeScriptクライアント（axios利用）
- テスト用のモックデータ"イベントスキーマの管理
マイクロサービス間の非同期通信（Kafka、EventBridge等）でもスキーマ管理は重要です。
claude "以下のドメインイベントのAsyncAPI仕様を作成してください:
- UserCreated: ユーザー新規登録時に発行
- OrderPlaced: 注文確定時に発行
- PaymentCompleted: 決済完了時に発行
各イベントのペイロード定義と、
発行元サービス・消費先サービスの対応表も含めてください。"トラブルシューティング
よくある問題と解決方法
Q: Claude Codeが他のリポジトリのコードを読み込めない
- Claude Codeの作業ディレクトリが正しいか確認（
pwd） - 他リポジトリを相対パスで参照できる配置にする（
../other-repo/） - CLAUDE.mdに明示的なパスを記述する
Q: コンテキストが大きすぎてClaude Codeの応答が不正確になる
- リポジトリマップを要約版にする（詳細はリンク先を参照する形式）
- 一度に扱うリポジトリを2〜3個に制限する
- コンテキスト圧縮（Compaction）機能を活用する
Q: 複数リポジトリへの変更が一部だけマージされた
- CI/CDにクロスリポジトリの整合性チェックを組み込む
- GitHub Actions自動化でリンクされたPRのステータスを監視する
- APIバージョニング（
/v1/、/v2/）で後方互換性を担保する
まとめ — Claude Codeでマルチリポジトリ開発を加速する
Claude Codeは、マルチリポジトリ環境における開発効率を飛躍的に向上させるツールです。
マルチリポジトリ開発のポイント：
- CLAUDE.mdにリポジトリマップを記述して、Claude Codeにサービス間の関係を理解させる
- APIスキーマをSingle Source of Truthとして一元管理し、スキーマ駆動で開発を進める
- CI/CDに横断チェックを組み込み、リポジトリ間の不整合を早期発見する
- サブエージェントで並列処理し、複数リポジトリへの一括更新を自動化する
マイクロサービス開発のスキルとClaude Codeの活用力を組み合わせることで、SESエンジニアとしての市場価値を大きく高められます。Claude Codeのモノレポガイドやチーム開発ガイドと合わせて、あなたの開発ワークフローを最適化してください。
AI開発ツールを活用してエンジニアとしてのキャリアを加速させたい方は、SES BASE で最新のSES案件をチェックしてみてください。
