背景
複数のWebアプリケーションを1つのプラットフォームとして開発している。リポジトリは機能ごとに分かれていて、認証サーバー、共通UIライブラリ、各アプリケーション、ドキュメントなどで構成されている。
1人でこれを回すにあたって、Claude Codeをただのチャットツールではなく「開発チームの一員」として機能させるアーキテクチャを設計した。
全体構成
ワークスペース（親）
├── アプリA/ # Git Submodule
├── アプリB/ # Git Submodule
├── アプリC/ # Git Submodule
├── 認証サーバー/ # Git Submodule
├── 共通UIライブラリ/ # Git Submodule
├── CLAUDE.md # オーケストレーション設計
├── Makefile # 一括操作
└── .claudeignore # サブモジュール除外
ポイントは親ワークスペースでは設計とオーケストレーションだけ行い、実装は全て子Agentに委譲するという原則。
設計判断
1. コンテキスト分離
.claudeignore でサブモジュールを除外している。これにより:
- 親Agentのコンテキストウィンドウにサブモジュールのコードが入らない
- 親から
GrepやGlobしてもサブモジュール内はヒットしない - 各子Agentは自分のリポジトリだけを見る
なぜこうするのか: Claude Codeのコンテキストウィンドウは有限。6つのアプリのコードが全部入ると、肝心の設計判断に使える領域が圧迫される。
2. カスタムAgent定義
各サブモジュールに .claude/agents/ ディレクトリを用意し、カスタムAgentを定義している。子Agentは対象リポのCLAUDE.mdを読み、そのリポ内だけで作業する。
Agentツール:
subagent_type: "app-a"
prompt: "認証フローのバグを調査して修正して"
3. 並列実行パターン
同じ変更を複数リポに横展開するとき、Agentを並列で起動する。
Agent 1: subagent_type: "app-a" → "User型にteamIdフィールドを追加して"
Agent 2: subagent_type: "app-b" → "User型にteamIdフィールドを追加して"
Agent 3: subagent_type: "app-c" → "User型にteamIdフィールドを追加して"
3つ同時に走る。人間がやったら30分かかる横展開が、2-3分で終わる。
4. commit/pushは親から
子Agentには権限制約がある場合があるので、実装は子Agent、commit/pushは親から直接Bashで実行するルールにしている。これは設計上の判断でもある。コミットの粒度やメッセージは人間（またはオーケストレーターの親）がコントロールすべき。
カスタムコマンド
よく使うワークフローはカスタムコマンドとして定義している。
| コマンド | 用途 |
|----------|------|
| /commit | コンベンショナルコミット |
| /pr | PR作成 |
| /push-safe | セキュリティチェック付きpush |
| /review | AIコードレビュー |
| /fix-ci | CI失敗自動修正 |
| /overnight | 夜間自律実行 |
| /impl | 機能実装 |
| /explore-code | コードベース横断調査 |
特に /overnight は、寝てる間にAgentにタスクを任せるコマンド。朝起きたらPRが上がっている状態を作れる。
CLAUDE.mdの設計
CLAUDE.mdはAgentへの「業務マニュアル」。以下を書いている:
- ワークスペースの構成: 何がどこにあるか
- 認証アーキテクチャ: 認証方式、JWT、Cookie共有の仕組み
- ポート割り当て: 各アプリのローカルポート
- 行動原則: コーディングルール参照、段階的コミット、エラー自動回復のルール
- Agent委譲のルール: いつ子Agentに委譲し、いつ親で直接やるか
これを書くか書かないかで、Agentの出力品質が全く違う。
実感している効果
- 1人で6アプリ + 認証サーバー + 共通UIを回せている。物理的に不可能な作業量を可能にしている
- 横展開のコストがほぼゼロ。型変更、ライブラリ更新、設定変更を全リポに一括適用できる
- コンテキストスイッチが減る。Agentに「あのリポのあの機能を調べて」と投げれば、自分は別の設計作業を続けられる
まだ課題なこと
- Agentの出力品質の評価が人間依存。レビューAgentはあるが、最終判断は自分
- CI連携が手動。GitHub Actions上でClaude Codeを自動実行するHeadless運用はまだやれていない
- Agent間の依存関係の管理。「認証サーバーの変更→全アプリに反映」の順序制御はまだ手動
まとめ
Claude Codeは「便利なチャットツール」ではなく「プログラマブルな開発チーム」として扱える。そのためにはオーケストレーション設計が必要で、CLAUDE.md、カスタムAgent、.claudeignore によるコンテキスト分離がその基盤になる。
1人開発でも、この構成を組めば5-6人分の作業をこなせる実感がある。