Cloudflare のブログに「How we built a software factory to drive Astro’s GitHub issue count to zero」という記事が出ました(Matthew Phillips、2026-08-04 公開、2026-08-21 取得)。Astro のリポジトリで自動トリアージを数か月回して、未解決 issue を 200 件超から約 30 件まで減らした話です。
仕組みの話として読めますが、私が持ち帰ったのは別のところでした。エージェントが繰り返し失敗した箇所を、エージェントの成績ではなく、そのコードが人間にとっても読みにくい場所の印として扱っている点です。
自分の保守しているコードベースにエージェントを入れていて、失敗が積み上がっている人向けです。先に要点だけ:
- エージェントが同じ箇所で繰り返し間違えたとき、原文はそれを3つのうちどれかの印として読む。境界が不透明な抽象、説明の無いコード、足りないテスト。どれも人間にとっての読みにくさと同じもの
- 直し方は命令ファイルに規則を足すことではなく、コードにコメントとテストを足すこと。原文には、ある
if条件の意味を説明するコメントを足したら、エージェントがその場所で誤った書き換えをしなくなった、という例がある - この直し方だと、次に来る人間も同じだけ楽になる。命令ファイルを育てる直し方では、次のエージェントしか得をしない
記事が書いていること
以下はすべて上記 URL、2026-08-21 取得。
数字はこうです。「未解決 issue を 200 件超から約 30 件に減らし、来月中にはゼロになる見込み。そうなれば 5 年を超えるこのリポジトリの歴史で初めて」。「issue 破産」を宣言したわけでも、古いチケットを自動で閉じたわけでもない、と明記しています。この数字は私には追試できないので、出典つきの引用として扱います。
パイプラインは4段で、人間がバグを追うときの段取りをそのまま写したものです。
| 段 | やること |
|---|---|
| Reproduce | 報告に添えられた再現リポジトリを clone して、報告どおりに起きるか確かめる |
| Diagnose | コードにログを仕込み、根本原因の場所を特定する |
| Verify | テスト・コメント・ドキュメントを読み、それがバグなのか意図した挙動なのかを判定する |
| Fix | 再現を失敗するユニットテストに変換し、アーキテクチャガイドに沿って解を選び、修正する |
各段は隔離されたサブエージェントが実行し、発見を report.md に書き出して次の段に渡します。段を分けるのは「バグが実在しないかもしれない場面で解を捻り出そうとする LLM の偏り」を防ぐためだ、と原文は書いています。
修正に至ると pkg.pr.new でプレビュー版を作って issue に投稿し、報告者本人が自分のプロジェクトで動いたと確認したときに初めて pull request が開きます。状態は issue のラベル(triage needed と fix verified)だけで持ち、実装は triagebot-action として切り出されています。設定例ではトリアージ用と検証用に別のモデルが指定されていますが、分けた理由は原文に書かれていません。
失敗を何の印として読むか
ここが本題です。原文は、エージェントが正解に至らないとき、その失敗を次の3つのどれかを指す印として読む、と書いています。
- 不透明な抽象。エージェントがコンポーネント間の境界を読み取れないなら、人間の開発者もそのコード構造に苦労している可能性が高い
- 説明の無いコード。重要な箇所に、なぜそう実装したかのコメントが無い
- 足りないテスト。特にユニットテストの被覆が薄い
具体例として挙がっているのが HMR(Hot Module Replacement)まわりの一連のバグです。ボットは特定の if 条件を繰り返し書き換えようとしました。その変更は当該バグを直すのですが、その条件にテストが無かったため、別の場所に回帰を生みました。ここで取った対処は、ボットに「その条件を触るな」と指示することではなく、その条件が何を支配しているかを説明するコメントをコードに1つ足すことでした。それ以後、ボットはその場所で誤った書き換えを試みなくなった、とあります。
原文の締めはこうです。欠けていたコメント・テスト・境界を足すたびにボットはその箇所で目に見えて良くなり、次にそこを触る人間も同じだけ良くなる。
手元にどう効きそうか
ここからは見立てです。
「エージェントが繰り返し失敗する」という信号の読み方は、実は二通りあります。ひとつは、命令ファイル(CLAUDE.md や copilot-instructions.md)に「ここではこうしろ」と規則を足す方向。もうひとつは、コード側にコメントとテストを足す方向です。手元の経験では前者に流れがちで、Claude Code や Copilot CLI の公式ドキュメントもたいてい前者を勧めます。たとえば Copilot CLI の /chronicle improve は、エージェントの失敗ややり直しを読んで改善を提案する機能ですが、提案先は copilot-instructions.md という命令ファイルです(docs.github.com、2026-08-07 取得)。
Astro の記事が新しいのは、同じ信号を読んで是正をコードに送っている点です。命令ファイルに足した規則は、次のエージェントにしか効きません。コードに足したコメントは、次のエージェントにも、次の人間にも効きます。同じ手間なら後者のほうが得です。
もうひとつ効きそうなのは、「読みにくい」が件数になることです。原文がその回数を数えて並べたとは書いていないので、ここは私の推測です。人間のコードレビューで「ここは読みにくい」と言っても主観として流れますが、エージェントが同じ箇所で直せなかった回数は積み上がります。数えておけば、可読性の負債に優先順位を付ける数字になるはずです。
ただしこの読み替えは、失敗の原因が自分たちの保守物の中にあるときにしか使えません。外部ライブラリや環境が原因の失敗に同じ手は効きません。
手元での追試はしていません。やるなら、直近でエージェントが繰り返し誤った書き換えを試みた箇所に説明コメントを1行足して、同じ依頼を投げ直して挙動が変わるかを見る、という最小の形になります。
まとめ
- エージェントが同じ箇所で繰り返し間違えたら、命令ファイルに規則を足す前に、その箇所のコードにコメントかテストが欠けていないかを見る
- 直すのは命令ファイルではなくコード。コメントを足すだけで止まった例が原文にある。コードに足した説明は次の人間にも効く
- 直せなかった回数は数えておく。「読みにくい」に優先順位を付けられる数字になる
- 外部依存や環境が原因の失敗には使えない。自分たちが保守しているコードの中でだけ成り立つ