agent-swarm-workflow

Agent Swarm 工作流——并行实现

核心见解： 每个 Agent 都可以互换，且都是通才。他们都使用相同的基础模型，并读取相同的 AGENTS.md。仅仅告诉某个 Agent 它是“前端 Agent”，并不会让它更擅长前端开发。

通过 Agent Mail 和 Beads，Agent 群集实现了分布式、健壮且能够自组织。

---

先决条件

启动 Agent 群集前：

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，用于会话管理

---

Agent 群集架构

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

---

启动 Agent 群集

使用 NTM（命名 Tmux 管理器）

# 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)"

手动设置

在项目文件夹中为每个 Agent 创建 tmux 会话／窗格。

---

精确提示词——Agent 初始行动指令

给每个 Agent 提供以下精确提示词以启动：

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

Agent 完成一个 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 后进行自我审查

让 Agent 在继续处理下一个 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.

持续运行此流程，直到他们不再发现 Bug。

---

处理上下文压缩

精确提示词——压缩后

Agent 执行压缩后，立即跟进：

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

这会重新确立有关工具和工作流的关键上下文。

---

质量审查提示词

精确提示词——跨 Agent 审查

定期让 Agent 相互审查工作：

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.

---

提交工作

精确提示词——提交更改

让 Agent 按逻辑分组提交更改：

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 集成

Agent 如何协调

每个 Agent 都会：

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. 自我审查——Agent 审查自己的代码
2. 交叉审查——Agent 审查其他 Agent 的代码
3. 随机探索——深入检查随机代码路径

稳定状态信号

当三类审查都确认无问题（未发现 Bug，也未做出更改）时，代码很可能已足够稳固。

---

完整提示词参考

初始行动指令

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 展示图谱健康状况

---

常见问题

问：Agent 如何知道要处理什么？ 答：它们使用 bv --robot-triage 或 bv --robot-next 找出影响最大的就绪 bead。

问：它们如何避免冲突？ 答：通过 Agent Mail 中的文件预留。独占预留会阻止其他人操作；提交前检查会强制执行这一规则。

问：如果 Agent 崩溃或忘记了怎么办？ 答：每个 Agent 都可以互换。启动新会话，阅读 AGENTS.md，检查 bead 状态，然后继续。

问：我应该运行多少个 Agent？ 答：取决于项目的复杂程度。可以从 3-6 个开始。Agent 越多，速度越快，但协调开销也越大。

问：哪种模型组合效果最好？ 答：建议混合使用。可以试试 3 个 Claude Code（Opus）、2 个 Codex（GPT 5.2）和 1 个 Gemini。它们各有所长。

问：Agent 是否需要各自擅长不同领域？ 答：不需要，每个 Agent 都可以互换，且都是通才。仅仅告诉某个 Agent 它是前端 Agent，并不会让它更擅长前端。

问：git 提交和 bead 之间是否具有可追溯性？ 答：有，bv 会自动进行分析，通过分析数据流并做出逻辑推断，将 bead 与相关的 git 提交关联起来。