"TODOリストのサイクル"を常に回しながらAIを働かせたら、コードレビューの認知負荷が激減した話
もはや何番煎じか分からない「AIにTODOリストを書かせる」という発想が、
意外にも、あとから 「人間が」『AIは"なぜ"そのコードを書いたのか？』を追跡するのに役立つことに気付いたよ、というお話です。
※ いま流行りの仕様駆動開発のお話ではありません。
何を解決する記事なのか
皆さん、コーディングAgent（Claude Code, Codex, GitHub Copilot...）を使っていますか？
きっと使っていますよね。
確か、つい半年か1年前くらいまでは、AIには小さな関数や機能単位でコードを書かせていたような気がするのですが、
今や、タスクを与えれば自律的にプランニングから実装>テスト>デプロイまで一貫してなんでもやってくれるようになりました。
私も、Codexのおかげでアプリ開発が5倍速になりました。
こうした自動化されたコーディングAgentは便利な一方で、
一度に大量のコード変更・ファイル追加が行われてしまうので、
- コミットメッセージに何を書けばいいのか（or 長くなってしまう）問題...
-
変更差分が多すぎてコードレビューで全容を把握するのが困難...
- というか、実質レビューを諦めて全部Approveしてしまう...
-
Pull Requestの文章も長くなっていく...
- そしてAIに書かせて、精査せず送信...
という課題を感じている人もいるんじゃないかと思います。私もその一人でした。
そんなある日、タイトルにもあるように
- コーディングAgentに「TODOチェックリストを常に書きながら働け」と命令する
- 「その差分をリモートにpushして、定期的にリセットする」サイクルを回す
ということをしていたところ、「あれ？この方法なら問題解決じゃないか？」と気づいてしまいました。
この方法により、
- コミットメッセージは
TODO.mdの差分を読んで、そのタイトルだけ書く - コードレビューは
TODO.mdの差分をまず読んで、方針が怪しいところはコード詳細を読む - PR/MRのアブストは
TODO.mdの差分だけでほぼ網羅
でOKになったのです。
今日はそのことについて書きます。
※ コードレビューの前に別途CIでpre-commitやtestの仕組みなどを活用する前提
やりかた（どんなコーディングAgentでもOK）
Step1. AGENTS.md（CLAUDE.md）に下記を記載するだけ
コーディングAgentごとに、ルールを記載するファイルがあると思いますが、そこに下記の内容を追記します。
- チャットの初回開始時には`README.md`を確認してプロジェクトの概要を理解してください。
- タスク実施項目は`TODO.md`にチェックボックス形式で記載してから遂行してください。実施済のタスクはチェックを付けてください。
- TODOリストの書き方
`````markdown
- 機能追加: ...のために...導入
- [x] ...を追加
- [ ] ...を適用
- 改善: ...の問題を回避
- [x] ...を修正
- [ ] ...を変更
`````
- コードの修正で不要になった過去のコードや機能は適切に削除してください。
- タスクが完了したら、下記を実施してください。
- `README.md`を確認し、古い仕様の記載を削除して現在の状態に常に同期するように修正してください。
- `TODO.md`を確認し、より以前のTODOの内容があとから変更されてすでに古い情報になっている場合に、記載の統合や補足情報の追記を行うなどして最終的な成果物と同期させて下さい。
Step2. コミットの差分に変更点がチェックリストで表示される
あとはコーディングAIに、性能の限り自由に働いてもらってください！
そしてしばらくしてタスク完了の報告を受けたら、変更をステージングするなりコミットすると思います。そのときTODO.mdファイルが生成・追記されていることに気付くはずです。
VS Codeなどのローカルのエディタ上や、GitHubのようなリモートのWebUIでTODO.mdの差分を確認してみると、
下の画像のようにコーディングAgentの働いた内容（= 今回のcommitの変更点の要約）になっています！
（テキストでも紹介）
- 実験: Responses API 互換レイヤの導入
- [x] `main.py` に Responses API を優先使用し、失敗時に `chat.completions` へフォールバックする互換ラッパを実装
- [x] 画像入力（data URL）に対応するための変換ヘルパ（`_to_responses_input`）を追加
- [x] Responses API のレスポンスから本文を抽出するユーティリティ（`_extract_text_from_responses`）を追加
- [x] スライド画像説明関数を Responses 優先で動作するように置き換え（デバッグ出力を追加）
- [x] README に互換挙動（Responses優先/フォールバック）を追記して仕様を同期
+ - 改善: ログ/Warning/トークン集計
+ - [x] `[INFO] 使用: ...` のログを初回のみ出力するよう抑制
+ - [x] `UserWarning: style lookup by style_id is deprecated` を解消（スタイル名で取得）
+ - [x] Responses API の `usage` 形状（`input_tokens`/`output_tokens` 等）を集計器に対応
+
+ - 調査/仕様: Reasoningトークンと合算値
+ - [x] Web調査: Reasoningトークンも課金対象であることを確認（Responses/Chatで`total_tokens`の定義が揺れる）
+ - [x] 集計仕様: `total` は `prompt + completion + reasoning`（請求合算）に統一
+ - [x] 表示順: `reasoning` を `total` の前に表示し、合算の含意を明確化
+ - [x] README: `total` が reasoning を含む旨を明記
+
+ - 機能: API切替フラグ（Responses/Completions）
+ - [x] CLIオプション `--completions` を追加（既定はResponses）
+ - [x] スライド要約/Markdown整形でフラグを尊重してAPIを選択
+ - [x] ログ表示（どのAPIを使用したか）を既存の仕組みで維持
+ - [x] READMEにオプションと既定の動作を追記
+
+ - 機能: モデル使い分け + Azureデプロイマップ
+ - [x] `AZURE_OPENAI_DEPLOYMENT` にJSONマップ（モデル→デプロイ）を許容（`"*"`フォールバック対応）
+ - [x] モデル解決関数を実装（OpenAI直=素通し/Azure=デプロイ名へ解決）
+ - [x] `--md-model` を追加（MarkItDown専用）、未指定時は `--llm-model` を使用
+ - [x] main内で MarkItDown用モデルとその他用モデルを分離して適用
+ - [x] README/.env.example を現仕様に同期
このように、実施内容が「Gitにおける差分」になっているのがポイントです。
なぜなら、1000行のコードと1100行のコードの差分を読むのは大変ですけれども、その内容がたった5行程度の日本語に要約・リスト化されたものを読むのは簡単だからです。
あとはこの差分だけ読んで、コミットメッセージを考えるだけでOKです。
そしてAIによって書かれた膨大な量のコードは、ほぼ読まずにまずはcommitしてしまいましょう。
そうでもしないと、これからの時代は時間がいくらあっても足りないですよね。
（動作確認や危険な実装が無いかの確認は、そのあとpushする前にAgentにやってもらいます。この記事ではそれには触れません。ここで実施するのはあくまで変更点記録のためのcommitです。）
Step3. 本番ブランチへマージ、その後TODO.mdをリセット
その後、TODO.mdのお掃除も大事なポイントです。
たとえばGitHub Flowのブランチ戦略を採用している場合には、下記の流れでTODO.mdの再利用サイクルを回していきます。
- devブランチでcommitを重ねていき、
TODO.mdにもチェック済リストが溜まっていく - テスト、動作確認
- mainブランチにPull Request発行
- すると、
TODO.mdの変更点がまさにレビュー依頼文そのものになる
- すると、
- 無事にmainブランチにマージされた後、別の開発ブランチを切ったタイミングで過去の
TODO.mdはリセット、 またゼロからTODO.mdを書かせ始める- 過去のTODOリストをコーディングAgentに読みこませたところで、基本LLMコンテキストの浪費にしかならないので、手動で消してあげましょう
- 上のプロンプトでは、常に
README.mdに最新の仕様が書かれるようになっているので、読ませるならこちらにします。
以上です！
ね、簡単でしょ？
まとめ
冒頭でも書いたように、
「AIにTODOリスト書かせるなんて何番煎じですか？」って話ではあるのですが、
この話の肝は
- TODOリストを（ローカルで使うだけではなく）リモートまでpushしてしまうことで、さらっと変更点をおさらいできる履歴ファイルとして使ってしまう
ということで、
Agentのタスク遂行能力を高めるためのレールとしてではなく、
人間の認知負荷を減らすためのTipsとしてTODOリストの生成が便利だと気づいた
という点が、個人的に Good & New な気づきでした。
Discussion