Claude CodeのTodoWrite駆動開発：AIペアプログラミングにおける最適なタスク粒度とは

概要

Claude CodeのTodoWrite機能は、AIがタスクリストを作成・管理するための仕組みです。2025年8月から2026年4月にかけて、複数のプロジェクトでTodoWriteを使った開発を続けてきました。

その中で見えてきたのは、タスク粒度が3-7アイテムのとき最も効率が良いということです。少なすぎると方向を見失い、多すぎるとコンテキストウィンドウを圧迫します。

本記事では、プロジェクト別のTodoWrite使用パターン、最適なタスク粒度、セッション分割の判断基準、そしてRead連打問題について記録します。

TodoWriteとは

Claude Codeには、タスクリストを作成・更新するTodoWrite機能があります。AIが「今やるべきこと」をリスト化し、1つずつ完了にしていきます。

1
☐ config.py にモジュールCのパラメータを追加
2
☐ moduleC.py を作成
3
☐ moduleManager.py にモジュールCのimportを追加
4
☐ engine.py にモジュールCの呼び出しを追加
5
☑ ユニットテストを作成・実行  ← 完了

人間のタスク管理ツール（Jira、GitHub Issues）とは異なり、TodoWriteは1セッション内でのAIの作業管理に特化しています。

プロジェクト別の使用パターン

データ分析プロジェクト：3-7アイテム

分析モジュールの量産時は、1モジュール = 1タスクとして3-7アイテムを管理していました。

1
☐ モジュールC 作成
2
☐ モジュールD 作成
3
☐ モジュールE 作成

このプロジェクトでは「1つの分析モジュールを追加する」という作業が明確に定義されており、タスクの粒度が自然に揃いました。3-7アイテムという範囲は、1セッションで完了可能な量として最適です。

icoi-v4プロジェクト：最大50アイテム

ECサイト構築時は、商品のMDXファイル生成で最大50アイテムに達する場面がありました。

1
☐ エチオピア イルガチェフェ MDX生成
2
☐ コロンビア スプレモ MDX生成
3
☐ ブラジル サントス MDX生成
4
... （以下27件）

50アイテムのTodoWriteは非効率でした。理由は以下の通りです。

• タスクリストの表示だけでコンテキストを消費する
• AIが全タスクの状態を把握するのに時間がかかる
• 後半のタスクで品質が低下する

最終的に、8-10件ずつのバッチ処理に切り替えました。

claudelogプロジェクト：Spec-Driven Development

Spec-Driven Development（仕様駆動開発）では、要件定義→設計→テスト設計→タスク分割→実装の全工程でTodoWriteを使いました。

1
☐ 要件定義書の作成
2
☐ 技術設計書の作成
3
☐ テスト設計書の作成
4
☐ タスク分割
5
☐ 実装: CLI引数パーサー
6
☐ 実装: ログ読み込み
7
☐ 実装: Ollama要約
8
☐ テスト実行

工程が異なるタスクを混在させると、粒度が不揃いになります。「要件定義書の作成」と「CLI引数パーサーの実装」では作業量が全く異なります。対策として、工程ごとにTodoWriteをリセットする運用にしました。

最適なタスク粒度

3-7アイテムが最適な理由

タスク1つの理想的なサイズ

• 所要時間: 10-30分で完了する単位
• 成果物: 1つのファイル変更、または1つの機能追加
• 検証可能: テスト実行やビルド確認で完了を判定できる

1
# 良いタスク粒度
2
☐ moduleC.py の作成とユニットテスト
3

4
# 粗すぎるタスク粒度
5
☐ 分析モジュール全体の実装
6

7
# 細かすぎるタスク粒度
8
☐ moduleC.py のimport文を追加
9
☐ moduleC.py のcalculate関数を追加
10
☐ moduleC.py のgenerate_result関数を追加

セッション分割の判断基準

「続けてください」のパターン

長時間の作業では、以下のようなやり取りが頻繁に発生しました。

1
私: 「続けて作成してください」
2
私: 「続きをお願いします」
3
私: 「作業続行してください」

これらの指示が増えてきたら、セッション分割を検討すべきサインです。

セッション分割の3つの判断基準

基準1: タスクの残量

残りタスクが5個以上ある場合、新しいセッションで作業した方が品質が高くなります。

基準2: AIの応答品質

以下の兆候が見えたら、コンテキストウィンドウが逼迫しています。

• 同じファイルを何度もReadする（Read連打問題）
• 以前のセッションで決めたルールを忘れる
• 「すでに完了したタスク」を再度実行しようとする

基準3: 作業の性質が変わるとき

「コード実装」から「テスト作成」に移る、「バックエンド」から「フロントエンド」に移るなど、作業の性質が変わるタイミングはセッション分割の好機です。

Read連打問題

何が起きるか

セッションが長くなると、Claude Codeが同一ファイルを5-8回繰り返しReadする現象が発生します。

1
Tool: Read file "src/config/config.py"
2
... （作業）
3
Tool: Read file "src/config/config.py"   ← 再読み込み
4
... （作業）
5
Tool: Read file "src/config/config.py"   ← また再読み込み

なぜ起きるか

コンテキストウィンドウが長くなると、古い情報がウィンドウの外に押し出されます。AIは「ファイルの内容を覚えていない」ため、再度読み込みます。しかし、読み込んだ内容がまたすぐにウィンドウの外に出るので、同じファイルを何度も読む悪循環に陥ります。

対策

対策1: セッションを分割する

最も効果的な対策です。新しいセッションはコンテキストが空なので、Read連打は発生しません。

対策2: CLAUDE.mdに要約を書く

頻繁に参照するファイルの要約をCLAUDE.mdに書いておくと、毎回Readする必要がなくなります。

1
## config.py の構造
2
- LINE 1-50: インポートと定数定義
3
- LINE 51-100: モジュールA設定
4
- LINE 101-150: モジュールB設定
5
- LINE 151-200: モジュールC設定

対策3: 1タスク完了ごとに状態を報告させる

1
各タスク完了時に、以下を報告してください。
2
- 変更したファイル一覧
3
- 次のタスクで必要なファイル一覧
4
- 現在のTodoWrite状態

これにより、AIが「次に何をすべきか」を自分で整理し、不要なReadを減らせます。

TodoWrite駆動開発のテンプレート

これまでの経験から、以下のテンプレートに落ち着きました。

セッション開始時の指示

1
以下のタスクをTodoWriteで管理しながら実装してください。
2

3
1. [タスクA]
4
2. [タスクB]
5
3. [タスクC]
6

7
各タスク完了時にテストを実行し、問題なければ次に進んでください。
8
1セッションで完了しない場合は、残りタスクを報告して終了してください。

セッション引き継ぎ時の指示

1
前回のセッションで以下が完了しています。
2
- [完了タスクA]
3
- [完了タスクB]
4

5
今回は以下の残りタスクを実施してください。
6
- [残りタスクC]
7
- [残りタスクD]
8

9
前回作成したファイル: src/xxx.py, src/yyy.py

まとめ

TodoWriteは「AIの短期記憶を補助するツール」です。人間のタスク管理ツールとは目的が異なります。AIの特性（コンテキストウィンドウの制約、セッション間の記憶喪失）を理解した上で使い分けることが重要です。