2児のパパ系Webエンジニア
の開発日記
A Dad-of-Two Engineer's Development Diary

AIエージェントが古いTODOに寄り道する!閉じた課題のTODOをgit grepとghで洗い出す手順

AIエージェントが古いTODOに寄り道する!閉じた課題のTODOをgit grepとghで洗い出す手順

🙌 結論から

AIエージェントに大きいリポジトリを触らせるなら、先に「もう閉じた課題を指しているTODO」だけでも消しておく価値があります。

Google が11月6日に Developers Blog で出した分析によると、コーディングエージェントはファイルを読む作業の約13%で、TODO(bug/...) のような課題番号つきのコメントに出くわしていました。

そのうち実際に寄り道したのは6%だけですが、その83%は開発者に頼まれていない行動です👀

しかも、寄り道したセッションは手順が70%、トークンが77%、待ち時間が105%増えていたそうです。

正直、この数字を見てドキッとしました・・・。

人間は「いつかやる」で何年もスルーしてきたTODOを、エージェントはちゃんと読んで、律儀に拾いにいっちゃうんですよね(・_・;)

この記事では、閉じた課題のTODOを git grep と gh issue view で洗い出す手順と、PHPStan・ESLint で新しく増やさない設定までをまとめます。

💡 Googleの分析で分かった寄り道の中身

元の記事は Google の Sam Saccone さんと Madhuri Garikapati さんによる「Agent Distraction」です。

社内の数千人のエンジニアが使ったエージェントの実行記録(数億ステップ分)を調べた結果です!

数字を抜き出すと、こんな感じです👇

  • ファイルを読むセッションの約13%(7回に1回くらい)で、課題番号つきの TODO / FIXME に出くわす
  • 出くわしたうちの94%は無視、6%は参照先の課題に手を出す
  • 手を出したうちの83%は、開発者が頼んでいない寄り道
  • 頼まれていない寄り道の41%は、もう閉じた課題を追いかけていた(修正済み・確認済みが32%)
  • 残り57%は開いている課題で、そのうち39%はコードの編集までしていた

一番もったいないのは「もう直った課題」を読みにいって、トークンと時間を使っているパターンです。

開いている課題に勝手に手を出すのも困りますが、こちらはPRのレビューで気づけます!

閉じた課題への寄り道は差分に何も残らないので、レビューでは気づきにくいんですよね(´・ω・`)

Google のチームは、古いTODOを自動で掃除する仕組みを半年回して、数千件の古い参照を消したそうです。

人間のレビューでの承認率は95%以上とのことでした✨

👀 まずはリポジトリのTODOを数える

いきなり消す前に、まずはどれくらいあるのかを数えます💡

Git の管理下にあるファイルだけを見たいので、grep -r ではなく git grep を使います。

node_modules や vendor を勝手に除外してくれるのが楽です🙌

# TODO と FIXME の行数(Laravel ならこのあたり)
git grep -nE 'TODO|FIXME' -- app routes resources tests | wc -l

# そのうち課題番号(#123 の形)が付いているもの
git grep -nE '(TODO|FIXME).*#[0-9]+' -- app routes resources tests

長く続いている Laravel のプロジェクトだと、2本目のコマンドで思ったより出てくるかもしれません。

TODO: #123 ここは仮の実装 のように、課題番号が書いてあるTODOは、課題の状態と突き合わせられるのがポイントです。

番号が無い TODO: あとで直す は機械的に判断できないので、今回はいったん置いておきます( .. )

🔧 閉じた課題のTODOだけを洗い出す

ここが一番やりたかったところです!

GitHub CLI の gh issue view は --json で state・stateReason・closedAt を取れるので、TODOに書いてある番号を1つずつ聞きにいきます。

git grep -hoE '(TODO|FIXME)[^#]*#[0-9]+' -- app routes resources tests \
  | grep -oE '[0-9]+$' \
  | sort -un \
  | while read -r n; do
      gh issue view "$n" --json number,state,stateReason,closedAt \
        --jq 'select(.state == "CLOSED") | "#\(.number) \(.stateReason) \(.closedAt)"' \
        2>/dev/null
    done

出力は #123 COMPLETED 2025-03-10T... のような形になります。

stateReason は「完了(COMPLETED)」か「対応しない(NOT_PLANNED)」です。

COMPLETED のものは「直ったのにコメントだけ残っている」可能性が高いので、最初に見る候補にしています。

ハマりやすいところも書いておきます🤔

  • TODOの番号がPRの番号だと gh issue view はエラーになる。上のコマンドは 2>/dev/null で飛ばしているので、PRも見たいときは gh pr view で同じことをする
  • 別リポジトリの課題(acme/api#45 のような書き方)はこのコマンドでは拾えない。-R acme/api を付けて別に回す
  • 番号が多いと GitHub API の呼び出し回数がかさむので、最初は app/ だけなど範囲を絞って回すのがおすすめ

ちなみに、これを丸ごとAIエージェントに頼むのもありです(^^)

ただその場合は、「消すのは私が確認してから。まずは一覧だけ出して」と最初に書いておくのが大事です。

ここで勝手に消され始めたら、それこそ寄り道ですからね笑

✨ PHPStanとESLintで増やさない

掃除しても、また閉じた課題のTODOが溜まっていったら同じことの繰り返しです。

なので、新しく増えたものはCIで止める形にしておきます👍

PHP 側は、PHPStan の拡張の staabm/phpstan-todo-by が使えます。

Packagist では2026年6月8日の 0.3.4 が出ていて、参照している GitHub の課題やPRが閉じたら、そのTODOをエラーとして出してくれる拡張です💡

composer require --dev staabm/phpstan-todo-by

phpstan/extension-installer を入れていれば自動で読み込まれます!

課題のチェックは初期設定ではオフなので、phpstan.neon でオンにします。

parameters:
    todo_by:
        ticket:
            enabled: true
            tracker: github
            github:
                defaultOwner: your-name
                defaultRepo: your-repository
                credentials: null
                credentialsFilePath: null

コメントは // TODO: #123 - fix me や // TODO: GH-123 - fix me の形で書けば、defaultOwner と defaultRepo の課題として見てくれます。

プライベートリポジトリなら、credentials か credentialsFilePath で GitHub のトークンを渡す必要があります(・_・;)

フロント側(TypeScript・Vue)は、ESLint の no-warning-comments で「TODOを書いたら警告」にできます。

// eslint.config.js
export default [
  {
    rules: {
      'no-warning-comments': ['warn', {
        terms: ['todo', 'fixme'],
        location: 'anywhere',
      }],
    },
  },
];

こちらは課題の状態までは見てくれません(´・ω・`)

なので私なら、いきなり error にはせず warn で数を見える化するところから始めます。

location: 'anywhere' にしておくと、// これは遅い。todo: キャッシュする のような文の途中のTODOも拾えます✨

🤔 消す前に確認したいこと

Google の記事でも強調されていたのが、課題が閉じていても、そのTODOがまだ意味を持っていることがあるという点です。

例えば「#123 が直るまでこの回避策を残す」というTODOは、課題が閉じた今こそ回避策ごと消すべきかもしれません。

逆に、課題は閉じたけど別の課題に引き継がれていて、コメントの番号だけが古いパターンもあります👀

なので消す前に、この3つは見るようにしたいです。

  • 課題の最後のコメント(別の課題に移っていないか)
  • そのTODOの行を git log -L や git blame で追って、いつ・どのPRで入ったか
  • TODOのすぐ下にある回避策のコードを、一緒に消してよいか

コメントだけ消して回避策が残ると、今度は「理由の分からないコード」が残ります。

ここは Rector のときと同じで、まとめて1つの大きいPRにしないのが安心です!

AIエージェントに渡す指示ファイル(CLAUDE.md や AGENTS.md)に1行足しておくのも、手軽な対策です🙌

コード中のTODO/FIXMEは、依頼された作業と直接関係しない限り調べたり直したりしない。気になったものは最後に一覧で報告する。

掃除が終わるまでのつなぎとしては、これだけでも寄り道はかなり減らせるはずです。

🔗 関連記事と使い分け

「古い物をいきなり消さずに、確認しながら減らす」という考え方は、このブログの別の記事とも近いです。

パパ系Webエンジニア〜愛用ガジェット一覧 🛍️

この記事を書いている作業環境のガジェットを楽天ROOMにまとめています ✨ 在宅エンジニアのデスク作りの参考にどうぞ 🙌

👍 まとめ

AIエージェントの寄り道を減らす一番手軽な方法は、閉じた課題を指しているTODOを先に掃除しておくことでした。

git grep で番号つきのTODOを集めて、gh issue view で閉じたものだけ出せば、最初の候補はすぐ作れます🙌

あとは PHPStan の staabm/phpstan-todo-by や ESLint の no-warning-comments で、新しく溜まらないようにしておけばOKです(^o^)/

人間は「いつかやる」で済ませてきたコメントも、AIはちゃんと読んでしまう時代なんですよね・・・!

みなさんのリポジトリには、課題番号つきのTODOがどれくらい眠ってますか?


※ バージョン番号・料金・機能は今後も変わる可能性があります。最新情報は公式サイトをご確認ください👀

参考になったらシェアしてもらえるとうれしいです🙌

Xでポスト Threads はてブ LINE