task-management-protocol

タスク管理プロトコル

Claude Code のネイティブなタスクツールを使用して、エージェントとセッション間のタスク同期、進捗追跡、コンテキストの引き継ぎを行うための標準化されたプロトコルです。

問題の説明

バックグラウンドエージェントが作業を完了しても、メインセッションに通知が届きません。エージェントは調査結果をタスクの説明に反映しません。エージェント間またはセッション間で構造化されたコンテキストを引き継ぐためのプロトコルがありません。

このスキルで解決すること：

1. セッション終了時やエージェントの作業完了時にコンテキストが失われる
2. バックグラウンドエージェントの調査結果がメインセッションに伝わらない
3. タスクの可視性が低く、作業が重複する
4. エージェント間で情報を渡すための構造化された方法がない

コアツールのリファレンス

ツール	目的	使用するタイミング
TaskList()	ステータス付きで全タスクを一覧表示	作業開始時、完了後
TaskGet(id)	タスクの詳細を取得	割り当てられたタスクの開始前
TaskCreate(...)	新しいタスクを作成	計画段階、サブタスクを発見したとき
TaskUpdate(...)	ステータス／メタデータを更新	進捗、発見事項、完了時

計画ファイル更新プロトコル（絶対遵守）

タスクが計画ファイル（.claude/context/plans/*.md）の一部である場合、タスクを実行するエージェントが、ルーターではなく、タスクマーカーを更新する責任を負います。

タスク開始時：計画ファイル内のタスク行を見つけ、- [ ] を - [~] に変更します。

タスク完了時：- [~] を - [x] に変更し、結果を1行で追記します。

ツール：該当する行に対して Edit を使用します。ファイル全体を書き換えてはいけません。

タイミング：TaskUpdate(completed) を呼び出す前に計画ファイルを更新します。

ファイルがない場合：計画ファイルが存在しなければ、何も通知せずにスキップします。エラーにしてはいけません。

# Find the line number
grep -n "task subject keywords" .claude/context/plans/my-plan.md

# Then use Edit to change [ ] → [~] on start, [~] → [x] on complete

アンチパターン：計画ファイルの更新をルーターに任せること。ルーターに見えるのは完了したタスクだけです。計画ファイルは実行中にリアルタイムで更新する必要があります。

---

プロトコル

フェーズ 1：セッション開始（必須）

作業を始める前に、必ず以下の手順を実行します：

// Step 1: Check existing tasks
TaskList();

// Step 2: If assigned task exists, read full details
TaskGet({ taskId: '<assigned-id>' });

// Step 3: Claim the task
TaskUpdate({
  taskId: '<assigned-id>',
  status: 'in_progress',
  activeForm: 'Working on <task-subject>',
});

重要な理由：

• 作業の重複を防ぎます（すでに進行中の作業を確認できます）
• タスクの説明から完全なコンテキストを取得できます
• 他のエージェント／セッションに作業の開始を知らせます

フェーズ 2：作業中（進捗の更新）

以下の場合にタスクを更新します：

• 重要な情報を発見したとき
• ブロッカーを見つけたとき
• サブタスクを特定したとき
• 大幅に進捗したとき

発見事項の更新パターン

// When you discover something important
TaskUpdate({
  taskId: 'X',
  description: `ORIGINAL: <original-description>

## Discoveries (${new Date().toISOString().split('T')[0]})
- Found: <what you discovered>
- Files: <relevant files>
- Impact: <why this matters>`,
  metadata: {
    discoveredFiles: ['path/to/file1.ts', 'path/to/file2.ts'],
    discoveries: ['Pattern X found', 'Dependency Y required'],
    lastUpdated: new Date().toISOString(),
  },
});

ブロッカーの更新パターン

// When you hit a blocker
TaskUpdate({
  taskId: 'X',
  description: `<existing-description>

## BLOCKED (${new Date().toISOString().split('T')[0]})
- Blocker: <what's blocking>
- Needs: <what's required to unblock>
- Workaround: <possible workaround if any>`,
  metadata: {
    status: 'blocked',
    blocker: 'Description of blocker',
    blockerType: 'dependency|permission|information|external',
    needsFrom: 'user|other-agent|external-system',
  },
});

サブタスクの作成パターン

// When you discover subtasks
TaskCreate({
  subject: 'Subtask: <specific-task>',
  description: `Parent: Task #X

## Context
<why this subtask exists>

## Scope
<specific work to be done>

## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>`,
  activeForm: 'Working on <subtask>',
});

// Link to parent
TaskUpdate({
  taskId: '<new-subtask-id>',
  addBlockedBy: ['X'], // This subtask blocks parent completion
});

フェーズ 3：完了（必須）

構造化メタデータなしでタスクを完了にしてはいけません：

TaskUpdate({
  taskId: 'X',
  status: 'completed',
  description: `<original-description>

## Completed (${new Date().toISOString().split('T')[0]})
- Summary: <one-line summary of what was done>
- Files modified: <list>
- Tests: <passed/added/none>`,
  metadata: {
    summary: 'Concise summary of completed work',
    filesModified: ['path/to/file1.ts', 'path/to/file2.ts'],
    filesCreated: ['path/to/new.ts'],
    testsAdded: true,
    testsPassing: true,
    outputArtifacts: ['.claude/context/reports/backend/my-report.md'],
    nextSteps: ['Optional follow-up', 'Another consideration'],
    completedAt: new Date().toISOString(),
  },
});

// Check for newly unblocked tasks
TaskList();

フェーズ 4：セッション終了／引き継ぎ

未完了の作業を残してセッションを終了する前に：

// Update all in-progress tasks with current state
TaskUpdate({
  taskId: 'X',
  description: `<existing-description>

## Session Paused (${new Date().toISOString().split('T')[0]})
- Progress: <what was accomplished>
- Current state: <where things stand>
- Next step: <immediate next action>
- Files to review: <key files>`,
  metadata: {
    sessionPaused: true,
    progress: '60%',
    currentState: 'Description of current state',
    immediateNextStep: 'The very next thing to do',
    keyFiles: ['file1.ts', 'file2.ts'],
    keyDecisions: ['Decision 1', 'Decision 2'],
    pausedAt: new Date().toISOString(),
  },
});

コンテキスト引き継ぎの構造

引き継ぎ用メタデータスキーマ

エージェント間でコンテキストを引き継ぐ際は、以下の一貫した構造を使用します：

interface TaskHandoffMetadata {
  // Progress tracking
  status?: 'not_started' | 'in_progress' | 'blocked' | 'completed';
  progress?: string; // e.g., "60%", "3/5 steps"

  // Discovery context
  discoveredFiles?: string[];
  discoveries?: string[];
  patterns?: string[];

  // Blocker information
  blocker?: string;
  blockerType?: 'dependency' | 'permission' | 'information' | 'external';
  needsFrom?: string;

  // Completion context
  summary?: string;
  filesModified?: string[];
  filesCreated?: string[];
  outputArtifacts?: string[];

  // Continuation context
  currentState?: string;
  immediateNextStep?: string;
  keyFiles?: string[];
  keyDecisions?: string[];

  // Timestamps
  lastUpdated?: string;
  completedAt?: string;
  pausedAt?: string;
}

引き継ぎコンテキストの読み取り

別のエージェントが作業したタスクに着手するとき：

// Get full task details including metadata
const task = TaskGet({ taskId: 'X' });

// Check metadata for context
if (task.metadata?.sessionPaused) {
  // Previous session paused - read currentState and immediateNextStep
}
if (task.metadata?.discoveries) {
  // Previous agent found things - review discoveries array
}
if (task.metadata?.blocker) {
  // Task was blocked - check if blocker is resolved
}

セッション間の連携

環境変数：CLAUDE_CODE_TASK_LIST_ID

この環境変数を使用して、セッション間でタスクリストを共有します：

# Set shared task list for all sessions
export CLAUDE_CODE_TASK_LIST_ID="my-project-tasks"

# Start claude code - will use shared task list
claude

使用するタイミング：

• 複数のターミナルで同じプロジェクトに取り組むとき
• タスクの状態を共有するバックグラウンドエージェントを使うとき
• タスクリストを使ってチームで共同作業するとき

共有タスクリストのパターン

// Session A creates task
TaskCreate({
  subject: 'Implement feature X',
  description: '...',
  metadata: {
    owner: 'session-a',
    priority: 'high',
  },
});

// Session B (same CLAUDE_CODE_TASK_LIST_ID) picks up task
TaskList(); // Sees task from Session A
TaskUpdate({
  taskId: '1',
  status: 'in_progress',
  metadata: {
    owner: 'session-b', // Claims ownership
    previousOwner: 'session-a',
  },
});

絶対遵守事項（必ず守ること）

1. 要約なしで完了にしない

// WRONG - No context for future reference
TaskUpdate({ taskId: 'X', status: 'completed' });

// CORRECT - Full context preserved
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: 'Added auth middleware with JWT validation',
    filesModified: ['src/middleware/auth.ts'],
    completedAt: new Date().toISOString(),
  },
});

2. 発見事項は必ず更新する

// WRONG - Discoveries lost
// ... agent finds important pattern but doesn't record it ...

// CORRECT - Discoveries preserved
TaskUpdate({
  taskId: 'X',
  metadata: {
    discoveries: [...existingDiscoveries, 'Found circular dependency in module X'],
  },
});

3. 完了後は必ず TaskList を実行する

// WRONG - May have unblocked other tasks
TaskUpdate({ taskId: "X", status: "completed" });
// ... session ends ...

// CORRECT - Check for follow-up work
TaskUpdate({ taskId: "X", status: "completed", metadata: {...} });
TaskList();  // Find newly unblocked tasks

4. 構造にはメタデータ、文章には説明を使う

// WRONG - Structured data in prose
TaskUpdate({
  taskId: 'X',
  description: 'Files: a.ts, b.ts. Blocked by: auth issue. Progress: 50%',
});

// CORRECT - Structured metadata + prose description
TaskUpdate({
  taskId: 'X',
  description: 'Implementing auth flow. Hit a blocker with token refresh.',
  metadata: {
    filesModified: ['a.ts', 'b.ts'],
    blocker: 'auth issue',
    progress: '50%',
  },
});

Memory Protocol との統合

タスクのメタデータは Memory Protocol を補完するものであり、置き換えるものではありません。

情報の種類	タスクのメタデータ	メモリファイル
タスク固有の発見事項	はい	いいえ
プロジェクト全体のパターン	参照のみ	はい（learnings.md）
アーキテクチャ上の決定事項	参照のみ	はい（decisions.md）
ブロッキング問題	はい	はい（issues.md）
進捗状況	はい	いいえ
完了の概要	はい	はい（learnings.md）

パターン：

1. タスク固有のコンテキストをタスクのメタデータに記録します
2. プロジェクト全体の学びをメモリファイルに記録します
3. 相互に参照できるようにします

// Task completion with memory reference
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: 'Implemented auth flow',
    memoryUpdates: ['learnings.md: JWT refresh pattern', 'decisions.md: ADR-005 auth architecture'],
  },
});

例

例 1：機能を完了する開発者エージェント

// Start
TaskList();
TaskGet({ taskId: '5' });
TaskUpdate({ taskId: '5', status: 'in_progress', activeForm: 'Implementing login flow' });

// Discovery during work
TaskUpdate({
  taskId: '5',
  metadata: {
    discoveries: ['Existing auth module at src/auth/', 'Uses JWT not sessions'],
    keyFiles: ['src/auth/jwt.ts', 'src/middleware/auth.ts'],
  },
});

// Completion
TaskUpdate({
  taskId: '5',
  status: 'completed',
  metadata: {
    summary: 'Added login endpoint with JWT auth',
    filesCreated: ['src/routes/login.ts', 'src/routes/login.test.ts'],
    filesModified: ['src/routes/index.ts'],
    testsAdded: true,
    testsPassing: true,
    completedAt: new Date().toISOString(),
  },
});
TaskList(); // Check for unblocked tasks

例 2：引き継ぎを行うバックグラウンドエージェント

// Background agent starting long task
TaskUpdate({
  taskId: '10',
  status: 'in_progress',
  metadata: { runningInBackground: true },
});

// Progress update (multiple during execution)
TaskUpdate({
  taskId: '10',
  metadata: {
    progress: '40%',
    currentState: 'Processed 400/1000 files',
    discoveries: ['Found 12 security issues', '3 critical in auth module'],
  },
});

// Completion - main session can check this
TaskUpdate({
  taskId: '10',
  status: 'completed',
  metadata: {
    summary: 'Security scan complete: 12 issues found (3 critical)',
    outputArtifacts: ['.claude/context/reports/security/security-scan.md'],
    criticalFindings: 3,
    highFindings: 5,
    mediumFindings: 4,
    completedAt: new Date().toISOString(),
  },
});

例 3：複数エージェントの連携

// Planner creates tasks with dependencies
TaskCreate({ subject: 'Design auth system', description: '...', activeForm: 'Designing auth' });
TaskCreate({
  subject: 'Implement auth backend',
  description: '...',
  activeForm: 'Implementing auth',
});
TaskCreate({ subject: 'Add auth tests', description: '...', activeForm: 'Testing auth' });

TaskUpdate({ taskId: '2', addBlockedBy: ['1'] }); // Implementation blocked by design
TaskUpdate({ taskId: '3', addBlockedBy: ['2'] }); // Tests blocked by implementation

// Architect completes design
TaskUpdate({
  taskId: '1',
  status: 'completed',
  metadata: {
    summary: 'Auth design complete - JWT with refresh tokens',
    outputArtifacts: ['.claude/context/plans/auth-design.md'],
    keyDecisions: ['JWT over sessions', 'Redis for token store'],
  },
});

// Developer can now start (task 2 unblocked)
TaskList(); // Shows task 2 now available
TaskGet({ taskId: '2' }); // Gets design context from task 1's metadata

関連スキル

• session-handoff - セッション全体の引き継ぎドキュメントを作成します（複雑な引き継ぎに使用）
• operational-modes - タスク実行中のツール使用を自己調整します
• thinking-tools - タスク完了の品質を確認するチェックポイント

絶対遵守事項

1. 構造化されたメタデータ（summary、filesModified、completedAt）なしに、タスクを絶対に完了扱いにしないでください
2. 作業を開始する前に必ずTaskUpdate(in_progress)を呼び出してください。タスクを引き受けずに作業を始めてはいけません
3. 新たにブロック解除されたタスクがないか確認するためにTaskList()を呼び出さずに、作業を絶対に完了しないでください
4. 発見事項は後からまとめてではなく、その都度、タスクのメタデータに必ず追加してください
5. 説明文に構造化データを絶対に記載しないでください。機械可読フィールドにはmetadataフィールドを使用してください

アンチパターン

アンチパターン	失敗する理由	正しい方法
完了時に概要のメタデータがない	後続のエージェントが作業を引き継ぐためのコンテキストを得られない	完了メタデータには必ずsummary、filesModified、completedAtを含めます
作業前にin_progressを省略する	タスクの担当者が不明になり、重複作業が始まる	作業を開始する前に必ずTaskUpdate(in_progress)を呼び出します
完了後にTaskListを確認しない	新たにブロック解除されたタスクが停滞したままになる	各タスクの完了後に必ずTaskList()を呼び出します
説明文に構造化データを記載する	エージェントが解析できず、コンテキストが失われる	構造化データにはmetadataフィールドを、説明文には経緯を記載します
発見事項の更新を怠る	作業中に蓄積されたコンテキストがセッション終了時に失われる	後からまとめてではなく、発見事項をその都度メタデータに追加します

Memory Protocol（必須）

開始前： .claude/context/memory/learnings.mdを読みます

完了後：

• 新しいタスクパターンを発見した場合 -> .claude/context/memory/learnings.md
• タスクツールに関する問題がある場合 -> .claude/context/memory/issues.md
• タスク構造に関する決定事項がある場合 -> .claude/context/memory/decisions.md

中断されることを前提にしてください。タスクのメタデータに記録されていなければ、起きていないのと同じです。