Claude Code のマルチエージェント・ワークフロー：役割分担、隔離、手動レビュー

コードを自動マージする完全自律型の「AI エージェントチーム」は、気づきにくい設計上の欠陥、リファクタリングの循環、コードベースの劣化を招きがちです。並列に動く二つのエージェントが独立した真実を作るわけではありません。実装担当が論理的な誤りを犯した場合、似たプロンプトの前提で動くレビュー担当も見落とす可能性があります。

信頼できるマルチエージェント・ワークフローは、完全自律という幻想ではなく、厳格な役割分担の上に成り立ちます。実装する Author、独立して検証する Reviewer、そしてマージを最終判断する人間の開発者です。

1. 役割の境界：Author、Reviewer、人間の意思決定者

有効な開発ワークフローでは、各参加者に閉じた明確な責任範囲があります。

役割	主な責任	入力成果物	出力成果物
Author Agent	コード実装とローカルのユニットテスト	タスク記述、完了条件	Git ブランチ、diff、対象を絞ったテストスイート
Reviewer Agent	エッジケースの発見とリグレッション確認	Git diff、引き継ぎカード、検証コマンド	構造化レビュー・チェックリスト（Pass/Block）
人間の意思決定者	アーキテクチャの検証と最終マージ	Reviewer の要約、CI/CD の状態	`main` ブランチへの手動マージ

2. コンテキストとワークスペースの隔離

Author と Reviewer を同じ作業ディレクトリや同じ会話スレッドで動かしてはいけません。次の三つの運用レベルで隔離します。

セッションコンテキスト：独立した会話スレッドにより、相互のハルシネーションや循環的な追認を防ぎます。
ファイルシステムの隔離：別々の Git worktree を使うことで、Reviewer は未コミットの作業状態ではなく、確定した diff だけを確認できます。
環境の安全性：API キーと実行時認証情報は環境変数に保持し、プロンプト本文には決して渡しません。

worktree を準備するコマンド

git worktree add ../agent-author -b feat/payment-retry
git worktree add ../agent-reviewer feat/payment-retry

[!IMPORTANT]

API 設定：各 Claude Code セッションは、OS の環境変数で設定した専用の API 認証情報を使用します。現在の設定手順は BetterToken の Claude Code ドキュメントで確認してください。

3. 構造化された引き継ぎ契約

Author が実装を終えたら、簡潔な引き継ぎカードを作成します。生のチャット記録、秘密情報、未検証の仮定は厳密に除外します。

### Handoff Card

- **Task**: Add HTTP 429 retry support in payment client with exponential backoff.
- **Branch**: `feat/payment-retry`
- **Changed Files**: `src/client/http.ts`, `tests/http-retry.test.ts`
- **Verification Command**: `npm test -- tests/http-retry.test.ts` (Passed)
- **Risks & Blockers**: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- **Next Step**: Reviewer agent validates Retry-After header handling.

4. 人間が最終承認するプロトコル

Reviewer は隔離された環境で評価を行います。

クリーンな worktree ../agent-reviewer に移動します。
記録された検証コマンドを実行します。
副作用とエッジケースについて、独立して diff を調査します。
主担当エンジニア向けの構造化サマリーを作成します。

最終承認はエンジニアが行います。

Reviewer の所見を確認する。
main に対するリグレッションがないことを確認する。
手動でマージを実行する：git merge feat/payment-retry。

このパイプラインは相互追認のループを抑え、品質とアーキテクチャの責任を開発者の手に残します。