シングルエージェントAIコーディングの限界
以前、50以上のエンドポイントを持つレガシーなNode.jsサービスのリファクタリングをAIアシスタントに任せようとして、4時間を無駄にしたことがありました。Swaggerドキュメントの更新とインテグレーションテストの作成を同時に行うよう指示したのですが、結果は散々でした。作業の途中でAIはデータベースのスキーマを忘れ、存在しない関数を呼び出し始め、ドキュメントはハルシネーション（もっともらしい嘘）の塊になってしまったのです。
これは、すべての開発者がいずれ直面する壁です1つのAIエージェントに複数の高度なタスクを同時にこなさせようとすると、「ワーキングメモリ」が不足してしまいます。プロジェクトが数千行のコードに成長するにつれ、出力の質は低下します。結局、機能をリリースするよりも、AIのデバッグに時間を費やすことになってしまうのです。
なぜコンテキストの飽和が生産性を下げるのか
問題はモデルの知能不足ではなく、「コンテキストの飽和」にあります。標準的なチャットでは、すべてのファイルの要約や指示が、限られた注意力の枠を奪い合います。リファクタリングとドキュメント作成を同時に要求すると、AIは複雑なロジックとフォーマット規則のバランスを保つことに苦労します。
大規模なリポジトリはノイズが多いものです。単一のエージェントは、無関係なヘルパーファイルに気を取られたり、特定のサブタスクへの集中を維持できなかったりすることがよくあります。些細なCSSの修正を、重要なAPIセキュリティの修正と同じ優先順位で扱ってしまうこともあります。プロフェッショナルな結果を得るには、これらのタスクを分解する必要があります。プロジェクト全体のノイズに煩わされない、専門化されたエンティティが必要なのです。
解決策：Claude Codeのサブエージェント
Claude Codeは、サブエージェントを使用することでこの問題を解決します。1つのインスタンスがすべてを行おうとするのではなく、メインのエージェントがプロジェクトマネージャーとして機能します。このマネージャーは、Claudeの一時的な専門バージョンを生成できます。各サブエージェントには狭いスコープと特定のツールセットが与えられ、1つの仕事を完璧に遂行します。
これは現実のエンジニアリングチームのようなものです。リードエンジニアは、ボイラープレートのコードを一行ずつすべて書くわけではありません。UIはフロントエンドのスペシャリストに、APIはバックエンドのエキスパートに委任します。サブエージェントは、この階層的な効率性をターミナルに直接もたらします。
クイックスタート：最初のサブエージェントを起動する
Claude Codeがインストールされていれば、複雑な設定は不要です。このツールは、タスクが一度に処理するには大きすぎると判断すると、自動的にサブプロセスの起動を提案するように設計されています。
これを実際に試すには、並列作業が必要なコマンドを実行してみてください。プロジェクトディレクトリでターミナルを開き、以下を実行します：
claude "auth.tsのユーザーバリデーションをリファクタリングしてください。その間、サブエージェントを使って新しいエンドポイントのMarkdownガイドを作成してください。"Claude Codeが別のタスクを初期化するのが確認できるはずです。UIには、ドキュメント作成を委任していることが表示されます。これにより、メインのエージェントはMarkdownの構文でメモリを汚染することなく、TypeScriptのロジックに集中し続けることができます。よりクリーンで高速な作業方法です。
また、より明示的に委任することも可能です：
claude "このプロジェクトをVitestに移行しています。既存の20個のJestテストを変換するためのサブエージェントを作成し、その間にpackage.jsonと設定ファイルの更新を手伝ってください。"委任の仕組み（内部構造）
Claude Codeがサブエージェントを作成するとき、単に新しいチャットウィンドウを開いているわけではありません。新鮮な実行コンテキストを構築します。このサブエージェントには、以下の3つの要素が与えられます：
- 明確なミッション： 外部のノイズを排除した、特定のプロンプト。
- スコープ限定のツール： ファイルシステムへのアクセス権。ただし、多くの場合、特定のフォルダに制限されます。
- 独立したコンテキスト： 無関係なファイルが見えないため、ハルシネーションが劇的に減少します。
私の経験上、Claude Codeを使いこなす秘訣は、直交するタスクを見極めることです。これらはロジックは重なりませんが、同じ機能に属するタスクです。例えば、Reactコンポーネントを作成する場合、メインのエージェントにロジックを担当させ、サブエージェントにツールセットを書かせます。これらを並列で動かすことで、開発時間全体を約30%削減できています。
高度なマルチステージ・ワークフロー
大規模な移行作業では、これらのやり取りを連鎖させることができます。私は複雑なタスクに対して「調査 -> 実行 -> 検証」というパターンを使っています。データベース移行のためのプロンプト構造の例を挙げます：
claude "TypeORMからPrismaに移行します。以下の手順に従ってください：
1. サブエージェントを生成して、15個のエンティティをprisma.schemaファイルにマッピングしてください。
2. スキーマの準備ができたら、一緒にレビューしましょう。
3. 次に、別のサブエージェントを生成して、リポジトリファイルを書き換えてください。
4. 最後に、サブエージェントを使用してビルドを実行し、型エラーを修正してください。"この構造により、「コンテキストの乖離」を防ぐことができます。AIは新しいPrismaのコードを書いている最中に、古いTypeORMの構文を覚えている必要はありません。各サブエージェントは、特定のステップだけに集中し、クリーンな状態で作業を開始します。
サブエージェントの追跡
サブエージェントの実行中、Claude CodeはCLI上でライブステータスを更新します。「Sub-agent working…」というアイコンや、特定のファイル操作が表示されます。ループに陥っているようであれば、プロセスを中断することも可能です。メインのエージェントを主な連絡窓口として扱いましょう。スペシャリストと直接話すのではなく、マネージャーに何をしたいかを伝えるのです。
エージェント管理のプロのコツ
委任は強力ですが、注意しないとコストがかさんだり、混乱を招いたりすることもあります。効率的なワークフローを維持するためのヒントを紹介します：
- 厳格な境界線を設定する： サブエージェントが触れるべきディレクトリを正確に伝えます。「/src/components内のファイルのみを変更してください」といったフレーズを使います。
- 引き継ぎをレビューする： サブエージェントが終了すると、マネージャーが作業内容を要約します。これを注意深く読んでください。もしサブエージェントが期待外れの結果を出した場合は、すぐに変更を元に戻しましょう。
- ループを止める： サブエージェントが同じコマンドを3回実行しても成功しない場合は、停止させてください。手動でヒントを与えて、軌道修正させます。
- コストを評価する： 各サブエージェントはトークンを消費します。2分で終わるタスクに使うのは過剰です。人間が20分以上かかるようなタスクのために取っておきましょう。
私は通常、ボイラープレートの作成、大量のデータ形式の変換、あるいは100以上のディレクトリにまたがるインポートの更新などにサブエージェントを使用します。これらのタスクはロジックは単純ですが、量が多いのが特徴です。まさに専門のエージェントが輝く場面です。委任という考え方に切り替えることで、Claude Codeを単なるチャットボットから、真の自律的なエンジニアリングパートナーへと変えることができるのです。
