analysis_claude_code/docs/v2-構造化プランニング.md

v2: Todoによる構造化プランニング

約300行。+1ツール。明示的なタスク追跡。

v1は機能する。しかし複雑なタスクでは、モデルが見失うことがある。

「認証をリファクタリングし、テストを追加し、ドキュメントを更新して」と頼むと何が起こるか見てみよう。明示的な計画なしでは、タスク間を飛び回り、ステップを忘れ、集中を失う。

v2は1つのものを追加：Todoツール。エージェントの動作を根本的に変える約100行の新コード。

問題

v1では、計画はモデルの「頭の中」にのみ存在：

v1: "Aをして、次にB、次にC"  （見えない）
    10ツール後: "あれ、何をしていたっけ？"

Todoツールはそれを明示化：

v2:
  [ ] 認証モジュールをリファクタリング
  [>] ユニットテストを追加         <- 現在ここ
  [ ] ドキュメントを更新

これであなたもモデルも計画が見える。

TodoManager

制約のあるリスト：

class TodoManager:
    def __init__(self):
        self.items = []  # 最大20

    def update(self, items):
        # バリデーション:
        # - 各項目に必要: content, status, activeForm
        # - Status: pending | in_progress | completed
        # - in_progressは1つだけ
        # - 重複なし、空なし

制約が重要：

ルール	理由
最大20項目	無限リストを防ぐ
in_progressは1つ	集中を強制
必須フィールド	構造化出力

これらは任意ではない—ガードレールだ。

ツール

{
    "name": "TodoWrite",
    "input_schema": {
        "items": [{
            "content": "タスクの説明",
            "status": "pending | in_progress | completed",
            "activeForm": "現在形: 'ファイルを読んでいます'"
        }]
    }
}

activeFormは今何が起こっているかを示す：

[>] 認証コードを読んでいます...  <- activeForm
[ ] ユニットテストを追加

システムリマインダー

Todo使用を促すソフト制約：

INITIAL_REMINDER = "<reminder>マルチステップタスクにはTodoWriteを使用してください。</reminder>"
NAG_REMINDER = "<reminder>10ターン以上todoなし。更新してください。</reminder>"

コマンドではなくコンテキストとして注入：

# INITIAL_REMINDER: 会話開始時（mainで）
if first_message:
    inject_reminder(INITIAL_REMINDER)

# NAG_REMINDER: agent_loop内で、タスク実行中に
if rounds_without_todo > 10:
    inject_reminder(NAG_REMINDER)

重要な洞察：NAG_REMINDERはエージェントループ内で注入されるので、モデルは長時間実行タスク中にそれを見る、タスク間だけではなく。

フィードバックループ

モデルがTodoWriteを呼び出すとき：

入力:
  [x] 認証をリファクタリング (完了)
  [>] テストを追加 (進行中)
  [ ] ドキュメントを更新 (保留)

返却:
  "[x] 認証をリファクタリング
   [>] テストを追加
   [ ] ドキュメントを更新
   (1/3 完了)"

モデルは自分の計画を見る。それを更新する。コンテキストを持って続行する。

Todoが役立つとき

すべてのタスクに必要なわけではない：

適切な場面	理由
マルチステップ作業	追跡すべき5つ以上のステップ
長い会話	20以上のツール呼び出し
複雑なリファクタリング	複数のファイル
教育	「思考」が可視

経験則：チェックリストを書くなら、todoを使う。

統合

v2はv1を変更せずに追加：

# v1のツール
tools = [bash, read_file, write_file, edit_file]

# v2が追加
tools.append(TodoWrite)
todo_manager = TodoManager()

# v2は使用を追跡
if rounds_without_todo > 10:
    inject_reminder()

約100行の新コード。同じエージェントループ。

より深い洞察

構造は制約し、可能にする。

Todo制約（最大項目数、1つのin_progress）が可能にする（可視の計画、追跡された進捗）。

エージェント設計のパターン：

• max_tokensは制約 → 管理可能な応答を可能に
• ツールスキーマは制約 → 構造化された呼び出しを可能に
• Todoは制約 → 複雑なタスク完了を可能に

良い制約は制限ではない。足場だ。

---

明示的な計画がエージェントを信頼性あるものにする。

← v1 | READMEに戻る | v3 →