Agent Teamsのタスク割当とclaimの仕組み

このTipsでできること

Agent Teamsでは、リードとteammateが1つの共有タスクリストを介して作業を分担します。タスクはpending(未着手)・in progress(作業中)・completed(完了)の3状態を持ち、依存関係が付いたタスクは、前提が完了するまでteammateが自分で取得(claim)できません。この仕組みを知っていると、リードが明示的に割り当てる方式と、teammateが自分の判断で次のタスクを拾う方式を使い分けられるようになります。

タスクは3状態と依存関係で管理される

共有タスクリストの各タスクは、pending(未着手)・in progress(作業中)・completed(完了)のいずれかの状態を持ちます。加えてタスクには他のタスクへの依存関係を設定でき、依存先が未完了のあいだ、そのタスクはpendingのまま取得できません。

たとえば「APIエンドポイントの実装」というタスクに「DBスキーマ設計」というタスクへの依存を付けておくと、DBスキーマ設計がcompletedになるまでAPIエンドポイントのタスクはteammateから見えていても着手不能な状態が続きます。依存関係の解除は自動で、あるteammateが前提タスクを完了させると、Claude Codeが依存タスクを自動的にブロック解除します。ユーザー側で「次のタスクを解禁して」と明示的に指示する必要はありません。

割り当て方式は2つ — 明示指定と自己claim

タスクの割り当てには2つの方式があります。

• リードが割り当てる: 「このタスクはこのteammateに」とリードに直接指示する
• teammateが自己claim: teammateが自分のタスクを終えたあと、未割当かつブロックされていない次のタスクを自分の判断で拾う

どちらもClaude Codeが裏側で処理し、ユーザーが個別のAPIを叩く必要はありません。

明示割当は「誰が何を担当したか」を厳密に統制したいレビュー系の作業で有効です。自己claimは、独立したタスクが十数個あるような機械的な分割作業で威力を発揮します。手が空いたteammateがすぐ次のタスクに移るため、割当待ちの空白時間が生まれません。

タスクを取得する際は、複数のteammateが同時に同じタスクを取り合う競合状態を避けるためファイルロックが使われます。同時に2体のteammateが同じタスクを掴もうとしても、実際にタスクを保持するのは1体だけです。もう一方はロックの解放を待つか、次の未割当タスクへ移ります。この仕組みのおかげで、自己claim方式でも同じ作業が二重に実行される心配はありません。

Taskツールを使えないエージェントは、この共有タスクリストではなくメッセージのやり取りで作業を調整します。すべてのエージェントが同じ調整メカニズムを使うわけではない、という点は覚えておく必要があります。

teammate間のやり取りはmailboxで検証される

タスクの割当や依存関係の裏側では、teammate同士のメッセージも同様に堅牢な仕組みで支えられています。各teammateは~/.claude/teams/{team-name}/inboxes/{agent-name}.jsonという自分専用の受信箱を持ち、他のteammateやリードからのメッセージはここに書き込まれます。この受信箱には不正な形式のエントリが混入しないよう検証がかかっており、壊れたエントリは自動的に除去されます。

メッセージが「送信済み」と報告されるタイミングにも注意が必要です。Claude Codeは、送信元が送信操作を呼び出した時点ではなく、受信側の受信箱への書き込みが実際に成功した時点で送信済みとみなします。つまり送信の成否は受け手側の状態に依存しており、リードやteammateが「送ったはずなのに届いていない」と感じたら、まず受け手のteammateが生きているか、受信箱への書き込みが本当に完了しているかを疑うのが近道です。

もう一つ覚えておきたいのが、teammateの終了処理は即座には終わらないという点です。あるteammateにshutdown(終了)を指示しても、Claude Codeはそのteammateが現在実行中のツール呼び出しが完了するのを待ってから終了させます。長時間かかるツール呼び出しの最中にshutdownを指示すると、体感より終了が遅くなることがあります。これはタスクの整合性を守るための意図した挙動で、不具合ではありません。

セッションを再開してもタスクは残る

チームの設定とタスクリストは、セッションIDから導かれた名前でローカルに保存されます。チーム設定は~/.claude/teams/{team-name}/config.json、タスクリストは~/.claude/tasks/{team-name}/です。チーム設定のディレクトリはセッション終了時に削除されますが、タスクリストのディレクトリはローカルに残り続け、外部にアップロードされることもありません。つまりセッションを/resumeで再開しても、タスクの割当状況や依存関係、完了状態はそのまま引き継がれます。保持期間はセッションのトランスクリプトと同じcleanupPeriodDays設定に従います。

ここには見落としやすい落とし穴があります。タスクリストは残っても、in-processで動いていたteammateそのものは/resumeや/rewindでは復元されません。再開直後にリードが「もう存在しないteammateにメッセージを送ろうとする」ことがあります。これが起きたら、リードにteammateを新しく立て直すよう伝えれば、新しいteammateが永続化されていたタスクリストから拾って続きの作業を再開できます。タスク自体は消えていないので、やり直しになるのは「teammateの起動」だけです。

タスクが動かなくなったときの直し方

Agent Teamsの既知の制約として、teammateがタスクをcompletedとしてマークし忘れることがあります。これが起きると、そのタスクに依存する後続タスクがブロックされたままになります。

対処は2つです。

1. 実際に作業が終わっているかを自分で確認し、終わっていればタスクの状態を手動で更新する
2. リードに「該当teammateへタスク完了の確認を促して」と伝える

タスク粒度が割当の効率を左右する

タスク自体の粒度も、割当がスムーズに進むかどうかに直結します。小さすぎるタスクは調整のオーバーヘッドが効果を上回り、大きすぎるタスクはteammateがチェックインなしに長時間動き続けて手戻りのリスクが増えます。関数1つ、テストファイル1つ、レビュー1件のように、明確な成果物を1つ生むまとまりが目安です。1体のteammateあたり5〜6タスクを目安に細分化すると、全員が手を止めずに動き続けられ、誰かが詰まったときにリードが別のteammateへ再割当しやすくなります。

タスク割当でつまずきやすい点

タスクリストの仕組みを理解していても、実運用では次のようなつまずきが起きます。

• 同じファイルを別々のタスクに割ってしまう: タスクリスト自体は「誰が何を担当するか」を管理しますが、ファイル単位の排他制御まではしません。2つのタスクが同じファイルを編集対象にしていると、担当するteammateが違っても上書き事故が起きます。タスクを切る段階で「担当ファイルが重ならないか」を必ず確認してください
• Task toolを持たないエージェントを混在させる: Taskツールを持たないエージェントは共有タスクリストを使わず、メッセージのやり取りだけで調整します。チームの一部だけがこの条件を満たさないと、「タスクリストには載っているのに一部のteammateには見えていない」という状態が起こり得ます
• 依存関係を細かく刻みすぎる: 依存関係チェーンを何段も重ねると、前提タスクの完了漏れ1つで後続がすべて止まります。依存は「本当に順序が必要な箇所」だけに絞るのが安全です

よくある質問

リードは自分でタスクを実行してもよいか

構造上は可能ですが、想定された使い方ではありません。リードがteammateの完了を待たずに自分で実装を進めてしまうと、teammateとの分担が意味を失います。この動きに気づいたら「teammateの完了を待ってから進めて」とリードに伝えると、本来の役割分担に戻ります。

依存関係のあるタスクを間違って先に取得してしまうことはあるか

ありません。依存先が完了していないタスクはpendingのままロックされており、teammateやリードが明示的に無視しない限り取得の対象になりません。誤って着手できてしまう設計にはなっていません。

タスクの数はいくつが目安か

明確な上限はありませんが、teammate 1体あたり5〜6タスクを目安に分割すると、誰かが詰まったときにリードが別のteammateへ再割当しやすくなります。チームサイズとタスク粒度の設計指針そのものは、チームを何体編成するかという判断と合わせて考える必要があり、ここで説明したタスクの割当・取得・依存関係の仕組みは、Agent Teamsとサブエージェントの違いで説明した「独立したコンテキストを持つteammate同士が直接調整する」という設計の中核部分でもあります。

まとめ

Agent Teamsのタスク割当は、リードによる明示指定とteammateによる自己claimの2方式を持ち、依存関係のあるタスクは前提が終わるまで取得できません。依存関係の解除は自動ですが、teammateが完了マークを付け忘れる既知の不具合があるため、タスクが詰まったと感じたら状態を自分で確認する習慣を持つとよいでしょう。タスクの粒度を「明確な成果物を1つ生むまとまり」に揃えることが、割当そのものの効率を上げる一番の近道です。タスク完了の基準を機械的に強制したい場合は、TaskCompletedフックで品質ゲートを強制する方法と組み合わせると、テストが通っていないタスクを完了扱いにできなくなります。