ビルダー・バリデーターエージェントチーム

問題: 並列で動く Claude Code のエージェントは速い。しかし、役割が明確でないと、出力のクオリティがバラバラになり、結局自分で全行をチェックする羽目になります。エージェント同士がお互いの成果物を評価し合える仕組みが必要です。

ネイティブのAgent Teamsをお探しですか? Claude Code にはマルチエージェント連携のためのAgent Teams機能が組み込まれました。この記事では、実験的な機能を有効にしなくても動作する、Task ツールを使ったDIYアプローチを解説します。

すぐに使えるヒント: 次のマルチファイルタスクに、このビルダー・バリデーターチェーンを貼り付けてみてください。バリデーターはビルダーの完了直後に読み取り専用で実行されます。

TaskCreate(subject="Build auth middleware", description="Create JWT validation middleware in src/middleware/auth.ts. Export verifyToken and requireAuth functions.")
TaskCreate(subject="Validate auth middleware", description="Read src/middleware/auth.ts. Verify: exports exist, error handling covers expired/malformed tokens, no hardcoded secrets. Report issues only. Do NOT modify files.")
TaskUpdate(taskId="2", addBlockedBy=["1"])

タスク2はタスク1が完了するまで待機します。バリデーターは読むだけで、書き込みは一切しません。エージェント2体。信頼できる出力1件。

なぜペアがソロより優れているか

エージェントの基本ではサブエージェントとは何かを解説しました。タスク配布では並列実行による速度向上を扱いました。サブエージェントのベストプラクティスではルーティングを扱いました。この記事では別のテーマを扱います。エージェントに役割を与え、チームとしてペアを組ませることです。

ソロエージェントには単純な欠点があります。コードを書いたエージェントが、そのコードのレビューに最も向いていないということです。同じ盲点、同じ前提、同じショートカットを持っています。独立したバリデーターを投入すれば、ビルダーが見落としたものを検出できます。バリデーターがゼロの状態から始めるからです。

人間のチームがコードの著者だけをレビュアーにしない理由と同じです。別の目を持つ人を連れてくるのです。

ビルダー・バリデーターパターン

ビルダーはコードを書きます。バリデーターはコードを読みます。この役割が交わることはありません。

ビルダーのプロンプト — 作成にスコープを絞る:

You are a builder agent. Your job:
 
1. Read the task description carefully
2. Implement the solution in the specified files
3. Run any relevant tests
4. Mark your task complete
 
Rules:
 
- Only modify files listed in your task
- Do not modify test files (validators handle test verification)
- If you hit a blocker, document it in the task description and mark complete

バリデーターのプロンプト — 検証にスコープを絞る:

You are a validator agent. Your job:
 
1. Read all files the builder created or modified
2. Check against the acceptance criteria in the task description
3. Run the test suite
4. Report findings as a new task if issues exist
 
Rules:
 
- Do NOT modify any source files
- Do NOT create new implementation code
- You may only create or update task entries to report issues
- Use Read and Bash (for tests) only - never Edit or Write

重要な制約: バリデーターはコードを書けません。これにより、本物の問題を表面化させることを強制し、こっそり修正してレビューを省略することを防ぎます。バリデーターが問題を発見した場合、ビルダーに戻すための新しいタスクを作成します。カスタムエージェント定義と disallowedTools を使ってツールレベルで強制することもできます。これによりバリデーターから Edit と Write を完全に取り除けます。

ビルドしてから検証するための依存チェーン

TaskUpdate の addBlockedBy パラメーターが、このパターンを結びつける要素です。バリデーターは追加の配線なしにビルダーを待ちます。

// Phase 1: Parallel builders
TaskCreate(subject="Build user API routes", description="Create CRUD endpoints in src/api/users.ts...")
TaskCreate(subject="Build user database schema", description="Create migration in src/db/migrations/...")

// Phase 2: Validators blocked by their builders
TaskCreate(subject="Validate API routes", description="Read src/api/users.ts. Verify REST conventions, error handling, input validation...")
TaskCreate(subject="Validate database schema", description="Read migration files. Verify column types, indexes, foreign keys...")

TaskUpdate(taskId="3", addBlockedBy=["1"])
TaskUpdate(taskId="4", addBlockedBy=["2"])

タスク1と2は別々のファイルに触れるため並行して実行されます。タスク3と4はそれぞれ自分のビルダーを待ちます。ビルドフェーズは並列で高速に。各出力は独立してチェック。

すべてのビルドが完了してから実行する横断的なチェックは、複数のブロッカーをスタックするだけです。

TaskCreate(subject="Integration validation", description="Verify API routes correctly reference the database schema. Check that all referenced tables and columns exist.")
TaskUpdate(taskId="5", addBlockedBy=["1", "2"])

チーム全体の計画を構築するメタプロンプト

タスクチェーンを手動で作るのは面倒です。CLAUDE.md にメタプロンプトを置いておけば、機能リクエストから即座にチーム計画全体を生成できます。

## Team Plan Generation
 
When I say "team plan: [feature]", generate a task structure:
 
For each component:
 
1. TaskCreate a builder task with specific files and acceptance criteria
2. TaskCreate a validator task scoped to read-only verification
3. TaskUpdate to chain validator behind its builder
 
After all component pairs, add one integration validator blocked by ALL builders.
 
Format each task description with:
 
- **Files**: exact paths to create or read
- **Criteria**: measurable acceptance conditions
- **Constraints**: what this agent must NOT do

こうすれば「team plan: Stripe webhook ハンドラーを追加」と言うだけで済みます。Claude が完全な依存グラフを返し、すべてのコンポーネントとバリデーターをペアにし、最後に統合バリデーターを配置します。計画を確認して、実行を指示するだけでエージェントが動きます。

これがオーケストレーターパターンの実例です。メインの Claude セッションが指揮を取ります。計画を作成し、ブロッカーを配線し、エージェントを送り出します。アプリケーションコード自体は手書きしません。

検証が失敗した場合

バリデーターが問題を発見した場合、ループが続きます。

バリデーターが何が壊れているかを示す修正タスクを登録する
ビルダーエージェントが修正タスクを拾う
新しいバリデータータスクが修正の後にチェーンされる

// Validator found missing error handling
TaskCreate(subject="Fix: add error handling to user API", description="The GET /users/:id endpoint returns 500 on invalid ID format. Add input validation and return 400 for malformed IDs.")
TaskCreate(subject="Re-validate user API error handling", description="Verify GET /users/:id returns 400 for non-UUID strings, 404 for valid UUID not found, 200 for valid existing user.")
TaskUpdate(taskId="7", addBlockedBy=["6"])

サイクルを重ねるごとにスコープが絞られます。最初のビルダーは機能全体を担当します。後のビルダーはバグ1件ずつを担当します。ループがコードを正しい方向へ導いていき、途中のデバッグを自分でやる必要がありません。

より厳しいチェックのために、フックをすべてのファイル変更時に自動ルールとして実行させれば、バリデーターエージェントが起動する前に問題を検出できます。バリデーションをエージェント定義に組み込むことで、品質チェックをエージェントのアイデンティティの一部にすることもできます。

まず1ペアから始めよう

ワークフロー全体を作り直す必要はありません。次に2ファイル以上に触れる機能を選んでください。ビルダータスクを1つ作成します。addBlockedBy 付きのバリデータータスクを1つ作成します。バリデーターがビルダーの見落としを指摘する場面を目撃してください。

一度機能することを確認したら、積み上げていけます。並列ビルダーにチェーンされたバリデーター、計画を書くメタプロンプト、すべてをまとめる統合バリデーター。明確な役割の境界を中心にエージェントのセットアップを構築しましょう。タスクシステムに順序を任せ、あなたは意思決定だけを担う。