Claude Code の TodoList を使っていて、「リストは出してくれるのに、なぜか作業品質が上がらない」と感じたことはないでしょうか。私も最初は同じで、最初のうちは TodoList に項目を並べることそのものが目的化してしまい、肝心の作業が雑になるという本末転倒な状況に陥っていました。
原因を突き詰めて気づいたのは、TodoList は「書くこと」よりも「どの粒度で書くか」「いつ更新するか」「検証項目をどう含めるか」のほうが遥かに成果に直結するという事実です。ここでは私自身が4サイト運営の自動化ワークフローで試行錯誤してきた中で、実際に効いた使い方を3つのパターンに絞ってご紹介します。
なぜ TodoList は「書けば安心」ではないのか
Claude Code の TodoList が便利なのは確かです。複雑なタスクを分解してくれ、進捗が視覚的にわかる。ユーザーとしてもエージェントとしても安心感があります。ただし、ここに落とし穴があります。
TodoList は「計画」を可視化するツールであって、「実行品質」を担保するツールではありません。粗い粒度で項目を並べるだけだと、各項目の中身が曖昧なまま作業が進み、結局どのステップでも手を抜けてしまうのです。たとえば次のような TodoList を書いたとします。
- [ ] コンポーネントをリファクタリングする
- [ ] テストを書く
- [ ] ドキュメントを更新する
これは一見整理されていますが、実際に作業を始めると「どのファイルを」「どう」リファクタするかはエージェント任せになります。結果として、全体最適ではなく目についたファイルだけ直して完了にしてしまう、といった事態が起こります。
パターン1: タスクは「検証可能な単位」で切る
私が最も効果を感じたのは、TodoList の1項目を「完了を客観的に検証できる単位」で切ることです。つまり、項目を読むだけで「何をやったら完了なのか」が一意に決まる状態にします。
悪い例と良い例を比較します。
❌ 悪い例（検証不能）
- [ ] API レスポンスのキャッシュを改善する
- [ ] エラーハンドリングを強化する
✅ 良い例（検証可能）
- [ ] src/lib/api-cache.ts に 5分 TTL の Map ベースキャッシュを実装する
- [ ] src/app/api/checkout/route.ts の try/catch で Stripe の StripeCardError を個別にハンドルし、ユーザー向けメッセージを返す
- [ ] 上記2つの変更に対する Vitest テストを tests/api-cache.test.ts に追加する（キャッシュヒット・ミス・期限切れの3ケース）
良い例では、各項目の完了条件が明確です。キャッシュが Map ベースか、TTL が 5分か、対象関数に StripeCardError の分岐があるか——この4つを見れば完了判定できます。エージェントが作業した後、あなた自身も git diff を見ながら同じ粒度で検証できるわけです。
私の経験では、項目あたりの記述は「動詞 + 対象ファイル + 完了条件」の3要素で書くと、おおよそ検証可能な粒度に収まります。
パターン2: 必ず最後に「検証ステップ」を入れる
次に重要なのが、TodoList の最後に明示的な「検証ステップ」を入れることです。これを省くと、エージェントは「全項目にチェックが付いた = 完成」と判断して作業を終えてしまい、実際に動かない状態でも気づけません。
私は次のようなテンプレートで常に最後にチェックステップを追加しています。
- [ ] （作業項目1）
- [ ] （作業項目2）
- [ ] （作業項目3）
- [ ] 【検証】変更した全ファイルで tsc --noEmit がエラーなく通ることを確認する
- [ ] 【検証】vitest run で既存テストが緑であることを確認する
- [ ] 【検証】手動で / /en/articles/... の3ページを開いて表示崩れがないことを目視確認する
検証ステップを TodoList に含めるだけで、最終成果物の品質が目に見えて上がります。理由は単純で、エージェントは「検証項目も完了させないと終わらない」と理解するため、作業の最後に手抜きをしなくなるからです。
ちなみに、より高い信頼性が必要な作業では検証ステップを 別のサブエージェントに任せる のも有効です。Claude Code の Task ツールで検証専用エージェントを呼び出すと、本体作業をしたエージェントのバイアスを排除したチェックができます。
パターン3: 更新タイミングを「1項目ずつ即時」に固定する
3つ目のパターンは、TodoList の更新タイミングに関するものです。Claude Code のドキュメントでも推奨されていますが、実運用で徹底するとしないで差が出ます。
ルールはシンプルで、「1項目を開始する直前に in_progress に」「1項目を完了した直後に completed に」、この2つを必ず守ります。まとめて更新しないことがポイントです。
なぜまとめて更新してはいけないのか
ある時、私は TodoList を「5項目まとめて作業してから、最後に全部 completed にする」という使い方をしていました。これは一見効率的に見えますが、実際には次のような問題が起こります。
- 途中でエラーが起きた時、どこまで実際に完了しているのか追跡不能になる
- セッションが切れて再開した時、進捗の真の姿がわからない
- 検証の対象範囲が広すぎて、問題の切り分けに時間がかかる
1項目ずつ即時更新に変えてから、途中中断からの復帰が楽になりました。Claude Code は前回のセッションの TodoList を認識できるので、正しい状態で保存されていれば続きから自然に再開できます。
実装例: TodoWrite を組み込んだワークフロー
以下は、私が記事執筆の自動化で実際に使っているプロンプトの骨子です。Claude Code の TodoWrite ツールを使う場合の典型的な形として参考にしてください。
# タスク: 記事を1本作成してpushする
まず、以下の TodoList を TodoWrite で登録してから作業を開始してください。
1. [pending] GSCデータから今日のテーマを選定し、重複スラッグがないことを確認する
2. [pending] 日本語版MDXを content/articles/ja/claude-code/ に作成する（3,000文字以上、敬体統一）
3. [pending] 英語版MDXを content/articles/en/claude-code/ に作成する（1,500ワード以上）
4. [pending] 【検証】find content/articles/ja -name "*.mdx" | wc -l と英語版の件数が一致することを確認する
5. [pending] 【検証】pushするMDXに存在しない内部リンクが含まれていないことを grep で確認する
6. [pending] git add → commit → push を実行する
7. [pending] _updated_article_log/ にログを記録する
各項目は「開始時に in_progress、完了時に completed」で1つずつ確実に更新してください。
検証ステップで問題が見つかった場合は、新しい pending 項目を追加してから修正に入ってください。このプロンプトの要点は、検証ステップを明示的に入れていること、そして「問題発見時の分岐」も TodoList で管理することを指示している点です。問題が出たら新しい pending を追加してから作業するルールにすると、結果的に対応漏れが減ります。
使わないほうが良い場面もある
最後に、TodoList が 向かないケース にも触れておきます。万能ツールではありません。
- 会話型の質問応答: 「この関数の役割は何ですか」「エラーの原因は何ですか」のような質問に TodoList を作るのは過剰です。読む側の認知負荷が増えるだけで、むしろ回答の本質が埋もれます。
- 1ファイルの小さな修正: タイポ修正や数行の変更では、TodoList を立てる時間のほうがコストです。直接 Edit してしまいましょう。
- 探索フェーズ: 「どう実装するか決める前の調査」段階では、何を調べるかが流動的なので、TodoList に固めてしまうと柔軟性を失います。まず探索して、方針が決まってから TodoList 化するほうが効果的です。
個人的な経験則ですが、「作業時間が15分以上かかる」かつ「複数ファイル・複数検証項目が絡む」タスクの時に TodoList を使うのが費用対効果のスイートスポットだと感じています。
さらに深めたい方へ
AIエージェントを前提としたワークフロー設計の考え方が整理されていて、TodoList のような具体ツールの活用にも応用が効きます。
次の一歩
まずは今日の作業で、15分以上かかりそうなタスクを1つだけ TodoList 化してみてください。その際、最後に必ず1つ以上の「検証」項目を入れるルールだけ守ってみましょう。たったこれだけで、作業の最終品質が変わることを実感できるはずです。慣れてきたら、検証ステップを別サブエージェントに任せる発展形に進むと、さらに安定した自動化が実現できます。
実例: 2時間のリファクタに TodoList を当ててみた
パターンを具体化するために、先週実際に走らせたセッションを簡略化してご紹介します。Next.js のルート1つに集約されていた決済フローを、共通ヘルパーに切り出す2時間のリファクタです。
最初に登録した TodoList はこうなっていました。
1. [pending] Stripe セッション生成を src/lib/stripe/checkout.ts に名前付きエクスポートで切り出す
2. [pending] Webhook 署名検証を src/lib/stripe/webhook.ts に切り出す
3. [pending] src/app/api/checkout/route.ts を新ヘルパーを import する形に書き換える
4. [pending] src/app/api/webhook/route.ts を新ヘルパーを import する形に書き換える
5. [pending] tests/stripe/ に両ヘルパーのユニットテストを追加する（最低: 正常系 + 失敗系1つずつ）
6. [pending] 【検証】プロジェクト全体で tsc --noEmit が通る
7. [pending] 【検証】vitest run が緑のまま
8. [pending] 【検証】localhost で決済テストを通して動作確認する
作業が項目3の途中に差し掛かったとき、小さな問題が見つかりました。旧ルートが書き出していたメタデータ形式を、新ヘルパーがまだ保持していなかったのです。そこで、黙って修正に入るのではなく、新しい pending 項目を追加してから修正に取りかかりました。
3.5 [pending] checkout メタデータのログ形式を新ヘルパーでも維持する
「計画外の修正をするときは、必ず先に TodoList に追加してから着手する」というこの小さな規律が、長時間セッションを誠実に保ってくれます。後でコミットを振り返ったとき、すべての変更に追跡可能な由来があるという状態は精神衛生上も価値が大きいと感じます。
考え方の転換: 「リスト」ではなく「契約」として扱う
振り返って一番大きな変化は、TodoList に対する心構えそのものでした。以前は「やることを並べたもの」として書いていましたが、今は「エージェントに渡す契約書」として書くようになりました。受け入れ条件まで含めて渡す、という意識です。
各項目が「ファイル Y で X を完了し、Z で検証できる」という小さな契約として書かれていると、エージェントを行単位で監視する必要がなくなります。少し離れた場所で作業を任せ、戻ってきたときに契約に照らして成果を確認すればよくなるのです。これこそ Claude Code の生産性が本当に活きる瞬間だと私は感じています。
この記事で紹介したパターンは、リストを長くするためのものではありません。各項目を信頼できるものにするための工夫です。その感覚が掴めると、5行の TodoList で2時間のタスクを任せられるようになり、注意力を本当に必要な箇所に集中できるようになります。