Agent Teamsのタスク割当とclaimの仕組み
Agent Teamsの共有タスクリストは3状態と依存関係で動きます。リードの指名とteammateの自己claimの使い分け、タスクリストが空になる条件、詰まったときの直し方をまとめます。
このTipsでできること
Agent Teamsでは、リードとteammateが1つの共有タスクリストを介して作業を分担します。タスクはpending(未着手)・in progress(作業中)・completed(完了)の3状態を持ち、依存関係が付いたタスクは前提が終わるまで取得(claim)できません。
この記事では、割り当て方式の使い分けに加えて、「タスクリストが空のまま動かない」「完了にならず後続が止まる」「メッセージが届かない」といった症状の切り分けを扱います。
タスクリストが空のままなら、まずモデルを見る
Agent Teamsを有効にしたのにタスクが1件も作られない場合は、割り当て以前にタスク管理のツールが載っていない可能性があります。TaskCreate・TaskGet・TaskList・TaskUpdateの4つは、Claude 3.x、Opus 4〜4.7、Sonnet 4〜4.6、Haiku 4.5のセッションでだけ既定で提供されます。それ以外のモデルや、Claude Codeが認識できないモデルIDでは、オプトインしない限りツールが外れます。この既定の範囲はv2.1.268以降の仕様です。
このとき、各エージェントは共有タスクリストを使わず、メッセージのやり取りで調整します。オプトインの方法は4つあります。
# 環境変数で、どのモデルでもタスクツールを提供する
CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude
# ツール名を --allowedTools に書く
claude --allowedTools TaskCreate環境変数 CLAUDE_CODE_ENABLE_TODO_TOOLS はv2.1.233以降が必要です。3つ目は、--tools にタスクツールを並べる方法です。--tools はそのセッションの組み込みツールを列挙したものだけに絞るので、普段使う他の組み込みツールも併記します。4つ目は、Agent SDKの allowedTools と tools オプションで、この2つのフラグと同じように働きます。バックグラウンドセッションとクラウドセッションは例外で、モデルが対象外でも同じツールが提供されます。
チームの中でも既定の効き方は一様ではありません。同一プロセスで動くin-processのteammateはリードのセッションに従い、リードにツールがあればteammateにも付きます。tmuxなどの分割ペインで動くteammateは別のClaude Codeプロセスなので、そのteammate自身のモデルで決まります。リードがOpus 4.7でteammateが対象外のモデルだと、後者だけタスクリストを使えない構成になり得ます。
タスクは3状態と依存関係で管理される
共有タスクリストの各タスクは、pending・in progress・completedのいずれかにあります。依存先が未完了のあいだ、そのタスクはpendingのままで取得できません。
たとえば「APIエンドポイントの実装」に「DBスキーマ設計」への依存を付けると、スキーマ設計がcompletedになるまでAPIの実装には誰も着手できません。解除は自動で、前提タスクを完了させたteammateの操作をきっかけに、Claude Codeが依存タスクのブロックを外します。「次を解禁して」と指示する必要はありません。
割り当ては明示指定か自己claimで決まる
割り当て方式は2つで、どちらもClaude Codeが裏で処理します。
リードの指名か、teammateの自己claimか
リードが割り当てる
担当を決めたいときは、リードに「認証周りの修正はresearcherに、テスト追加はtesterに」と直接伝えます。レビュー系のように、誰が何を見たかを揃えたい作業向きです。
teammateが自己claimする
teammateは自分のタスクを終えたあと、未割当でブロックされていない次のタスクを自分で拾います。独立した機械的な作業が十数件あるときは、割当待ちの空白が生まれません。
複数のteammateが同じタスクを同時に取りにいく競合は、ファイルロックで防がれます。そのため、自己claimでも同じタスクが二重に走ることはありません。ロックの待ち方や、負けたteammateが次に何をするかは、Agent Teamsのドキュメントには書かれていません。
タスクが詰まって見えるときの切り分け
動いていないように見えるときは、まずタスクリストの実際の状態を見ます。in-processモードでは、エージェントパネルでteammateを選んでEnterを押すと、そのセッションの中身も覗けます。
詰まったタスクの直し方
- 1
作業が終わっているかを見る
Ctrl+Tでタスクリストの表示を切り替え(一度に表示されるのは最大5件)、タスクの状態を確かめ、teammateの出力で成果物が実際にできているかを見ます。作業は終わっているのに完了の更新が漏れたまま、という形が公式の既知の制約に挙がっています。画面上でteammateを選んで
xを押すとそのteammateを止められますが、止める前に未完了のタスクがないかを先に見ておきます。 - 2
終わっていれば状態を直す
自分でタスクの状態を更新するか、リードに「該当teammateに完了の更新を促して」と伝えます。前提タスクが完了になれば、後続のブロックは自動で外れます。
- 3
teammateがもういなければ立て直す
/resumeや/rewindのあとは、in-processのteammateが復元されません。存在しないteammateへ送ろうとしたら、リードに新しいteammateを起動するよう伝えます。
完了の基準を機械的に強制したいときは、フックが使えます。TaskCompletedはタスクが完了扱いになる直前に動き、終了コード2で完了を止めてフィードバックを返せます。タスクがTaskUpdateで完了にされたときに加えて、teammateが進行中のタスクを抱えたままターンを終えたときにも発火します。TaskCreatedフックも同じ要領で、タスクの作成を止めたいときに終了コード2を返します。具体的な書き方はTaskCompletedフックで品質ゲートを強制するにあります。
メッセージが届かないときはmailboxを疑う
teammate同士のメッセージは、~/.claude/teams/{team-name}/inboxes/{agent-name}.jsonという受信箱のファイルを通じて届きます。Claude Codeは受信箱を読むたびに各エントリを検証し、形式に合わないものはエラーとして報告したうえで除去し、有効なメッセージは配信します。v2.1.207より前は、壊れたエントリが1件あると毎秒エラーが出続け、ファイルを手で消すまでその受信箱への配信が止まっていました。
「送信済み」の基準も押さえておく価値があります。送信側が呼び出した時点ではなく、受け手の受信箱への書き込みが成功した時点で、送信済みと報告されます。プレーンなメッセージも、プラン承認やshutdownリクエストのような構造化メッセージも同じ扱いです。
書き込みが失敗すると、送り手のツール結果に次の形のエラーが返り、何も送られません。
Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.原因として公式に挙がっているのは、ディスクが満杯、ディレクトリに書き込めない、別のエージェントが受信箱のロックを長く握っている、の3つです。v2.1.224より前は、書き込みに失敗しても送信済みと報告されていました。古いバージョンで「送ったはずなのに届かない」が起きていたら、この挙動が原因かもしれません。書き込みに失敗する原因の切り分けは、Agent Teamsでinboxへの書き込みに失敗する原因と対処で詳しく扱っています。
プラン承認の提出が失敗した場合は、teammateがプランモードのまま再提出の成功を待つ状態になります。権限リクエストが届かなかった場合は、誰もそのツール呼び出しを承認していません。
teammateのshutdownにも待ち時間があります。リードがshutdownをリクエストすると、teammateは承認して終了するか、理由を添えて拒否できます。承認した場合も、実行中のリクエストやツール呼び出しを終えてから止まります。
セッションを再開しても残るもの、残らないもの
チームの設定とタスクリストは、session-に続けてセッションIDの先頭8文字を付けた名前で、ローカルに保存されます。
セッション終了後のチームの設定とタスクリスト
消える
~/.claude/teams/{team-name}/config.jsonを含むチーム設定のディレクトリは、セッションの終了時に削除されます。ファイルには実行時の状態が入るため、手で編集しても次の更新で上書きされます。
残る
~/.claude/tasks/{team-name}/は端末に残り、外部へアップロードされません。再開したセッションでもタスクが残り、保持期間はcleanupPeriodDaysに従います。
チームそのものは1セッションに閉じていて、別のセッションと共有できません。一方、通常のセッションではCLAUDE_CODE_TASK_LIST_ID=my-project claudeのように環境変数を設定すると、~/.claude/tasks/の名前付きディレクトリのタスクリストを複数のセッションで共有できます。
タスクの切り方で割当の効率が決まる
粒度が小さすぎると調整の手間が効果を上回り、大きすぎるとチェックインなしに長く動いて手戻りが増えます。目安は、関数1つ、テストファイル1つ、レビュー1件のように、明確な成果物を1つ生むまとまりです。teammate 1体につき5〜6タスクなら、全員が手を止めずに動け、誰かが詰まったときにリードが再割当しやすくなります。
人数は、ほとんどのワークフローで3〜5体から始めるのが妥当です。独立したタスクが15件あっても、最初は3体で足ります。各teammateが独自のコンテキストウィンドウを持つため、トークンの使用量はアクティブなteammateの数に応じて増えます。人数が増えるほど、タスク調整の手間と衝突の可能性も増えます。タスクが数件しかない作業では、1つのセッションのほうが費用対効果は高くなります。
タスク割当でつまずきやすい点
- 同じファイルを別々のタスクに割る: 各teammateが別のファイル群を持つようにタスクを切ります。タスクリストにはファイル単位の排他制御の記述がなく、2体が同じファイルを編集すると上書きが起きます
- 順序依存の強い作業をチームに載せる: 順番どおりに進める作業、同じファイルを編集する作業、依存関係が多い作業は、単一のセッションかサブエージェントのほうが向いています
- リードが自分で実装を始める: リードがteammateの完了を待たずに実装へ入ることがあります。気づいたら「Wait for your teammates to complete their tasks before proceeding」のように、teammateの完了を待つよう伝えます
- リードが早く終わったと判断する: すべてのタスクが済む前にリードがチームの作業を締めようとすることがあります。この場合は、続けるように伝えます
まとめ
タスクが動かないときは、モデルにタスクツールがあるか、状態が実態と合っているか、受信箱への書き込みが成功しているかの順に見ると、原因を絞れます。後続が止まったときは、完了の更新漏れが既知の制約なので、成果物ができているかから確かめます。担当を厳密に分けたいときはリードの指名を、数を捌きたいときは自己claimを選び、タスクは「明確な成果物を1つ生む」大きさに揃えます。