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は、依頼された作業と直接関係しない限り調べたり直したりしない。気になったものは最後に一覧で報告する。
掃除が終わるまでのつなぎとしては、これだけでも寄り道はかなり減らせるはずです。
🔗 関連記事と使い分け
「古い物をいきなり消さずに、確認しながら減らす」という考え方は、このブログの別の記事とも近いです。
- RectorでLaravelの古い書き方を自動で直した話: 書き方の置き換えは Rector、コメントの掃除は今回の手順。どちらも
--max-changesのように少しずつPRにするのがコツ - MySQLの使っていないインデックスを不可視にしてから消した話: 「使っていなさそう」をすぐ消さずに確かめる流れは、閉じた課題のTODOとまったく同じ考え方
パパ系Webエンジニア〜愛用ガジェット一覧 🛍️
この記事を書いている作業環境のガジェットを楽天ROOMにまとめています ✨ 在宅エンジニアのデスク作りの参考にどうぞ 🙌
👍 まとめ
AIエージェントの寄り道を減らす一番手軽な方法は、閉じた課題を指しているTODOを先に掃除しておくことでした。
git grep で番号つきのTODOを集めて、gh issue view で閉じたものだけ出せば、最初の候補はすぐ作れます🙌
あとは PHPStan の staabm/phpstan-todo-by や ESLint の no-warning-comments で、新しく溜まらないようにしておけばOKです(^o^)/
人間は「いつかやる」で済ませてきたコメントも、AIはちゃんと読んでしまう時代なんですよね・・・!
みなさんのリポジトリには、課題番号つきのTODOがどれくらい眠ってますか?
※ バージョン番号・料金・機能は今後も変わる可能性があります。最新情報は公式サイトをご確認ください👀