同じ if 条件を、ボットが何度も書き換えようとする。その変更で目の前のバグは直るけれど、別の場所で不具合が出る。Astro の開発で起きた話です。
その条件が何を制御しているのかをコメントに書いたら、誤った書き換えを試みなくなったそうです。私なら、また指示ファイルに注意書きを足していたと思います。コードのそばに理由を書く、という対処が気になりました。
出典は Matthew Phillips さんの「How we built a software factory to drive Astro’s GitHub issue count to zero」(2026-08-04 公開、2026-08-21 取得)。Astro の未解決 issue を、自動トリアージを使って 200 件超から約 30 件まで減らした取り組みの中で紹介されています。
その if 条件が必要な理由は、コードだけでは伝わらなかった
問題があったのは、開発中の変更を画面に反映する HMR (Hot Module Replacement) まわりです。書き換えられていた条件にはテストがなく、変更すると別の場所に影響することを、テストでは確かめられませんでした。
記事では、エージェントが直せない箇所について、コードの構造や説明にも問題がないかを見るとしています。
- コンポーネントの役割分担が読み取りにくい
- なぜその実装なのかを説明するコメントがない
- 期待する動作を確かめるテストが足りない
初めてそのコードを読む人も、同じところで迷いそうです。「そこを触るな」と言われても、理由が分からなければ、次に似た修正をするときに困ります。コメントなら、その条件式を変えてよいかを判断する材料も残せます。
バグの修正を始めるまでにも、段取りがある
ボットの仕事全体も、いきなり修正案を作る流れにはなっていませんでした。
| 段階 | やること |
|---|---|
| 再現 | 報告に添えられたリポジトリを clone し、報告どおりに起きるか確かめる |
| 原因調査 | コードにログを入れ、原因の場所を特定する |
| 仕様の確認 | テスト・コメント・ドキュメントを読み、バグか意図した動作かを判断する |
| 修正 | 再現例をユニットテストにし、アーキテクチャガイドに沿って修正する |
各段階は別のサブエージェントが担当し、調べたことを report.md で次に渡します。バグがあるか分からないうちから修正案を作り始めるのを防ぐために、段階を分けたと説明されています。
修正後は pkg.pr.new でプレビュー版を作り、issue に投稿します。報告者が自分のプロジェクトで動作を確認してから pull request を開く流れです。実装は triagebot-action で公開されています。コードができたところで終えず、困っていた人の環境でも確かめてもらっています。
次にそのコードを読む人にも、理由を残したい
私も、失敗が続くと CLAUDE.md や copilot-instructions.md に規則を足しがちです。GitHub Copilot CLI にも、過去の失敗ややり直しから指示ファイルの改善を提案する /chronicle improve があります(ドキュメント、2026-08-07 取得)。
今回の例を読むと、注意書きを置く先は指示ファイルだけではないと思えます。なぜその実装なのかをコードに書けば、指示ファイルを読んでいない開発者にも伝わります。
外部ライブラリや実行環境が原因なら、コメントでは直りません。手元ではまだ試していませんが、繰り返し間違えられた条件式を一つ選び、必要な理由をコメントに書いて、同じ修正を頼んでみたいです。その説明は、次に自分が読むときにも残ります。