task-dependency-patterns

タスク依存関係のパターン

概要

Claude Code 2.1.16 では、4 つのツールを備えたネイティブのタスク管理システムが導入されました。

CC 2.1.268 に関する注意事項： TaskCreate、TaskGet、TaskUpdate、TaskList、TodoWrite は、Claude 3.x、Opus 4.0～4.7、Sonnet 4.0～4.6、および Haiku 4.5 でのみ提供されます。この許可リストに含まれないモデルでは、オペレーターが CLAUDE_CODE_ENABLE_TODO_TOOLS=1 を設定しない限り、これらのツールは利用できません。CC がこのフラグを有効にするのは、ユーザー設定または管理者設定（あるいはシェル）から指定された場合のみです。ork からは設定できません（CC はプラグイン設定のうち permissions だけを読み取るため）。このスキルでの Task ツール呼び出しはすべて、オペレーターの環境に応じて利用できるものとして扱ってください。

• TaskCreate：件名、説明、activeForm を指定して新しいタスクを作成します
• TaskUpdate：ステータス（pending → in_progress → completed）を更新し、依存関係を設定します
• TaskGet：ブロッカーを含むタスクの詳細を取得します
• TaskList：ステータスと依存関係の概要を含むすべてのタスクを表示します

タスクを使うと、作業を体系的に追跡し、並行作業を調整し、進捗を明確に把握できます。

使用する場面

• 複雑な複数ステップの実装を分割する
• 複数のファイルにまたがる並行作業を調整する
• 大規模な機能の進捗を追跡する
• 関連する変更間の依存関係を管理する
• 作業状況を可視化する

主なパターン

1. タスクの分解

複雑な作業を、個別に追跡可能な単位に分割します。

Feature: Add user authentication

Tasks:
#1. [pending] Create User model
#2. [pending] Add auth endpoints (blockedBy: #1)
#3. [pending] Implement JWT tokens (blockedBy: #2)
#4. [pending] Add auth middleware (blockedBy: #3)
#5. [pending] Write integration tests (blockedBy: #4)

2. 依存関係の連鎖

addBlockedBy を使って実行順序を設定します。

// Task #3 cannot start until #1 and #2 complete
{"taskId": "3", "addBlockedBy": ["1", "2"]}

3. ステータスのワークフロー

pending → in_progress → completed
   ↓           ↓
(unblocked)  (active)

pending/in_progress → deleted

• pending：タスクは作成済みですが、未着手です
• in_progress：作業中です
• completed：作業が完了し、検証済みです
• deleted：タスクを削除します — タスクを完全に削除します

タスクの削除

status: "deleted" を使って、タスクを完全に削除します。

// Delete a task
{"taskId": "3", "status": "deleted"}

削除する場面：

• すべてのブロッカーが失敗した、孤立したタスク
• 別の方法に置き換えられたタスク
• 誤って作成された重複タスク
• キャンセルされたパイプラインのタスク

削除しない場面：

• 後で再試行する可能性のあるタスク（pending のままにします）
• 有用な履歴があるタスク（代わりに completed にします）
• in_progress の作業によってブロックされているタスク（解決を待ちます）

4. activeForm パターン

スピナー表示用に現在進行形の表現を指定します。

subject（命令形）	activeForm（進行形）
Run tests	テストを実行中
Update schema	スキーマを更新中
Fix authentication	認証を修正中

エージェントチーム

エージェントチームでは、共有タスクリストとエージェント間メッセージングを使って、複数のエージェントを連携させられます。

CC 2.1.161 — 並列ツール呼び出しの独立した失敗： 並列バッチ内のツール呼び出しが失敗しても、他の呼び出しはキャンセルされなくなりました。それぞれが個別の結果を返します。チームメイトはバッチ全体が中断されたと決めつけず、タスクのステータスを個別に確認し、失敗に明示的に対処する必要があります。

チームのワークフロー

1. (implicit team — CC 2.1.178+)       → one team per session; no TeamCreate
2. TaskCreate(subject, description)    → Add tasks to shared list
3. Agent(name, team_name, prompt)      → Spawn teammates into the implicit team
4. TaskUpdate(owner: "teammate-name")  → Assign tasks
5. SendMessage(to, message, summary)   → Direct teammate communication
6. (turn / background ends)            → teammates wind down; Ctrl+F x2 for bg

セッション間の返信は親に届きます（CC 2.1.248）： サブエージェントが別のセッションに SendMessage を送信した場合、返信はサブエージェントではなく、親セッションの会話に届きます。サブエージェントはメッセージを送信したら作業を続け、親が返信を確認します。セッション間の SendMessage / ListAgents は、テレメトリが無効な場合でも、Bedrock、Vertex、Foundry で使用できます（CC 2.1.248）。

チームと Agent ツールの使い分け

基準	Agent ツール（サブエージェント）	エージェントチーム
独立したタスク	はい	過剰です
横断的な変更	限定的	はい
エージェント間の会話	いいえ（スター型トポロジー）	はい（メッシュ型）
コスト重視	低い（約 1 倍）	高い（約 2.5 倍）
複雑さ < 3.0	はい	いいえ
複雑さ > 3.5	可能	推奨

チームのタスクパターン

# Spawn teammate into shared task list. A teammate that writes files works in
# a manual worktree the lead creates first (#4557); the lead merges its branch
# before dependent tasks start. No isolation on the call: a call with name and
# isolation launches a plain subagent, not a teammate (Claude Code docs).
Bash("git worktree add .worktrees/backend -b feat/my-feature-backend feat/my-feature")
Agent(
  prompt="You are the backend architect... Work only in .worktrees/backend/ "
         "(cd there, check pwd and branch first). Commit your work there and "
         "message the lead your branch name and commit sha.",
  team_name="my-feature",
  name="backend-architect",
  subagent_type="ork:backend-system-architect"
)

# Teammate claims and works tasks
TaskList → find unblocked, unowned tasks
TaskUpdate(taskId, owner: "backend-architect", status: "in_progress")
# ... do work ...
TaskUpdate(taskId, status: "completed")
TaskList → find next task

ピアメッセージング

# Direct message between teammates (params: to, message, summary)
SendMessage(to: "frontend-dev",
  message: "API contract ready: GET /users/:id returns {...}",
  summary: "API contract shared")

# No broadcast primitive — send to each teammate, or post to the shared
# task list (TaskCreate/TaskUpdate) so every teammate sees it
SendMessage(to: "backend-dev",
  message: "Breaking change: auth header format changed",
  summary: "Breaking auth change")

コンテキスト枯渇への対応

Agent Teams の使用中に、ワークフローの途中でコンテキストの上限に達した場合：

• TaskList を使って、完了済みのチームメイトから部分的な結果を収集します
• 利用可能な出力を統合します。何も報告せずに失敗するより、部分的な結果を優先します
• スキップしたタスクは、TaskUpdate(taskId: task_id, status: "completed", metadata: {"skipped": "context limit"}) で記録します

アンチパターン

• 単純な1ステップの作業にタスクを作成する
• 循環依存関係（A が B をブロックし、B が A をブロックする）
• ブロックされているタスクを in_progress のままにする
• 完了後にタスクを完了済みとしてマークしない
• チームメイト1人だけに関係するメッセージにブロードキャストを使う
• 単純な逐次作業にチームを立ち上げる（代わりに Agent ツールを使います）

関連スキル

• ork:implement - タスク追跡と進捗更新を含む実装ワークフロー
• ork:verify - 検証タスクと完了チェックリスト
• ork:fix-issue - 仮説に基づく RCA の追跡を含む問題解決
• ork:brainstorm - エージェントタスクを並列で実行する設計検討

参考資料

Read("references/<file>") で必要に応じて読み込みます：

ファイル	内容
dependency-tracking.md	依存関係追跡のパターン
status-workflow.md	ステータスワークフローの詳細
multi-agent-coordination.md	マルチエージェントの連携