long-running-tasks

name	long-running-tasks
description	状態の永続化と進捗トラッキングを伴う自律的なロングランニングタスクのパターン。 以下の場合に使用: - 追跡が必要な複数ステップのタスク - コンテキストウィンドウの制限を超える可能性のある作業 - セッション間で状態を永続化する必要がある場合 - 複雑なマイグレーション、リファクタリング、複数ファイルの変更 - ユーザーが「全部完了して」「自律的に実行」と言った場合 Trigger phrases: long task, autonomous, persist state, track progress, migration, refactoring, multi-step
allowed-tools	Read, Write, Glob, Grep, Bash, TodoWrite
model	sonnet
user-invocable	true

ロングランニングタスクパターン

単一セッションやコンテキストウィンドウを超える可能性のある複雑な複数ステップのタスクを管理するテクニック。

イニシャライザー + コーディングエージェントパターン

Anthropic の推奨パターンは 2 つの異なるロール を使用する:

1. イニシャライザーロール（初回セッションのみ）

初回実行時:

• .claude/workspaces/{workspace-id}/ にワークスペース進捗ファイルを作成
• タスクの全スコープを分析し、機能に分解
• git リポジトリの状態を初期化
• 将来のセッション用の再開コンテキストを記録

2. コーディングロール（各セッション）

各セッションで:

1. 進捗ファイルと git log を読み取り
2. 次の未完了機能を特定
3. 一度に 1 つの機能を実装（全部一度にやらない！）
4. 機能を手動または自動でテスト
5. 結果で進捗ファイルを更新
6. 説明的なメッセージで動作するコードをコミット

重要な知見: 「一度に 1 つの機能」

Anthropic のリサーチより: エージェントは一度にやりすぎる傾向がある — 本質的にアプリをワンショットで試みる。

解決策: 1 セッションにつき 1 つの機能に集中し、徹底的にテストし、進捗を更新する。

---

基本原則

Claude Code Best Practices より:

1. TodoWrite を広範に使用 - 作業を分解し、進捗を可視化
2. JSON ベースの状態永続化 - .claude/workspaces/{workspace-id}/claude-progress.json と .claude/workspaces/{workspace-id}/feature-list.json を使用
3. 頻繁にチェックポイント - Claude Code は変更前に自動保存
4. 即座に完了マーク - 完了のバッチ処理をしない

なぜ Markdown ではなく JSON か？ 「モデルは Markdown ファイルと比べて JSON ファイルを不適切に変更する可能性が低い。」 - Anthropic

状態管理

詳細な進捗トラッキングの実装については progress-tracking スキルを参照:

• JSON ファイルスキーマ（claude-progress.json、feature-list.json）
• ワークスペース分離（{branch}_{path-hash} 形式）
• PreCompact フック統合とコンパクション回復
• セッション追跡と再開コンテキスト

クイックリファレンス:

.claude/workspaces/{workspace-id}/
├── claude-progress.json  # 進捗ログ、再開コンテキスト
└── feature-list.json     # 機能/タスクステータス追跡

TodoWrite 統合

TodoWrite を JSON ファイルと併用:

システム	目的	スコープ
TodoWrite	リアルタイム可視化	現在のセッション
JSON ファイル	永続化	セッション横断

フロー:

1. 作業開始前に todo を in_progress にマーク
2. 完了直後に completed にマーク
3. 一度に in_progress は 1 つだけ
4. セッション再開時に JSON ファイルから同期

大規模マイグレーションパターン

多くのファイルに影響するマイグレーション:

フェーズ 1: 発見

重要: バルクファイル発見は code-explorer エージェントに委任する。

オーケストレーターのコンテキストで find/grep を直接実行しない。代わりに:

**code-explorer に委任:**
- タスク: `*.tsx` に一致し `OldPattern` パターンを含む全ファイルを検索
- 返却: ファイル一覧、一致件数、推定スコープ
- 目的: マイグレーション計画のための発見

これによりオーケストレーターのコンテキストを保持し、委任ファーストの原則に従う。 エージェントの発見結果を計画ファイルに記録する。

フェーズ 2: バッチ処理

管理可能なバッチでファイルを処理:

バッチ 1: src/components/*.tsx（15 ファイル）
バッチ 2: src/pages/*.tsx（8 ファイル）
バッチ 3: src/utils/*.ts（4 ファイル）

各バッチを個別の todo として追跡。

フェーズ 3: 検証

各バッチ後:

• テストを実行
• リグレッションを確認
• 進捗を更新

バックグラウンドタスク

ノンブロッキング操作:

# バックグラウンドで開発サーバーを実行
npm run dev &

# 作業を続けながらテストを実行
npm test &

# Ctrl+B で実行中タスクをバックグラウンドに

注:

• バックグラウンドタスクは環境がサポートしている場合のみ使用。
• 制約のある環境では、明示的なタイムアウト付きフォアグラウンド実行を推奨（例: timeout 300 npm test）。

サブエージェント再開パターン

ロングランニングタスクでサブエージェントを効率的に活用するパターン。

再開が重要な理由

Claude Code Subagents Documentation より:

「再開されたサブエージェントは、以前の全ツール呼び出し、結果、推論を含む完全な会話履歴を保持する。」

サブエージェント再開の利点:

• コンテキストをゼロから再構築する必要がない
• エージェントが停止したところから正確に継続
• 探索結果の喪失を防止
• 権限エラーや中断からのリカバリ

基本的な再開パターン

初回呼び出し:
"code-explorer を使用してモジュール A を分析"
[エージェント完了、エージェント ID: agent-abc123 を返す]

継続（同じエージェントを再開）:
"agent-abc123 を再開し、モジュール B も分析"
[以前の会話の完全なコンテキストで再開]

オーケストレーター再開プロトコル

ロングタスクのオーケストレーション時、再開の可能性のためにエージェント ID を追跡:

{
  "activeAgents": {
    "exploration": "agent-abc123",
    "implementation": "agent-def456"
  },
  "completedAgents": [
    {"id": "agent-xyz789", "task": "architecture review", "summary": "..."}
  ]
}

再開の判断ツリー:

エージェントは正常に完了したか？
├─ はい: サマリーを保存、エージェント ID をクリア
└─ いいえ（中断/失敗）:
    ├─ 権限エラー → フォアグラウンドで再開
    ├─ コンテキスト枯渇 → サマリー付きで新しいエージェントを開始
    └─ ネットワークエラー → 短い待機後に再開

バックグラウンドサブエージェントのリカバリ

バックグラウンドサブエージェントが権限不足で失敗した場合:

1. エージェントは失敗したツール呼び出しをスキップして続行
2. 完了後、フォアグラウンドで再開してリトライ可能
3. 再開時にインタラクティブな権限プロンプトが利用可能

リカバリの例:

# バックグラウンドエージェントが権限エラーに遭遇
エージェント agent-abc123 が部分的な結果で完了。
スキップされた操作: /etc/config への書き込み（権限拒否）

# フォアグラウンドで再開して完了
agent-abc123 をフォアグラウンドで再開し、失敗した操作をリトライ。
[インタラクティブ権限プロンプトが表示]

バックグラウンドサブエージェントの制限

機能	フォアグラウンド	バックグラウンド
MCP ツール	利用可能	利用不可
権限プロンプト	インタラクティブ	自動拒否
AskUserQuestion	利用可能	サイレント失敗
再開	-	フォアグラウンドで再開可能

オーケストレーターへの重要な影響:

1. MCP ツール利用不可: バックグラウンドサブエージェントは MCP 提供ツール（例: mcp__github__*、mcp__memory__*）を使用できない。タスクが MCP ツールを必要とする場合、フォアグラウンドで実行するか作業を分割する。

2. 権限の自動拒否: バックグラウンドエージェントが権限を必要とする操作（例: 許可パス外の新ファイルへの書き込み）を試みると、操作はサイレントにスキップされる。エージェントは続行するが不完全な結果になる可能性がある。

3. AskUserQuestion のサイレント失敗: バックグラウンドエージェントは明確化の質問ができない。タスク途中でユーザー入力が必要な場合:

   • ステップをスキップして結果に記録
   • デフォルトの仮定をする（潜在的に不正確）
   • サブタスクを失敗させる

4. リカバリ戦略: バックグラウンドエージェントの結果が不完全な場合:

   エージェント結果で以下を確認:
   - 「スキップされた操作」や「部分的な結果」の表示
   - 期待される出力の欠落
   - 予想より低い確信度スコア
   
   不完全な場合:
   → エージェントをフォアグラウンドで再開してインタラクティブに完了
   → または具体的な指示で新しいフォアグラウンドエージェントを開始
   

再開を使用すべき場面

シナリオ	推奨アクション
探索の拡大	同じ code-explorer を再開
追加のレビューチェック	同じ security-auditor を再開
権限エラーからのリカバリ	フォアグラウンドで再開
エージェントがコンテキスト上限に達した	サマリー付きで新しいエージェントを開始
完全に新しい視点が必要	新しいエージェントを起動

再開の判断ツリー

既存のエージェントを再開するか新規に開始するかを決定するための判断ツリー:

エージェントタスクは完了したか？
├─ いいえ（中断/失敗）:
│   ├─ 権限エラー？
│   │   └─ はい → フォアグラウンドで再開（インタラクティブプロンプトが利用可能）
│   ├─ ネットワーク/一時的エラー？
│   │   └─ はい → 短い待機後に再開
│   ├─ コンテキスト枯渇？
│   │   └─ はい → 以前の作業のサマリーで新しいエージェントを開始
│   └─ ユーザーキャンセル？
│       └─ はい → 作業を続けるべきなら再開、そうでなければ新しいエージェント
│
└─ はい（正常に完了）:
    ├─ 同じトピックのフォローアップが必要？
    │   └─ はい → 再開（コンテキストを保持）
    ├─ 別のトピックの作業が必要？
    │   └─ はい → 新しいエージェントを開始
    └─ 結果が不十分？
        ├─ 深さが不足？
        │   └─ 「X についてより深く調査」で再開
        └─ 方向が間違い？
            └─ 修正されたプロンプトで新しいエージェントを開始

エージェント ID 追跡のベストプラクティス

効率的な再開のためにオーケストレーション状態でエージェント ID を追跡:

{
  "agentTracking": {
    "active": {
      "exploration": {
        "id": "agent-abc123",
        "task": "analyzing auth module",
        "startedAt": "2025-01-16T10:00:00Z"
      }
    },
    "completed": [
      {
        "id": "agent-xyz789",
        "task": "architecture review",
        "completedAt": "2025-01-16T09:30:00Z",
        "summary": "Recommended service layer pattern",
        "resumable": true
      }
    ],
    "failed": [
      {
        "id": "agent-def456",
        "task": "security audit",
        "failedAt": "2025-01-16T09:45:00Z",
        "reason": "permission_denied",
        "recoveryAction": "resume_foreground"
      }
    ]
  }
}

オーケストレータープロトコル:

1. エージェント起動時: エージェント ID とタスク説明を記録
2. エージェント完了時: サマリー付きで完了リストに移動
3. エージェント失敗時: 失敗理由とリカバリアクションを記録
4. 類似の新しい作業の開始前: 再開可能なエージェントが存在するか確認

再開時のコンテキスト保持

再開時、エージェントは以下を保持:

• 完全な会話履歴
• 以前の全ツール呼び出しと結果
• 推論と行った決定
• 読んだファイルと実施した分析

これにより再開は以下に最適:

• 反復的な探索（A を分析、次に B、次に C）
• 多フェーズレビュー（セキュリティ、次にパフォーマンス、次にアクセシビリティ）
• 作業を失わないエラーリカバリ

トランスクリプトの場所

サブエージェントのトランスクリプトは以下に保存:

~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

デフォルトで 30 日後に自動クリーンアップ（cleanupPeriodDays 設定で変更可能）。

マルチセッション作業

セッション終了時:

1. 現在の位置で進捗ファイルを更新
2. 説明的なメッセージで WIP 変更をコミット
3. resumptionContext.nextAction が具体的であることを確認

次のセッション開始時:

1. ワークスペース進捗ファイルを読む
2. 最初の pending または in_progress 機能を見つける
3. 記録された位置から続行

詳細なセッションプロトコルと例は progress-tracking スキルを参照。

避けるべきアンチパターン

アンチパターン	悪い理由	代わりに
完了のバッチ処理	失敗時に進捗を失う	即座に完了マーク
複数の in_progress	混乱、焦点を失う	一度に 1 つ
状態ファイルなし	再開できない	常に状態を記録
進捗ログなし	何が起きたか追跡できない	各アクションをログ
テストをスキップ	リグレッションが複合化	各バッチ後にテスト

Rules (L1 - Hard)

セッション継続性とデータ整合性に不可欠。

• ALWAYS: 進捗ファイルに workspaceId を含める（ワークスペースの競合防止）
• NEVER: 現在のワークスペース外の進捗ファイルに書き込まない
• ALWAYS: コンパクション後または新しいセッションでは最初にワークスペース進捗ファイルを読む
• NEVER: 複数の todo を in_progress にしない（焦点と明確さ）
• NEVER: 複数の機能を同時に試みない（不完全な実装の原因）
• ALWAYS: 1 セッション 1 機能に集中: 実装 → テスト → 進捗更新 → コミット → 次へ
• MUST: 現在の機能を完了してから次を開始（コンテキスト爆発の防止）

Defaults (L2 - Soft)

効果的なロングランニングタスクに重要。適切な理由がある場合はオーバーライド可。

• 3 ステップを超えるタスクにはワークスペース進捗ファイルを作成
• ワークスペース分離パスを使用: .claude/workspaces/{workspace-id}/
• 各重要なアクション後に進捗ファイルを更新
• todo は即座に完了マーク（バッチ処理しない）
• 再開コンテキストを JSON で記録（position、nextAction、keyFiles）
• バッチ変更後にテスト
• 状態永続化には JSON を使用（プレーンテキストではなく）

Guidelines (L3)

複雑なタスク管理のための推奨事項。

• consider: マルチセッション作業にはイニシャライザー + コーディングパターンの使用を検討
• consider: ノンブロッキング操作にはバックグラウンドサブエージェントを検討