多Agent系统：multi-agent-shogun

想象一下，当你给AI下达一个复杂任务——比如"写一个完整的Web应用"——你希望它是孤军奋战的独行侠，还是一支配合默契的部队？yohey-w/multi-agent-shogun（后文简称"幕府系统"）给出的答案是后者：它将多个Claude Code实例编织成一支战国军团，让AI以层级指挥的方式并行作战，把大型开发任务拆解成可同时执行的子任务，从根本上改变了人机协作的效率上限。

起源：为什么需要多Agent协同？

传统的AI编程工具无论是Copilot还是单实例Claude Code，本质上都是"单兵作战"模式。面对需要横跨前端、后端、测试、文档的大型项目，单个AI Agent常常力不从心：上下文窗口溢出、任务优先级混乱、缺乏全局视角。

日本开发者 yohey-w 从战国军事组织中汲取灵感，设计了一套多层级Agent指挥体系。这套系统的核心灵感来自日本战国时代的军队结构——主君（Lord/人类）→ 总大将（Shogun）→ 家老（Karo）→ 足轻（Ashigaru）——每一个层级各司其职，形成了一条清晰的任务传递链。人类只需下达战略指令，顶层Agent自动完成所有战术拆解和执行协调。

核心机制：战国家臣制度的工程实现

这套系统的运作方式极具创意。每个"角色"实际上是一个运行在 tmux 会话中的 Claude Code 实例，拥有独立的指令集（AGENTS.md/instructions/）和专属的任务队列文件。

**Shogun（总大将）**是整个系统的中枢。它接收人类主人的命令，将任务写入 YAML 命令队列（queue/shogun_to_karo.yaml），然后通过 inbox 机制唤醒 Karo。它不亲自执行任务，只负责调度和汇报——这是典型的管理层逻辑。

**Karo（家老）**是战术指挥官。它从 Shogun 那里接收任务，进行深度分析和任务拆解（通常拆成 7 个并行子任务），分配给 Ashigaru 执行。Karo 还配备了一个"军师"（Gunshi）角色，专门负责战略级别的分析和研究，确保执行方向的正确性。

**Ashigaru（足轻，1-7号）**是最底层的执行单元。每个 Ashigaru 独立运行在自己的 tmux pane 中，执行具体代码编写、文档撰写等任务。多个 Ashigaru 可以同时开工，真正实现并行处理。

所有层级之间通过 YAML 文件 + inbox 邮件系统 进行事件驱动的异步通信，完全避免了轮询（polling）带来的 API 资源浪费。这套通信机制被作者称为"纯事件驱动，零轮询"——一旦有任务完成或状态变更，相关方通过文件写入触发下一步动作。

图1：多 tmux pane 协同作战全景图 —— Shogun 在独立会话中监控全局，Karo 和多个 Ashigaru 在 multiagent 会话的不同 pane 中并行执行任务

技术实现：纯 Shell + YAML 的极简架构

令人惊讶的是，这个复杂的多 Agent 协调系统完全由 Shell 脚本 + Makefile + YAML 配置文件 构建，没有任何重型依赖。

项目的核心技术栈：

• tmux：作为底层任务隔离和会话管理基础设施，每个 Agent 运行在独立的 tmux pane 中
• Shell/Bash：所有安装脚本（first_setup.sh、install.bat）、工具脚本（inbox_write.sh、slim_yaml.sh）和构建脚本（build_instructions.sh）均使用 Shell 编写
• YAML：作为 Agent 间的通信协议和数据格式，定义任务队列、状态流转、报告结构
• Make：提供标准化的开发命令（make test、make lint、make build），同时也是用户常用的入口
• Claude Code CLI：真正的执行引擎，每个 Agent 都是一个 claude code 实例

项目的目录结构清晰反映了角色划分：

• instructions/shogun.md / karo.md / ashigaru.md：各角色专属指令集
• instructions/common/：共享的任务流规范和状态定义
• queue/：所有 Agent 共享的任务队列目录（YAML 文件）
• agents/default/：Agent 特定配置
• config/projects.yaml：项目列表配置

指令文件采用 YAML front matter + Markdown 内容双层结构，机器可读的配置在前，角色行为指南在后。这种设计让系统规则既能被脚本解析（配置部分），也能被 Claude 理解（说明部分）。

TDD流程：足轻的标准化作业

Ashigaru 角色内置了严格的 TDD（测试驱动开发）流程，每个任务的执行必须遵循 Strategy → Spec → Test → Implement → Verify 五步。acceptance_criteria（验收标准）在任务分配时就明确定义，Ashigaru 完成任务后需要逐一核对。这套机制极大降低了"看起来完成了但其实有 bug"的风险。

图2：TDD/NDD/RDD 开发流程图 —— 足轻严格执行测试驱动的标准化作业流程

MCP工具集成：扩展Agent能力边界

系统支持通过 MCP（Model Context Protocol）扩展 Agent 能力。当前配置的 MCP 工具包括：Notion（笔记管理）、Playwright（浏览器自动化）、GitHub（代码托管）、Sequential Thinking（结构化推理）和 Memory（记忆管理）。这些工具在需要时按需加载（lazy-load），避免资源浪费。

部署体验：零容器化的本地工具

multi-agent-shogun 不是为云端部署设计的。它是一个纯本地工具，运行在用户自己的终端环境中。安装过程极其简单：

1. 克隆仓库：git clone https://github.com/yohey-w/multi-agent-shogun
2. 运行安装：bash first_setup.sh（Linux/macOS）或双击 install.bat（Windows）
3. 在 tmux 中启动各层级的 Agent 实例

硬件要求极低：无需 GPU，RAM 1GB、磁盘 200MB 即可运行。真正瓶颈在于 Claude API 的用量——多个并行 Agent 会显著增加 token 消耗。项目明确不支持 Docker 容器化，因为它的设计哲学是"让人类直接参与协作"，而非无人值守的自动化流水线。

局限与挑战

多 Agent 协同带来了新的复杂性。首先是 token 成本：7 个 Ashigaru 同时调用 Claude API，token 消耗速度是单 Agent 的数倍，需要谨慎评估任务规模与成本的平衡。其次是 调试难度：当某个 Ashigaru 任务失败时，需要在对应的 tmux pane 中手动排查，链路较长。最后是 上下文管理：虽然有 inbox 机制，但 YAML 文件的并发写入仍可能产生竞态条件（作者在文档中提到了这一点）。

行业意义：重新定义AI编程的生产力边界

multi-agent-shogun 代表了一个重要趋势：从单Agent辅助编程到多Agent协同开发。它的战国军事隐喻并非噱头，而是真正影响了系统设计的每一个层面：层级清晰、职责明确、事件驱动通信。

对于需要处理复杂多模块项目的开发团队，这套系统提供了一种介于"全手动"和"全自动化"之间的折中方案。人类保留战略决策权，AI 承担战术执行和协调工作。这种人机协作模式或许会成为未来大型 AI 编程项目的主流形态。

github.com/yohey-w/multi-agent-shogun