Probe-and-Refine Tuning of Repository Guidance for Coding Agents

2026-06-21

2026-06-22

Probe-and-Refine のグラレコ

30秒で言うと

コーディングエージェントに渡す AGENTS.md や repository guidance は、あるだけで良くなるわけではない。

この論文は、静的に作った repository knowledge base を、合成バグ修正プローブで試し、失敗を診断し、短い運用指示へ反復的に磨く probe-and-refine tuning を提案している。

SWE-bench Verified では、no guidance が 25.5%、static KB が 28.3%、probe-and-refine が 33.0% の resolve rate だった。面白いのは、patch そのものの精度が上がったのではなく、評価可能な patch まで到達する coverage が増えたことだ。

この記事で持ち帰ること

AGENTS.md や repository guidance は、長く詳しく書けばよいものではなく、agent が正しい探索・再現・修正まで到達できるかで評価する運用資産である。
この論文の主な改善は、patch の正答率そのものではなく、評価可能な patch まで到達する coverage を増やした点にある。
guidance は model や step budget と相性がある。複雑な手順は、十分な手数がないとむしろ agent loop を崩す。
自分の運用に戻すなら、手順書を一発で完成させるのではなく、失敗しやすい小さな probe を作り、coverage / precision / budget / model fit を見ながら直す。

この論文の何がいいか

この論文の良さは、エージェント向けの指示文を「良いことが書いてあるメモ」ではなく、行動を変える operational guidance として測っているところにある。

コードベースには、どのファイルを見るべきか、どのテストを走らせるべきか、どの fallback に落ちやすいか、どの修正が危ないか、という運用知識がある。人間は雰囲気で覚えているが、agent はそれを毎回 prompt から復元しようとする。

ただし、指示を置けば解決するわけではない。先行研究では、LLM が生成した context file が agent を誤誘導し、むしろ resolve rate を下げる例も報告されている。この論文は、そこを「指示があるか」ではなく「どう作った指示か」に分解する。

ゆうきの文脈では、これは AGENTS.md、Codex skill、scheduled-ops、article-page-publisher の手順書をどう育てるかにそのまま刺さる。手順書は長くすれば良いのではなく、失敗プローブに当てて、coverage を増やし、step budget と model fit に合う形へ調整する必要がある。

どんな論文か

Probe-and-Refine Tuning of Repository Guidance for Coding Agents は、coding agent が repository-specific な運用知識を使って、現実の GitHub issue を修正できるかを調べる論文である。

対象は SWE-bench Verified の 500 instances。各 instance は実在する Python repository の issue で、agent が patch を作り、held-out test suite を通れば resolved とされる。

比較する条件は大きく三つある。

no guidance: repository guidance なし
static KB: tree-sitter などで repository structure を見て作った静的 knowledge base と generic guidance
probe-and-refine: static KB を初期値にし、合成プローブで失敗を診断して更新した guidance

probe-and-refine の特徴は、重い agentic training ではないことだ。tuning 中は multi-step agent loop も tool use も使わず、single-shot LLM call の組み合わせで、合成バグ修正プローブ、試行、judge、diagnostic aggregation、guidance edit を回す。最終的な guidance は 3000 文字以内の compact artifact として repository ごとに作られる。

課題と貢献

第一の貢献は、repository guidance を失敗から反復的に磨く probe-and-refine tuning を示したこと。

第二の貢献は、改善の内訳を coverage と precision に分けたこと。probe-and-refine は、評価可能な patch を出す割合を増やすが、評価に到達した patch が正しい確率そのものは大きく変えない。

第三の貢献は、step budget との相互作用を測ったこと。複雑な guidance は、十分な step budget がある時にだけ効く。短い予算では、より単純な static KB より悪くなる場合がある。

第四の貢献は、model fit の問題を出したこと。Qwen 向けに作った guidance を Nemotron にそのまま渡すと、agent loop が崩れ、fallback cascade が起きた。

手法のしくみ

まず repository の構造を見て、静的な knowledge base を作る。ここには、ファイル構造、よく見るべき subsystem、テストや実装に関する repository-specific な情報が入る。

次に、各 iteration で合成バグ修正プローブを生成する。これは本番の SWE-bench instance そのものではなく、guidance の弱点を炙り出すための小さな probe である。

その probe を single-shot で解かせ、期待される behavior と照合する。judge は、agent がどこで迷ったか、何を見落としたか、どの operational rule が足りなかったかを診断する。

最後に、診断を aggregate し、guidance を機械的に更新する。重要なのは、ただ「もっと詳しく書く」のではなく、repository の中で agent が間違えやすい行動を減らし、正しいファイルやテストへ到達しやすくする形で指示を変えることだ。

生成された guidance は、実際の coding agent が SWE-bench Verified を解く時に使われる。評価は official SWE-bench harness で行われる。

検証結果

主実験では、Qwen3.5-35B-A3B を使い、SWE-bench Verified 500 件を 200 steps で評価している。

resolve rate は次の通り。

no guidance: 25.5%
static KB: 28.3%
probe-and-refine: 33.0%

probe-and-refine は、static KB と no guidance の両方に対して有意に良い結果を出した。

ただし、改善の中身が大事だ。論文は、per-patch precision は約 59% で統計的に一定だと報告している。つまり、評価まで届いた patch の正しさが大きく上がったわけではない。

改善は coverage から来ている。refined guidance は、評価可能な patch を 14.5pp 多く出した。言い換えると、agent が正しいファイルへ到達し、patch として評価できる形まで持っていく確率が上がった。

step budget の実験も実務的に重要だ。25 steps では各条件がほぼ同等。50 steps では、probe-and-refine が static KB を下回る。これは、probe-and-refine が勧める reproduce-trace-patch 的な workflow が、50 steps では完走しづらいためと解釈されている。

100 steps、200 steps になると probe-and-refine が伸びる。複雑な guidance は、十分な行動予算があって初めて効く。

cross-model ではさらに注意が必要になる。Qwen 向け guidance を Nemotron に転用すると、Nemotron は行動せずに分析文を書きやすくなり、agent loop から patch が出ず、single-shot fallback に流れる。しかも fallback patch は malformed になりやすい。ここから、guidance は model-specific な行動校正を含むと読める。