claude_code_agent_farm — Claude Code並列実行のオーケストレーション実践

はじめに

1つのタスクに1エージェント――その前提を覆すのが claude_code_agent_farm だ。数百ファイルにまたがるリファクタリング、テストスイートの一括修正、リント違反の全件対応。1セッションで順番に処理していては時間がかかりすぎる問題を、複数エージェントの並列実行で解決する。

claude_code_agent_farm（以下 Agent Farm）は、この「1エージェントの限界」に対する直接的な回答だ。複数の Claude Code エージェントを並列起動し、コードベース全体に対するバグ修正やベストプラクティスの適用を自動化するオーケストレーションフレームワークである。

本記事はシリーズ俯瞰記事「AIエージェントハーネスの時代」の「並列実行」カテゴリの詳細編にあたる。Agent Farm のアーキテクチャ、ワークフロー、導入手順を実践的に解説する。

注記: 本記事の情報は2026年4月時点のものであり、各リポジトリの機能・数値は変動する可能性がある。最新の情報は各リポジトリの README を参照してほしい。

claude_code_agent_farm とは

Agent Farm は、複数の Claude Code プロセスを tmux セッション上で並列実行し、それぞれのエージェントに独立したタスクを割り当てて管理する。単なる並列起動スクリプトではなく、重複排除、進捗追跡、協調制御、適応型の起動間隔制御を備えたフレームワークだ。デフォルトで20エージェントを起動し、設定で最大50まで拡張できる。

GitHub Stars は~781（2026-04-13時点）。作者は Jeffrey Emanuel 氏。

アーキテクチャ

Python + Shell の2スクリプト構成

Agent Farm の設計は、関心の分離を意識した2スクリプト構成になっている。

Python スクリプト（オーケストレーター）

メインのオーケストレーションを担う claude_code_agent_farm.py がコアだ。tmux セッションの作成、各エージェントの起動・停止、健全性監視（ハートビート、応答チェック）、リアルタイムダッシュボード、コンテキストウィンドウの自動クリア、HTML レポート生成が責務となる。エージェントごとに独立した tmux ペインを割り当て、定期ポーリングで全体の進捗を把握する。

Shell スクリプト（ビューアー）

表示とインタラクションに特化した view_agents.sh（130行）がレイヤーとして機能する。tmux のラッパーとして動作し、グリッド表示・フォーカスモード・分割表示・直接アタッチの4つの表示モードを提供する。

この分離により、オーケストレーター単体でのヘッドレス実行や、ビューアー単体での既存セッション監視といった柔軟な運用が可能になる。

単一ファイル設計

claude_code_agent_farm.py は2,991行の単一ファイルに全機能を集約している。パッケージ分割は行わず、pyproject.toml の wheel 設定でも packages = ["claude_code_agent_farm.py"] として単一ファイルをパッケージとして扱う設計だ。コードベース全体を1ファイルで追える利点がある一方、規模が大きくなるほど保守上のトレードオフが生じる設計でもある。

2層のロック機構

Agent Farm には性質の異なる2種類のロックが存在する。

Python レベル（コード実装）:

エージェントの起動時に設定ファイルが破壊されるのを防ぐロック機構だ。~/.claude/.agent_farm_launch.lock に排他的ファイル作成（os.O_CREAT | os.O_EXCL）でロックを取得し、cc コマンド送信後に解放する。30秒経過で stale と判定して自動削除する。また、.claude_agent_farm_state.json の読み書きには fcntl.flock による排他/共有ロックを使い、アトミックリネームと組み合わせて整合性を保つ。

LLM プロンプト駆動（実装なし）:

Cooperating Agents ワークフローの協調制御を担うロックだ。こちらはコードによる実装ではなく、プロンプトの指示文だけで動作する（詳細は後述）。

設計の意図として、確実性が要求される起動制御はコードで、柔軟な協調が要求される開発作業はプロンプトで——という使い分けが読み取れる。

3つのワークフロー

Agent Farm が提供するワークフローは3種類ある。用途に応じて設定ファイルを選択する。

バグ修正ワークフロー

型チェックやリンターの出力結果をインプットとして、各エージェントが個別のエラーを並列に修正する。

{
  "workflow": "bug-fix",
  "source": "mypy",
  "max_agents": 10
}

修正済みの問題には [COMPLETED] タグが付与され、他のエージェントが同じ問題に着手することを防ぐ。この重複排除の仕組みにより、エージェント数を増やしても無駄な作業が発生しない。チャンクサイズは max(10, total_lines / agents / 2) で動的に決まる。

ベストプラクティス実装ワークフロー

ガイドドキュメント（コーディング規約、セキュリティポリシーなど）をエージェントに読み込ませ、コードベース全体への段階的な適用を行う。各エージェントは担当範囲のファイルを処理しながら進捗追跡ドキュメント（@<STACK>_BEST_PRACTICES_IMPLEMENTATION_PROGRESS.md）に記録し、未処理のファイルから順に着手する。

マルチエージェント協調開発ワークフロー

複数のエージェントが同一リポジトリ上で協調して開発を進めるモードだ。ファイルの競合を防ぐため、/coordination/ ディレクトリを基点とした分散ロックシステムを使う。

このワークフローの仕組みとアーキテクチャ上の意義については、次節で独立して解説する。

プロンプト駆動の協調プロトコル

Agent Farm のアーキテクチャで最も注目すべき点の一つが、Cooperating Agents ワークフローの実装方法だ。

コード実装なしで実現する協調制御

このワークフローの分散ロック機構はPythonコードとして一切実装されていない。プロンプトファイル（prompts/cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt）に記述された自然言語の指示文だけで、LLM が自律的に協調プロトコルを解釈・実行する設計だ。

README はこの設計について次のように明言している：

"No actual code is needed to effectuate the system; rather, the LLM (particularly Opus 4) is simply smart enough to understand and reliably implement the system autonomously"

協調プロトコルの構造

プロンプトが各エージェントに指示する協調プロトコルは以下の構造を持つ。

プロジェクト内に /coordination/ ディレクトリを作成し、次のファイル群で協調状態を管理する：

/coordination/
├── active_work_registry.json     # 全エージェントの作業登録
├── completed_work_log.json       # 完了タスクのログ
├── planned_work_queue.json       # 着手待ちの作業キュー
└── agent_locks/                  # ファイル単位のロック
    └── {agent_id}_{timestamp}.lock

各エージェントは起動時に agent_{timestamp}_{random_4_chars} 形式のユニーク ID を生成する。作業着手前には active_work_registry.json と agent_locks/ を確認し、競合する作業を避ける。ロックが1〜2時間以上経過している場合は stale と判定して処理を進める（プロンプト内の記述ベース。コード実装なし）。

この設計の含意

LLM の自然言語理解を「協調制御の実装手段」として活用している点が、従来の並列処理フレームワークとの大きな違いとして読める。コード実装より柔軟な協調が可能になる一方、LLM の理解力に依存するため、モデルの変更時に挙動が変わる可能性がある点は留意が必要だろう。README が「particularly Opus 4」と特定モデルを名指ししているのも、このトレードオフの表れと読める。

導入手順

前提として以下が必要になる。

• Python 3.13+
• tmux
• git
• uv（Python パッケージマネージャ）
• Claude Code（cc='claude --dangerously-skip-permissions' エイリアスの設定が必須。全エージェントが権限チェックをスキップして動作するため、本番環境やセンシティブなリポジトリでの運用は十分に注意すること）

セットアップは以下の手順で進める。

git clone https://github.com/Dicklesworthstone/claude_code_agent_farm.git
cd claude_code_agent_farm
bash setup.sh

環境の整合性は doctor コマンドで確認できる。

claude-code-agent-farm doctor --path /your/project

問題がなければ、対象プロジェクトとワークフロー設定を指定して実行する。

claude-code-agent-farm \
  --path /your/project \
  --config configs/python_best_practices_config.json

設定テンプレートは configs/ に30を超えるテンプレートが用意されており、Python・Next.js・Go・Rust 等の言語に加え、Solana、Unreal Engine、Terraform、Kubernetes など多様なドメインをカバーしている。

運用上の注意点

トークン消費とコスト

多数のエージェントを並列実行すれば、トークン消費量はその分だけ増加する。各エージェントが独立したコンテキストウィンドウを持つため、実行時間に比例してコストが増加する。まずは3〜5エージェントで動作を確認し、タスクの粒度とコストのバランスを見極めてからスケールさせるのが現実的だ。

起動時のstagger適応

エージェントの起動間隔（stagger）は適応的に制御される。デフォルトの基準間隔は10秒で、前のエージェント起動が成功した場合は間隔を半減、失敗した場合は倍増する（最大60秒）。

current_stagger = min(current_stagger * 2, 60.0)  # 失敗時: 最大60秒まで倍増
current_stagger = max(current_stagger / 2, self.stagger)  # 成功時: 基準値まで半減

この制御の目的は API レートリミット対応ではなく、複数エージェントが同時に起動することで settings.json が破壊される（clobber）問題の回避だ。起動間隔を動的に調整することで、設定ファイルへの競合アクセスを防いでいる。

コンテキストウィンドウの管理

長時間実行時のコンテキスト肥大化に対して、閾値ベースの自動クリア機能が働く。使用量が設定値を超えるとセッションをリセットし、応答品質の劣化を防ぐ。

コントローラウィンドウで Ctrl+R を押すと、全エージェントに /clear をブロードキャストして一括リセットすることもできる。長時間実行中にコンテキストを手動でリセットしたい場合に便利だ。

アイドル判定のタイムアウトも適応的に調整される。過去のサイクル時間の中央値×3（30〜600秒の範囲）で決まる閾値を基準に、それを超えて応答がないエージェントをアイドルと判定し、再起動対象に含める。長いサイクルのタスク（大規模リファクタ等）で短い閾値のまま誤ってアイドル判定されることを避けるための仕組みだ。

自動復旧

--auto-restart オプションを有効にすると、ハートビートが120秒以上更新されないエージェントや、エラー状態・アイドル超過のエージェントを自動的に再起動する。再起動には指数バックオフが適用され、初回10秒から最大5分（min(300, 10 * (2 ** restart_count))）まで延長される。

設定バックアップとシャットダウン制御

実行開始時に Claude の設定ファイルをタイムスタンプ付きでバックアップする（.claude_agent_farm_backups/ に最大10個、200MB 制限でローテーション）。設定の破壊が検出された場合はバックアップから自動復元する。

Ctrl+C でグレースフルシャットダウン（処理完了後に停止）、3秒以内に2回押すとフォースキルが実行される。

HTML レポート

実行終了後に単一 HTML ファイルのレポートを生成する（generate_html_report() メソッド）。実行サマリー、エージェント別パフォーマンス、設定詳細を含み、Rich の Console(record=True) 方式でインラインスタイルを付与する。

ライセンス注記

Agent Farm は MIT ライセンスをベースとしつつ、OpenAI・Anthropic およびその関連企業（Affiliates）による利用を全面禁止する追加条項（Rider）を含む。ベンチマークや機械学習パイプラインへの組み込みも対象となる。利用前にリポジトリの LICENSE ファイルを確認することを推奨する。

参考リンク

• claude_code_agent_farm — 本記事で紹介したオーケストレーションフレームワーク本体
• AIエージェントハーネスの時代（シリーズ俯瞰記事） — Claude Code × Codex の2大エコシステムを俯瞰するシリーズ起点
• Claude Code エコシステム編 — Agent Farm を含む Claude Code 周辺ツール群の全体像
• Claude Code superpowers 入門 — サブエージェント・並列実行・Hooks など Claude Code 拡張機能の入門
• everything-claude-code 自律ループ編 — Claude Code の自律ループ設計パターンの解説
• Claude Code 公式ドキュメント — Anthropic による Claude Code の公式リファレンス

まとめ

Agent Farm は、Claude Code の並列実行を再現性のあるワークフローとして整備したツールだ。デフォルト20エージェント・設定で最大50という構成は、大規模コードベースの一括改善――型エラーの全件修正、コーディング規約の全ファイル適用、セキュリティパッチの横展開――において確かな威力を発揮する。

アーキテクチャ上の際立った特徴は、プロンプト駆動の協調プロトコルだ。コードを1行も書かずに LLM に分散ロック機構を自律運用させるアプローチは、LLM の自然言語理解を「制御ロジックの実装手段」として活用した設計だ。柔軟さと引き換えにモデル依存のリスクがあるという、LLM オーケストレーション特有のトレードオフが端的に現れている。

運用のポイントは、エージェント数とタスク粒度のバランスだ。並列数を増やせば速くなるが、コストと設定ファイル競合のリスクがある。少数エージェントで検証し、起動間隔（stagger）や設定を調整してからスケールさせるアプローチが、この種のツールを実用に乗せる近道になる。