agent-swarm-workflow

エージェントスウォームワークフロー — 並列実装

核心となる洞察： すべてのエージェントは代替可能なジェネラリストです。全員が同じベースモデルを使い、同じ AGENTS.md を読みます。単に「フロントエンドエージェント」と呼ぶだけで、フロントエンドの能力が高まるわけではありません。

スウォームは Agent Mail と Beads を通じて分散型かつ堅牢で、自己組織化されます。

---

前提条件

スウォームを開始する前に、次の準備を整えます。

1. 包括的な計画を作成する（planning-workflow スキルを参照）
2. 整備済みの beads を用意する（beads-workflow スキルを参照）
3. AGENTS.md にすべてのツールの説明を設定する
4. Agent Mail サーバーを起動する（am または ~/projects/mcp_agent_mail/scripts/run_server_with_token.sh）
5. セッション管理に NTM を使用できる状態にする

---

スウォームのアーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                         BEADS                               │
│     (Task graph with dependencies, priorities, status)      │
└─────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
┌─────────────────────────────┐  ┌─────────────────────────┐
│        BV                   │  │     AGENT MAIL          │
│  (What to work on)          │  │  (Coordination layer)   │
└─────────────────────────────┘  └─────────────────────────┘
         │                            │
         └──────────────┬─────────────┘
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                    NTM + AGENTS                             │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐     │
│  │ CC  │  │ CC  │  │ Cod │  │ Gmi │  │ CC  │  │ Cod │     │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘     │
└─────────────────────────────────────────────────────────────┘

---

スウォームの開始

NTM（Named Tmux Manager）を使用する

# Spawn a swarm with multiple agents
ntm spawn myproject --cc=3 --cod=2 --agy=1

# Send initial prompt to all Claude Code agents
ntm send myproject --cc "$(cat initial_prompt.txt)"

# Or send to all agents
ntm send myproject --all "$(cat initial_prompt.txt)"

手動セットアップ

プロジェクトフォルダー内に、各エージェント用の tmux セッション／ペインを作成します。

---

正確なプロンプト — エージェントへの初期指示

開始時に、各エージェントにこの正確なプロンプトを与えます。

First read ALL of the AGENTS dot md file and README dot md file super carefully and understand ALL of both! Then use your code investigation agent mode to fully understand the code, and technical architecture and purpose of the project. Then register with MCP Agent Mail and introduce yourself to the other agents.

Be sure to check your agent mail and to promptly respond if needed to any messages; then proceed meticulously with your next assigned beads, working on the tasks systematically and meticulously and tracking your progress via beads and agent mail messages.

Don't get stuck in "communication purgatory" where nothing is getting done; be proactive about starting tasks that need to be done, but inform your fellow agents via messages when you do so and mark beads appropriately.

When you're not sure what to do next, use the bv tool mentioned in AGENTS dot md to prioritize the best beads to work on next; pick the next one that you can usefully work on and get started. Make sure to acknowledge all communication requests from other agents and that you are aware of all active agents and their names.  Use ultrathink.

---

実装ループ

正確なプロンプト — 次の Bead に進む

エージェントが bead を完了したら、このプロンプトを使って次の作業に進ませます。

Reread AGENTS dot md so it's still fresh in your mind.   Use ultrathink.   Use bv with the robot flags (see AGENTS dot md for info on this) to find the most impactful bead(s) to work on next and then start on it. Remember to mark the beads appropriately and communicate with your fellow agents. Pick the next bead you can actually do usefully now and start coding on it immediately; communicate what you're working on to your fellow agents and mark beads appropriately as you work. And respond to any agent mail messages you've received.

正確なプロンプト — Bead 完了後のセルフレビュー

次に進む前に、エージェントに作業をレビューさせます。

Great, now I want you to carefully read over all of the new code you just wrote and other existing code you just modified with "fresh eyes" looking super carefully for any obvious bugs, errors, problems, issues, confusion, etc. Carefully fix anything you uncover. Use ultrathink.

バグが見つからなくなるまで、これを繰り返します。

---

コンテキストの圧縮への対応

正確なプロンプト — 圧縮後

エージェントがコンテキストを圧縮したら、すぐに次のプロンプトを送ります。

Reread AGENTS dot md so it's still fresh in your mind.   Use ultrathink.

これにより、ツールとワークフローに関する重要なコンテキストを再確立できます。

---

品質レビュー用プロンプト

正確なプロンプト — エージェント間レビュー

定期的に、エージェント同士で作業をレビューさせます。

Ok can you now turn your attention to reviewing the code written by your fellow agents and checking for any issues, bugs, errors, problems, inefficiencies, security problems, reliability issues, etc. and carefully diagnose their underlying root causes using first-principle analysis and then fix or revise them if necessary? Don't restrict yourself to the latest commits, cast a wider net and go super deep! Use ultrathink.

正確なプロンプト — ランダムなコード調査

詳細な品質チェックには、次を使います。

I want you to sort of randomly explore the code files in this project, choosing code files to deeply investigate and understand and trace their functionality and execution flows through the related code files which they import or which they are imported by.

Once you understand the purpose of the code in the larger context of the workflows, I want you to do a super careful, methodical, and critical check with "fresh eyes" to find any obvious bugs, problems, errors, issues, silly mistakes, etc. and then systematically and meticulously and intelligently correct them.

Be sure to comply with ALL rules in AGENTS dot md and ensure that any code you write or revise conforms to the best practice guides referenced in the AGENTS dot md file. Use ultrathink.

---

作業のコミット

正確なプロンプト — 変更をコミットする

エージェントに、論理的にまとまった変更をコミットさせます。

Now, based on your knowledge of the project, commit all changed files now in a series of logically connected groupings with super detailed commit messages for each and then push. Take your time to do it right. Don't edit the code at all. Don't commit obviously ephemeral files. Use ultrathink.

---

Bead 完了後のプロンプト

正確なプロンプト — テストカバレッジの追加

Do we have full unit test coverage without using mocks/fake stuff? What about complete e2e integration test scripts with great, detailed logging? If not, then create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid with detailed comments.

正確なプロンプト — UI/UX の精査

Great, now I want you to super carefully scrutinize every aspect of the application workflow and implementation and look for things that just seem sub-optimal or even wrong/mistaken to you, things that could very obviously be improved from a user-friendliness and intuitiveness standpoint, places where our UI/UX could be improved and polished to be slicker, more visually appealing, and more premium feeling and just ultra high quality, like Stripe-level apps.

正確なプロンプト — UI/UX の徹底的な改善

I still think there are strong opportunities to enhance the UI/UX look and feel and to make everything work better and be more intuitive, user-friendly, visually appealing, polished, slick, and world class in terms of following UI/UX best practices like those used by Stripe, don't you agree? And I want you to carefully consider desktop UI/UX and mobile UI/UX separately while doing this and hyper-optimize for both separately to play to the specifics of each modality. I'm looking for true world-class visual appeal, polish, slickness, etc. that makes people gasp at how stunning and perfect it is in every way.  Use ultrathink.

---

Agent Mail との連携

エージェントの連携方法

各エージェントは次のことを行います。

1. セッション開始時に Agent Mail に 登録する
2. 編集前にファイルを 予約する（file_reservation_paths）
3. thread_id に bead ID を含めてメッセージで作業を 通知する
4. タスクの合間に受信トレイを 確認する
5. 完了したら予約を 解除する

ファイル予約のパターン

# Before starting work on a bead
file_reservation_paths(
    project_key="/path/to/project",
    agent_name="GreenCastle",
    paths=["src/auth/**/*.ts"],
    ttl_seconds=3600,
    exclusive=True,
    reason="br-123"
)

# After completing work
release_file_reservations(project_key, agent_name)

コミュニケーションのパターン

# Announce starting a bead
send_message(
    project_key, agent_name,
    to=["BlueLake", "RedMountain"],  # Other active agents
    subject="[br-123] Starting auth module",
    body_md="I'm taking br-123. Reserved src/auth/**.",
    thread_id="br-123"
)

# Update on completion
send_message(
    project_key, agent_name,
    to=["BlueLake", "RedMountain"],
    subject="[br-123] Completed",
    body_md="Auth module done and tested. Released file reservations.",
    thread_id="br-123"
)

---

タスク選択に BV を使う

主なコマンド

# THE MEGA-COMMAND: Start here
bv --robot-triage

# Just get the single top pick
bv --robot-next

# Get parallel execution tracks (for multi-agent)
bv --robot-plan

# Check for cycles (MUST FIX if found)
bv --robot-insights | jq '.Cycles'

# Find bottlenecks
bv --robot-insights | jq '.bottlenecks'

重要： bv を引数なしで実行しないでください。セッションをブロックするインタラクティブな TUI が起動します。

---

品質ループ

問題がなくなるまで実行する

変更がないという結果が安定して返ってくるまで、次のプロンプトを繰り返し実行します。

1. セルフレビュー — エージェントが自分のコードをレビューする
2. 相互レビュー — エージェントが他のエージェントのコードをレビューする
3. ランダムな調査 — ランダムなコードパスを詳しく調べる

安定状態の指標

3 種類すべてのレビューで問題なし（バグが見つからず、変更もない）という結果が得られたら、コードはおそらく堅牢です。

---

プロンプト一覧

初期指示

First read ALL of the AGENTS dot md file and README dot md file super carefully and understand ALL of both! Then use your code investigation agent mode to fully understand the code, and technical architecture and purpose of the project. Then register with MCP Agent Mail and introduce yourself to the other agents.

Be sure to check your agent mail and to promptly respond if needed to any messages; then proceed meticulously with your next assigned beads, working on the tasks systematically and meticulously and tracking your progress via beads and agent mail messages.

Don't get stuck in "communication purgatory" where nothing is getting done; be proactive about starting tasks that need to be done, but inform your fellow agents via messages when you do so and mark beads appropriately.

When you're not sure what to do next, use the bv tool mentioned in AGENTS dot md to prioritize the best beads to work on next; pick the next one that you can usefully work on and get started. Make sure to acknowledge all communication requests from other agents and that you are aware of all active agents and their names.  Use ultrathink.

次の Bead に進む

Reread AGENTS dot md so it's still fresh in your mind.   Use ultrathink.   Use bv with the robot flags (see AGENTS dot md for info on this) to find the most impactful bead(s) to work on next and then start on it. Remember to mark the beads appropriately and communicate with your fellow agents. Pick the next bead you can actually do usefully now and start coding on it immediately; communicate what you're working on to your fellow agents and mark beads appropriately as you work. And respond to any agent mail messages you've received.

セルフレビュー

Great, now I want you to carefully read over all of the new code you just wrote and other existing code you just modified with "fresh eyes" looking super carefully for any obvious bugs, errors, problems, issues, confusion, etc. Carefully fix anything you uncover. Use ultrathink.

相互レビュー

Ok can you now turn your attention to reviewing the code written by your fellow agents and checking for any issues, bugs, errors, problems, inefficiencies, security problems, reliability issues, etc. and carefully diagnose their underlying root causes using first-principle analysis and then fix or revise them if necessary? Don't restrict yourself to the latest commits, cast a wider net and go super deep! Use ultrathink.

ランダムな調査

I want you to sort of randomly explore the code files in this project, choosing code files to deeply investigate and understand and trace their functionality and execution flows through the related code files which they import or which they are imported by.

Once you understand the purpose of the code in the larger context of the workflows, I want you to do a super careful, methodical, and critical check with "fresh eyes" to find any obvious bugs, problems, errors, issues, silly mistakes, etc. and then systematically and meticulously and intelligently correct them.

Be sure to comply with ALL rules in AGENTS dot md and ensure that any code you write or revises conforms to the best practice guides referenced in the AGENTS dot md file. Use ultrathink.

圧縮後

Reread AGENTS dot md so it's still fresh in your mind.   Use ultrathink.

変更をコミットする

Now, based on your knowledge of the project, commit all changed files now in a series of logically connected groupings with super detailed commit messages for each and then push. Take your time to do it right. Don't edit the code at all. Don't commit obviously ephemeral files. Use ultrathink.

テストカバレッジ

Do we have full unit test coverage without using mocks/fake stuff? What about complete e2e integration test scripts with great, detailed logging? If not, then create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid with detailed comments.

UI/UX の精査

Great, now I want you to super carefully scrutinize every aspect of the application workflow and implementation and look for things that just seem sub-optimal or even wrong/mistaken to you, things that could very obviously be improved from a user-friendliness and intuitiveness standpoint, places where our UI/UX could be improved and polished to be slicker, more visually appealing, and more premium feeling and just ultra high quality, like Stripe-level apps.

UI/UX の徹底的な改善

I still think there are strong opportunities to enhance the UI/UX look and feel and to make everything work better and be more intuitive, user-friendly, visually appealing, polished, slick, and world class in terms of following UI/UX best practices like those used by Stripe, don't you agree? And I want you to carefully consider desktop UI/UX and mobile UI/UX separately while doing this and hyper-optimize for both separately to play to the specifics of each modality. I'm looking for true world-class visual appeal, polish, slickness, etc. that makes people gasp at how stunning and perfect it is in every way.  Use ultrathink.

---

実際に機能するフライホイール

PLAN ──► BEADS ──► SWARM ──► REVIEW ──► COMMIT
  │                  │          │         │
  │                  │          └────┬────┘
  │                  │               │
  │                  └───── REPEAT ──┘
  │                              │
  │         v2 PLAN ◄────────────┘
  │              │
  └──────────────┘

サイクルを重ねるごとに、次の点が改善されます。

• CASS が解決策を記憶する
• CM がパターンを抽出する
• UBS がより多くの問題を検出する
• BV がグラフの健全性を示す

---

よくある質問

Q: エージェントは何に取り組むべきか、どのように判断しますか？ A: bv --robot-triage または bv --robot-next を使って、優先度が最も高く、着手可能なビードを見つけます。

Q: 競合をどのように回避しますか？ A: Agent Mail のファイル予約を使います。排他的な予約によって他のエージェントをブロックし、コミット前ガードでこれを徹底します。

Q: エージェントがクラッシュしたり、忘れたりした場合はどうなりますか？ A: どのエージェントも代替可能です。新しいセッションを開始し、AGENTS.md を読み、ビードの状態を確認して、作業を続けます。

Q: エージェントはいくつ実行すべきですか？ A: プロジェクトの複雑さによります。まずは 3～6 個から始めてください。エージェントを増やすと速くなりますが、調整の負担も増えます。

Q: どのようなモデル構成が最適ですか？ A: 組み合わせることをおすすめします。Claude Code（Opus）を 3 つ、Codex（GPT 5.2）を 2 つ、Gemini を 1 つ試してみてください。それぞれ得意分野が異なります。

Q: エージェントごとに専門分野を持たせる必要がありますか？ A: いいえ、どのエージェントも代替可能なジェネラリストです。エージェントにフロントエンド担当だと伝えるだけで、フロントエンドの能力が高まるわけではありません。

Q: git コミットとビードの間に追跡可能性はありますか？ A: はい。bv がこの分析を自動的に行い、データの流れを分析して論理的に推論することで、ビードを関連する git コミットに紐付けます。