Claude Codeに Agent Teams という機能が追加された。複数のClaude Codeインスタンスをチームとして連携させる実験的機能。

これを戦国風マルチエージェント開発基盤「将軍システム」に組み込んでみたら、既存の課題がかなり解決したので紹介する。

Agent Teamsとは

複数のClaude Codeインスタンスをチームとして連携させる機能（現在は実験的）。

チームリーダーが作業を調整、メンバーが独立して並列作業する
subagentsとの違い: メンバー同士が直接通信できる、共有タスクリストがある
リーダーを調整専任に制限する delegate mode がある

主なAPI:

API	用途
`TeamCreate`	チーム作成
`SendMessage`	エージェント間メッセージング（自動配信）
`TaskCreate` / `TaskUpdate` / `TaskList`	共有タスクリスト管理

詳細は公式ドキュメント参照。

組み込み先: 将軍システム

今回Agent Teamsを組み込んだ「将軍システム」は、Claude Code × tmuxで動くマルチエージェント環境。戦国時代の軍制をモチーフにした階層構造になっている。

上様（人間）
  ↓
将軍（戦略統括）
  ↓
家老（タスク分解・足軽への指示展開）
  ↓
足軽×N（並列実行）

（上様＝将軍じゃない？という違和感はさておき）

元の通信方式はYAMLファイル + tmux send-keysによるイベント駆動。指示や報告をYAMLに書いて、tmux send-keys で相手のペインにメッセージを送って起こす仕組み。

使ってみて便利だったけど、いくつか課題があった。

旧形式の将軍画面。YAMLファイルを編集してsend-keysで家老を起こしている。家老が確認待ちで止まっている場合、殿(人)が、目視で見つけて指示する必要がある。

旧形式のエージェント画面。足軽が並列で作業しているが、通信はsend-keys経由。

Agent Teams導入前の課題

1. send-keys方式の通信ミス

tmux send-keysはメッセージとEnterを2回に分けて送信する必要がある。エージェントがこれをよく忘れて処理が止まる。

しかも止まっていることに気づくにはマルチエージェント側のtmuxを見に行くしかない。シェルスクリプトでラップして軽減したけど根本解決にはならず。

2. 将軍に報告が上がってこない

家老が将軍と殿（人間）のやり取りを邪魔しないよう気を遣って待機してしまう。作業が終わっているのに報告が来ず、殿がtmuxを見に行って「終わってるけど？」と確認する羽目になった。

5分おきの監視シェル（watchdog.sh）も作ったけど、手間が増えるだけだった。

3. 足軽の成果物の品質が低い

元システムにレビュー工程がない。足軽の作業結果がそのまま上がってくるので自分でチェックが必要。

これは 目付（レビュアー） という役職を新設して対応した。足軽の作業完了後、家老が目付にレビューを回して、問題があれば足軽に再作業させる流れにした。

4. 将軍が自分で作業を始めてしまう

委任すべきタスクを将軍が自分で実装し始めることがある。並列性が失われる。指示書で禁止しても完全には防げなかった。

通信方式の変遷

課題への対処を重ねた結果、通信方式はこう変わった。

段階	方式	課題
初期	YAML + tmux send-keys	Enter送信忘れ、通信ロスト
Agent Teams導入後	SendMessage + TaskCreate	組み込みの通信基盤に完全移行

Agent Teamsでどう変わったか

ここからが本題。

Agent Teams版の将軍画面。タスクリストとチームメンバーの状態が表示されている。

Agent Teams版のエージェント画面。家老・目付・足軽が並列作業中。
色分けとラベルも付いて見やすくなった。

通信の信頼性

send-keysを廃止してSendMessageに移行した。メッセージは自動配信されるので、送信忘れの問題が完全に無くなった。

メッセージ自動配信

Agent Teamsはメッセージが自動的に届く。ポーリング不要で、送信側はSendMessageを呼ぶだけ。家老が「将軍の邪魔にならないよう待機」する問題が解消された。

共有タスクリスト

TaskCreate / TaskUpdate / TaskList で進捗が見える。マルチエージェント側のtmuxを見に行かなくてよくなった。

delegate mode

リーダーを調整専任に制限するモード。コード編集等の作業ツールが使えなくなるので、将軍が自分で作業を始める問題を根本から解決できる。

指示書の禁止事項だけでは防げなかったものが、仕組みで制御できるようになったのは大きい。

改善スクリプトが不要に

send-keysラッパー（notify.sh）、監視シェル（watchdog.sh）など、課題対処のために作ったスクリプト群がほぼ不要になった。

tmuxセッション構成の工夫

Agent Teamsのデフォルトだとリーダーと同じ画面にエージェントのペインが開く。将軍の操作領域が狭くなるので、別tmuxセッションにエージェントを移動している。

shogunセッション     : 将軍（人間とのやり取り）
multiagentセッション : 家老・目付・足軽（バックグラウンド作業）

具体的な設定

起動スクリプト（claude-shogun）

Agent Teams版の起動スクリプト。環境変数でAgent Teamsを有効化して、tmuxモードで起動する。

#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
export SHOGUN_ROOT="$(dirname "$SCRIPT_DIR")"

# Agent Teams 有効化（tmux モード）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

exec npx -y @anthropic-ai/claude-code --teammate-mode tmux "$@"

ポイント:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1: Agent Teamsの有効化フラグ
--teammate-mode tmux: tmux分割ペインモードで起動
npx -y @anthropic-ai/claude-code: 常に最新版を使用

この起動スクリプト経由で起動するのでsettings.jsonの変更は不要。

CLAUDE.mdでの通信プロトコル定義

CLAUDE.mdにAgent Teams用の通信プロトコルを定義している。これがチーム全体のルールになる。

## 通信プロトコル: Agent Teams

エージェント間の通信は **Agent Teams** の組み込み機能を使用する。

| 操作 | API |
|------|-----|
| メッセージ送信 | SendMessage(type="message", recipient="名前", ...) |
| 全体通知 | SendMessage(type="broadcast", ...) |
| タスク作成 | TaskCreate(subject="...", description="...") |
| タスク割当 | TaskUpdate(taskId="...", owner="名前") |
| タスク完了 | TaskUpdate(taskId="...", status="completed") |

instructions/での役割定義

各エージェントの指示書にはYAML Front Matterでルールを書いている。

# instructions/shogun.md
role: team_leader
mode: delegate

forbidden_actions:
  - id: F001
    action: self_execute_task
    description: "自分でファイルを読み書きしてタスクを実行"
    delegate_to: karo
  - id: F002
    action: direct_ashigaru_command
    description: "Karoを通さずAshigaruに直接指示"
    delegate_to: karo

mode: delegate で将軍が自分で作業を始めることを防止している。

チームの構成と指示の流れ

将軍がチームを作成して、タスクを家老に割り当てる流れはこんな感じ。

# チーム作成
TeamCreate(team_name="shogun-team")

# 家老を spawn（delegate mode）
Task(subagent_type="general-purpose", team_name="shogun-team", name="karo",
     mode="delegate",
     prompt="汝は家老なり。instructions/karo.md を読んで役割を理解せよ。")

# タスクを作成して家老に割当
TaskCreate(subject="WBSを更新せよ", description="...")
TaskUpdate(taskId="1", owner="karo")
SendMessage(type="message", recipient="karo",
            content="新しいタスクを割り当てた。TaskList を確認せよ。",
            summary="新タスク割当通知")

階層構造の拡張

Agent Teamsの標準構成はリーダーとメンバーの2階層。でもCLAUDE.mdやinstructionsでルールを定義すれば、将軍→家老→足軽のような3階層以上の指揮系統も実現できる。

「将軍は家老にのみ指示」「家老が足軽にタスクを分配」といった制約をプロンプトで制御している。仕組み自体はフラットだけど、ルール次第で階層的な運用が可能。

まとめ

Agent Teamsで既存の課題がかなり解決した。

send-keys通信の不安定さ → SendMessageの自動配信で完全解消
タスク管理 → 共有タスクリストで進捗が可視化
委任制御 → delegate modeで仕組みとして強制

将軍システムの階層構造とAgent Teamsの設計思想は相性が良くて、ルール定義次第で柔軟に拡張できる。

YAML書き込みや家老のtmuxテキスト取得、send-keys送信といったステップが無くなったので、トークン消費も減ったし動作も早くなった。

ソースコード:

本家の通信方式も、進化していた

記事を書いた後に本家を確認したら、通信方式が独自に進化していた。

世代	方式	特徴
第1世代	YAML + send-keys(2回)	send-keysでメッセージ本体を送る。文字化け・ハングのリスク
第2世代	ntfy双方向通信	外部サービスntfy.sh経由。スマホから命令可能に。エージェント間通信としては不安定
第3世代	mailbox + nudge	send-keysは7文字のnudgeのみ。本体はYAMLファイル。flock排他ロック+inotifywait監視

第3世代のポイントは「send-keysでは短いnudgeだけ送り、メッセージ本体はファイルで渡す」という設計。send-keysで長い文字列を送ると文字化け・ハングするという教訓から来ている。

こちら（Agent Teams版）との比較:

本家: inbox_write.sh → YAMLファイル → inotifywait → nudge send-keys → 自分でRead
こちら: SendMessage() → Agent Teamsが自動配信 → 自動的に届く

本質的にやっていることは同じだけど、本家はファイルシステム+tmux+シェルスクリプトで自前実装しているのに対し、こちらはAgent TeamsのAPIに任せている。本家の「なぜそう設計したか」の知見（排他ロック、冪等性、nudge設計等）はAgent Teams運用でも参考になる。