task-coordinator

タスクコーディネーター

ワークフローのオーケストレーションに Claude Code のネイティブ Task システムを統合するパターンです。

使用する場面

• 進捗を可視化する必要がある、3 ステップ以上の連続したステップがあるワークフロー
• 依存関係の追跡が必要な並列実行
• クラッシュからの復旧が必要な、長時間実行されるワークフロー
• 永続的な状態を必要とする、セッションをまたぐ作業

設定チェック（ガードパターン）

TASK_TRACKING = config_read("task_tracking.enabled", "false")
LEDGER_ENABLED = config_read("task_tracking.ledger", "false")
LEDGER_PATH = config_read("task_tracking.ledger_path", ".agents/workflow-ledger.yml")
AUTO_CLEANUP = config_read("task_tracking.auto_cleanup", "true")

If NOT TASK_TRACKING: skip all Task operations, run workflow normally

タスクのライフサイクル

1. 作成

TASK = TaskCreate(
  subject: "Imperative verb phrase",     # "Run security review"
  description: "What and why",
  activeForm: "Present continuous form",  # "Running security review"
  metadata: {
    workflow: WORKFLOW_ID,
    step: STEP_NUMBER,
    milestone: true|false,
    phase: "phase-name",
    parallel_group: "group-id"
  }
)

2. 完全なステップパターン

If TASK_TRACKING:
  STEP_TASK = TaskCreate(subject: "Step N: Name", activeForm: "Doing name", metadata: {...})
  TaskUpdate(STEP_TASK.id, status: "in_progress")

... existing step logic (unchanged) ...

If TASK_TRACKING:
  TaskUpdate(STEP_TASK.id, status: "completed")

If LEDGER_ENABLED AND step.milestone:
  Write checkpoint -> LEDGER_PATH

メタデータの規約

キー	型	目的	例
workflow	文字列	タスクを 1 つのワークフロー実行にまとめます	"build-task-abc123"
step	整数	ワークフロー内のステップ番号	4
milestone	真偽値	ステップが台帳のチェックポイントを作成するかどうか	true
phase	文字列	複数フェーズのワークフローにおける名前付きフェーズ	"discovery"
parallel_group	文字列	並列で起動されたタスクをまとめます	"reviewers"

ワークフロー ID の形式："{workflow-name}-{timestamp}"（例："build-task-20260213T1430"）

依存関係のマッピング

TASK_A = TaskCreate(subject: "Foundation step", ...)
TASK_B = TaskCreate(subject: "Depends on A", ...)
TaskUpdate(TASK_B.id, addBlockedBy: [TASK_A.id])

ルール：

• まずすべてのタスクを作成し、その後で依存関係を設定します
• ブロックされているタスクは、ブロッカーが完了するまで割り当てられません

複数フェーズの例：

PHASES = [
  {name: "Discovery", deps: []},
  {name: "Architecture", deps: ["Discovery"]},
  {name: "Implementation", deps: ["Architecture"]},
  {name: "Review", deps: ["Implementation"]}
]

PHASE_TASKS = {}
For each P in PHASES:
  PHASE_TASKS[P.name] = TaskCreate(
    subject: "Phase: {P.name}",
    activeForm: "Running {P.name}",
    metadata: {workflow: WORKFLOW_ID, phase: P.name}
  )

For each P in PHASES:
  If P.deps is not empty:
    BLOCKER_IDS = [PHASE_TASKS[d].id for d in P.deps]
    TaskUpdate(PHASE_TASKS[P.name].id, addBlockedBy: BLOCKER_IDS)

並列実行

まずすべてのタスクを作成し、並列実行するために 1 つのメッセージで Task エージェントを起動します。

GROUP_ID = "reviewers-{WORKFLOW_ID}"

REVIEWER_TASKS = []
For each REVIEWER in REVIEWER_LIST:
  T = TaskCreate(
    subject: "Run {REVIEWER}",
    activeForm: "Running {REVIEWER}",
    metadata: {workflow: WORKFLOW_ID, parallel_group: GROUP_ID, reviewer: REVIEWER}
  )
  REVIEWER_TASKS.append(T)

# Launch ALL agents in a SINGLE message (enables parallelism)
For each T in REVIEWER_TASKS:  # all in ONE message
  Task(subagent_type: T.metadata.reviewer, prompt: "...", run_in_background: true)

# Collect results
For each T in REVIEWER_TASKS:
  RESULT = wait for agent completion
  TaskUpdate(T.id, status: "completed")

重要なルール： すべての Task() 呼び出しは、同じ応答メッセージ内に含める必要があります。メッセージを分けると、逐次実行になります。

結果の集約

ALL_TASKS = TaskList()
GROUP_TASKS = [T for T in ALL_TASKS where T.metadata.parallel_group == GROUP_ID]
COMPLETED = [T for T in GROUP_TASKS where T.status == "completed"]
FAILED = [T for T in GROUP_TASKS where T.status != "completed"]

If FAILED is not empty: Handle failures per error table
Else: Aggregate results from COMPLETED tasks

台帳チェックポイントパターン

マイルストーンとなるステップでクラッシュから復旧するための YAML ベースの記録です。

スキーマ

version: 1
workflow_id: "build-task-20260213T1430"
workflow_type: "build-task"
started_at: "2026-02-13T14:30:00Z"
last_checkpoint: "2026-02-13T14:35:00Z"
current_step: 4
status: "in_progress"  # in_progress | completed | failed
checkpoints:
  - step: 1
    name: "Workspace setup"
    status: "completed"
    completed_at: "2026-02-13T14:31:00Z"
    data: {}

チェックポイントの書き込み

If LEDGER_ENABLED AND step.milestone:
  CHECKPOINT = {step: STEP_NUMBER, name: STEP_NAME, status: "completed", completed_at: NOW(), data: {...}}
  Read existing ledger from LEDGER_PATH (or create new)
  Append CHECKPOINT to checkpoints array
  Update last_checkpoint, current_step
  Write ledger to LEDGER_PATH

ワークフロー別のマイルストーンステップ

ワークフロー	マイルストーンステップ
build-task	ワークスペースのセットアップ (1)、ビルド (4)、検証 (5)、品質 (7)、出荷 (9)
blueprint	調査 (1)、アーキテクチャ (4)、計画の作成 (6)、実行 (9)
run-blueprint	タスクの作成 (2)、各タスクの完了
quality-gate	各レビュアーの完了、最終判定

クラッシュからの再開

If LEDGER_ENABLED:
  LEDGER = Read LEDGER_PATH
  If LEDGER exists AND LEDGER.status == "in_progress":
    LAST_STEP = LEDGER.current_step
    COMPLETED_STEPS = [C.step for C in LEDGER.checkpoints where C.status == "completed"]
    For each STEP in WORKFLOW_STEPS:
      If STEP.number in COMPLETED_STEPS: skip
      Else: Execute STEP

復旧判断表：

台帳の状態	アクション
台帳ファイルなし	新規に開始
status: completed	新規に開始（前回の実行は完了しています）
status: in_progress	最後のチェックポイントから再開
status: failed	失敗したステップから再開
台帳の解析エラー	警告を記録し、新規に開始

セッションをまたぐ永続化

# At workflow start: export task list ID
TASK_LIST_ID = current task list identifier
Set env: CLAUDE_CODE_TASK_LIST_ID = TASK_LIST_ID

# In new session: restore task list
If env CLAUDE_CODE_TASK_LIST_ID is set:
  Restore task list from CLAUDE_CODE_TASK_LIST_ID
  ALL_TASKS = TaskList()
  Resume from incomplete tasks

注： セッションをまたいで永続化するには、タスクリスト ID を外部（環境変数、ファイル、または台帳）に保存する必要があります。

クリーンアップ

If TASK_TRACKING AND workflow completed successfully:
  If AUTO_CLEANUP:
    ALL_TASKS = TaskList()
    WORKFLOW_TASKS = [T for T in ALL_TASKS where T.metadata.workflow == WORKFLOW_ID]
    For each T in WORKFLOW_TASKS:
      TaskUpdate(T.id, status: "completed")

  If LEDGER_ENABLED:
    Update ledger: status = "completed", last_checkpoint = NOW()

エラー処理

エラー	アクション
TaskCreate の失敗	警告を記録し、追跡なしで続行
TaskUpdate の失敗	1 回再試行し、その後ログを記録して続行
TaskList のタイムアウト	利用可能な場合は台帳にフォールバック
TaskGet が古いデータを返す	更新前に再取得
台帳の書き込み失敗	警告を記録し、チェックポイントなしで続行
台帳の解析エラー	警告を記録し、新規開始として扱う
依存関係の循環を検出	エラーを記録し、循環を取り除いて続行

原則： タスク追跡の失敗によって、ワークフローの実行を決して妨げてはなりません。常に適切に機能を縮退させます。

状態の関係

+---------------------------+     +---------------------------+
|     Native Tasks          |     |     YAML Ledger           |
|  (TaskCreate/Update/List) |     |  (.agents/workflow-ledger) |
+---------------------------+     +---------------------------+
|  Source of truth for:     |     |  Supplementary for:       |
|  - Current step status    |     |  - Crash recovery         |
|  - Dependency tracking    |     |  - Cross-session resume   |
|  - Progress visibility    |     |  - Milestone receipts     |
|  - Parallel coordination  |     |  - Audit trail            |
+---------------------------+     +---------------------------+
         PRIMARY                         SECONDARY

If conflict: Tasks win. Ledger is advisory only.