Claude Task の仕組みと使い方｜タスク作成から並列実行まで

Claude Task とは — 進捗を追跡する新しい仕組み

Anthropic の公式 Task ドキュメントによると、Claude Code は複雑な作業を依頼された際、進捗をユーザーに見せながら整理するために Task システムを使います。Claude Code v2.1.142 以降では従来の TodoWrite が廃止され、TaskCreate / TaskUpdate / TaskGet / TaskList の 4 ツールへと責務が分割されました。

Task が自動作成される場面:

• 3 ステップ以上の複雑な多段作業
• ユーザーが複数の項目を列挙して依頼した場合
• 「進捗を見せながら進めて」と明示的に指示した場合
• 自明でない操作でユーザーへの可視化が有益な場合

Task のライフサイクルは pending → in_progress → completed の順に進み、全タスクが完了するとリストは自動で消去されます。削除したい場合は TaskUpdate で status: "deleted" を指定します。

TaskCreate — 1 件ずつ作成するのがポイント

旧 TodoWrite は複数の Todo を配列で一括書き換えする設計でしたが、TaskCreate は 1 件ずつ作成 するシングル操作です。

TaskCreate(
  subject: "認証モジュールの単体テストを追加",
  description: "login / logout / refresh の 3 フローをカバー",
  activeForm: "テストを書いています…"
)

引数の概要:

• subject（必須）: タスクのタイトル
• description: 詳細な説明文
• activeForm: in_progress 状態で表示する動的テキスト
• metadata: 任意の追加情報

TaskCreate 呼び出しに対するレスポンスには task_id が含まれます。この ID が後続の TaskUpdate / TaskGet でキーになります。SDK から外部監視している場合は tool_result ブロックの { "task": { "id": "...", "subject": "..." } } から取り出して保持してください。

TaskUpdate — ステータスを細かく制御する

TaskUpdate は taskId を指定して特定タスクを個別に更新します。作業開始時に in_progress、完了時に completed にセットするだけで、ユーザーの画面に進捗が反映されます。

TaskUpdate(taskId: "abc123", status: "in_progress")
# ...実作業...
TaskUpdate(taskId: "abc123", status: "completed")

変更できるフィールド:

• status: pending / in_progress / completed / deleted
• subject, description, activeForm: 内容の修正
• addBlocks: 依存タスクの追加
• addBlockedBy: 先行タスク依存の設定
• owner: タスク担当者の変更（Agent Teams で有効）

TaskGet と TaskList — 現状を把握する

TaskGet は taskId を指定して単一タスクの最新スナップショットを取得します。TaskList は全タスク、または filter で絞った一覧を返します。

# 未完了タスクを確認
TaskList(filter: "in_progress")

# 特定タスクの状態を確認
TaskGet(taskId: "abc123")

作業が途中で中断されたときに Claude 自身が TaskList を呼んで「何が残っているか」を把握する場面でよく使われます。外部コードで進捗ダッシュボードを作りたい場合も、ストリームから TaskList の tool_result を捕捉する方法が使えます。

TaskStop と TaskOutput — バックグラウンドセッションを管理する

TaskStop と TaskOutput は、バックグラウンドで動作している Claude Code セッションを制御するためのツールです。

• TaskOutput: 動作中のバックグラウンドセッションの現在の出力を取得
• TaskStop: セッションを安全に停止（現在のリクエストやツール呼び出しが完了してから停止）

エージェントビュー（claude agents で起動）は複数のバックグラウンドセッションを「Needs input / Working / Completed」の 3 ステートで一覧表示するインターフェイスです。長時間かかるリファクタリングや CI 解析などをバックグラウンドに委ねながら別の作業を並行するような使い方が典型例です。

Agent Teams の共有タスクリスト

Agent Teams（Claude Code v2.1.32 以降・実験的機能）では、複数の Claude Code インスタンスが 共有タスクリスト を介して協調します。

有効化方法:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

仕組み:

1. チームリーダーがタスクリストを作成
2. チームメンバーが自律的にタスクをクレーム（受け取り）
3. ファイルロックで二重クレームを防止
4. 依存関係が設定されたタスクは前提タスク完了まで待機

典型的なプロンプト:

PR #42 を 3 つの視点でレビューしてほしい。
- セキュリティ: 認証・セッション管理・入力検証に絞る
- パフォーマンス: DB クエリと API レイテンシに絞る
- テスト: カバレッジとテスト品質に絞る

このプロンプト一つで 3 セッションが並列起動し、それぞれが独立してタスクをクレームして実行します。完了後、リーダーが 3 つの知見を統合します。

フックで品質ゲートも設定できます:

• TeammateIdle: チームメンバーがアイドルになる前に実行
• TaskCreated: タスク作成時に検証、exit 2 で作成を阻止
• TaskCompleted: 完了マーク前に検証、exit 2 で完了を阻止

Python / TypeScript SDK でタスク状態を監視する

Claude Code を SDK 経由でプログラム制御している場合、アシスタントのストリームに含まれる tool_use ブロックを読み取ることで、タスクの進捗をリアルタイムに取得できます。

from claude_agent_sdk import query, AssistantMessage, ToolUseBlock

async for message in query(prompt="React アプリのパフォーマンスを最適化して"):
    if not isinstance(message, AssistantMessage):
        continue
    for block in message.content:
        if not isinstance(block, ToolUseBlock):
            continue
        if block.name == "TaskCreate":
            print(f"📋 作成: {block.input['subject']}")
        elif block.name == "TaskUpdate":
            status = block.input.get("status", "")
            icon = "✅" if status == "completed" else "🔧" if status == "in_progress" else "⏳"
            print(f"{icon} 更新: {block.input['taskId']} → {status}")

task_id は TaskCreate の tool_result から取得します。TaskCreate の 入力には task_id は含まれません。対応する tool_result ブロックとして { "task": { "id": "...", "subject": "..." } } の形で返されるため、マップに蓄積してください。

公式の Todo Tracking ガイドには TypeScript と Python 両方のサンプルコードが掲載されています。

TodoWrite との比較と移行ポイント

Task ツールへの切り替えは TypeScript Agent SDK 0.3.142 / Claude Code v2.1.142 でデフォルト有効になっています。旧来の TodoWrite 動作が必要な場合は CLAUDE_CODE_ENABLE_TASKS=0 で戻せます。

Python での詳細な移行手順は「Claude Agent SDK Python｜TodoWrite 廃止と Task tools 移行」に整理しています。

よくある実践パターン

大規模リファクタリング

複数ファイルにまたがるリファクタリングでは、Claude Code が自動的にファイルごとのタスクを作成し、進捗を in_progress → completed で追跡します。途中でセッションが中断しても、TaskList で残タスクを確認して再開できます。

CI / CD パイプラインへの組み込み

GitHub Actions 連携では、PR ごとに自動コードレビューを実行し、各確認項目を Task として追跡します。セキュリティ・パフォーマンス・テストカバレッジを並列で確認し、レビュー結果はコメントとして PR に投稿されます。

競合仮説による並列デバッグ

根本原因が不明なバグに対して複数の仮説を立て、それぞれを独立したセッションで並行調査する手法です。Agent Teams の共有タスクリストを使い、各セッションが担当仮説をクレームして独立検証します。一つのセッションだけで調査すると確証バイアスが起きやすい問題を、並列仮説検証が緩和します。