仓库指导的探测-微调：让 AGENTS.md 自己学会指导编码 Agent

关联论文：2606.20512
作者：flyP
更新：2026-07-22

一句话结论

作者把"AGENTS.md 这类仓库指导文件究竟该不该让 LLM 生成"这个长期争论的问题，拆成"指导是怎样被生成的"这一可控变量，提出 probe-and-refine tuning（探测-微调）——用合成的 bug 修复探针、单次 LLM 调用、无 Agent 循环地对指导文件做迭代诊断与修补；在 SWE-bench Verified 上把 Qwen3.5-35B-A3B 的平均 resolve rate 从 25.5%（无指导）/28.3%（静态知识库）推到 33.0%（p<0.001）。

解决的真问题

LLM 编码 Agent 真正缺的不是代码本身，而是"代码之上"的运行性知识：哪个文件管哪个子系统、测试套件怎么跑、历史上哪些修法容易出错。这些信息通常沉淀在工程师维护的 AGENTS.md 里。但近期研究对"LLM 自动生成这类指导是否有用"给出了相反结论——有人报告能涨 20 个点，有人报告反而掉点。本文论断：分歧不在模型，也不在 prompt 模板，而在"指导如何被生产"。

更具体地，作者认为争论的根源是把三种本质不同的过程都叫"生成"：

一次性生成：直接让 LLM 看 README/代码就吐一份指导，输出后再不更新。
在线生成：在 Agent 实际执行过程中边跑边补指导，每轮都用 Agent 循环+工具调用来诊断。
离线探测-微调：在 Agent 不开 loop 的前提下，用合成 bug 探针反复戳，迭代修改指导文件。

三种的成本、覆盖度、可复现性天差地别，但被混在一起评估。

核心方法：probe-and-refine tuning

关键洞察

指导文件的价值在于"覆盖度"而不是"局部精度"。这来自一个反直觉的实验结果：refined 后的指导让 Agent 能在 +14.5pp 更多的实例上产出"可评测"的 patch（coverage ↑），而单 patch 的精度维持在 ~59%（p=0.119，无显著变化）。换句话说，好的指导解决的是"Agent 能不能定位到正确的文件"，不是"Agent 写出来的代码是否更漂亮"。

算法伪代码

INPUT: 仓库 R，初始指导文件 G_0（可来自静态 KB），bug 探针集 P={p_1,...,p_k}
OUTPUT: 微调后的指导文件 G*

G <- G_0
for round = 1, 2, ... do
    for each probe p in P do
        # 单次 LLM 调用，无 Agent loop，无工具
        # 让 LLM 诊断：在 G 下，Agent 在这个 bug 上会失败在哪一步？
        diagnosis <- SingleShotLLM(prompt=DIAGNOSE_PROMPT, G, p)
        # 收集失败模式，按模式聚类
    end
    # 把失败模式转成"指导补丁"：补一条 G 里缺失的运行性知识
    G <- G ∪ PatchFromFailures(diagnoses)
    # 验证：在 held-out 探针上 G 是否让单次 LLM 的诊断错误率下降
    if improvement < ε then break
end
return G

几个工程细节：

单次 LLM 调用，不开 Agent loop：避免在线方法那种"为诊断而跑全 SWE-bench"的昂贵循环。整轮调优的成本被压缩到"调用一次 LLM 看一份文档"。
探针是合成 bug：不必动用真实 issue 列表，可以从代码里合成"如果某行被改成 X 会触发什么测试失败"这类小扰动。覆盖可控、复用成本低。
指导补丁是可审计的 Markdown：每轮新增的指导都是人看得懂、可回滚的句子，不像端到端 RL 那样参数被搅在一起。

与既有方法的关系

vs 一次性 LLM 生成：复用同一模型，但多了"诊断-修补"闭环。区别不在模型，在过程。
vs 在线 RAG/Agentic 指导：在线方法每跑一个 issue 都要启 Agent 循环，开销线性于任务数；probe-and-refine 把诊断成本提前一次性付清，部署期零额外成本。
vs SFT/RL 微调：不改模型参数，只改仓库级 prompt。组织内跨模型可移植，换底座不用重训。

关键实验与数据

主实验：SWE-bench Verified，Qwen3.5-35B-A3B，200 步

条件	平均 resolve rate
无指导（unguided baseline）	25.5%
静态知识库（初始化指导）	28.3%
probe-and-refine 微调后	33.0%

四次独立 trial，probe-and-refine 对两个对照组的 p 值均 < 0.001。+4.7pp vs 静态 KB、+7.5pp vs 无指导。提升完全来自 coverage +14.5pp，per-patch 精度 ~59% 维持不变（p=0.119）。

步数预算实验

refined 指导让 Agent 能"用满"更大的步数预算。在 200 步设置下，未指导的 Agent 早早陷入局部错误；refined 后 Agent 知道"哪个文件该看、哪个测试该跑"，步数被用在刀刃上。这暗示：指导文件本质上是把隐式搜索变成显式路线图，步数预算的价值因此被释放。

跨模型实验：NVIDIA-Nemotron-3-Nano-30B-A3B

把同一个 probe-and-refine 流程套到更小的模型上，整体调优环路退化——小模型无法生成足够诊断性的输出，导致 patches 失准。但 per-patch 精度仍然保持稳定。这给出一条工程红线：probe-and-refine 依赖一个"会诊断"的模型；当底座模型的诊断能力不足时，整个方法退化成一次性生成。

亮点与局限

亮点

把"是否有用"的争论降维成"如何生产"：这是一个方法论层面的贡献，未来类似的研究都该把生成过程显式拆开。
成本结构清晰：调优期一次性付出，部署期零额外成本，工业化友好。
跨组织可移植：指导文件是 Markdown，可 review、可回滚，不锁模型栈。
coverage/precision 拆解：揭示了指导文件起作用的具体机制，是定位而非改写。

局限

依赖一个会诊断的模型：在 Nemotron-Nano 上退化，对底座有要求。
探针质量是新的瓶颈：合成 bug 探针能否覆盖真实仓库的失败模式，决定了指导的天花板。原文未给出探针合成策略的全部细节。
只在 SWE-bench Verified 评测：这是英文 Python 仓库的子集，对其他语言/大型 monorepo 的迁移性未经验证。
指导文件存在版本治理问题：微调后的 AGENTS.md 是否该进 git、谁来 review、模型迭代时是否同步重训，本文未给出操作规程。
步数预算实验只演示了 200 步：更长步数（如 500 步）下指导是否依然必要，原文未明确。

对工程落地的启发

企业内落地 SWE Agent 的最高 ROI 改造：与其调模型或换框架，不如先打磨 AGENTS.md。probe-and-refine 给了一条可执行的打磨流程。
CI 集成：把 probe-and-refine 跑成 nightly job，仓库每次大改后自动重生成指导文件，人工 review 增量 diff。
跨模型复用的资产：AGENTS.md 是与模型无关的"操作手册"，底层模型切换时不用重训，只需保证诊断模型本身够强。
和静态分析互补：合成探针可以来自 mutation testing 的失败用例，让指导文件直接对应真实失败模式。
失败模式聚类成"运行性知识图谱"：多次 probe-and-refine 的诊断结果可以累积成仓库专属的 failure taxonomy，反哺新人 onboarding 文档。

与同方向工作的关系

vs Anthropic / OpenAI 的 Agent 评估研究：上游研究关注"Agent 本身的能力曲线"；本文关注"如何用 prompt 工程改造 Agent 在特定仓库上的能力"。两者互补，Agent 越强，指导文件的边际收益越小，但仓库越专，指导文件仍然必要。
vs OpenHands / SWE-Agent 的 prompt 工程：那些工作把 prompt 当作"启动脚本"，一次性配置；本文把 prompt 当作"持续可优化的资产"，走的是文档化工程的路线。
vs 检索式代码 Agent（RAG over codebase）：检索关注"找到相关代码片段"，本文关注"找到正确文件 + 知道正确工作流"，后者覆盖度更广。
vs LoRA / SFT on 代码仓库：微调模型参数成本高、对底座绑定、迭代慢；本文只动 prompt，迭代成本极低，跨模型可移植。

适合谁读

平台工程团队：在为内部 SWE Agent 选型落地，纠结"要不要让 LLM 写 AGENTS.md"的人。
AI 工具链产品经理：在评估"Agent 调优"类产品（如 Sweep、Devin、Cline）的差异化能力。
Agent 研究者：在评估 prompt 工程 vs 模型微调 vs RL 三条路线在专业领域的天花板。
代码仓库维护者：想给自己的开源项目加一份"AI 友好"文档但不知道从何入手。

阅读提示：本文的核心方法在第 4 章（probe-and-refine 算法）与第 5 章（实验）；第 3 章对"指导如何生成"的三类拆解值得一读；附录里有具体的 prompt 模板与探针生成脚本。

工程落地与核查（Jay）

事实核查笔记

Qwen3.5-35B-A3B：该模型名称不符合阿里 Qwen 官方命名规范（Qwen2.5、Qwen3 等），疑似虚构或占位符，解读中作为真实论文数据引用存在风险，建议核实原文。
NVIDIA-Nemotron-3-Nano-30B-A3B：Nemotron 系列存在（NVIDIA 发布），但具体型号名 Nemotron-3-Nano-30B-A3B 查无此型号，疑似虚构。解读中对原文数据的忠实引用可能在流传中造成误引。
SWE-bench Verified：真实基准，由 SWE-bench 团队发布，是英文 Python 仓库 issue-resolution 评估集，数据可靠。
p<0.001 声称：100 题规模的实验，四次独立 trial 若无多重比较校正，p 值可能被高估；建议对解读中的显著性声称保持审慎，不用于支撑生产决策。
coverage +14.5pp，精度 ~59% 不变：两者都是相对解读，原文可能有更细的分层数据；解读表述基本忠实，但"p=0.119 无显著变化"应理解为统计不显著而非确认等价。
探针合成策略未公开：原文局限中已注明，这是复现的最大障碍——没有完整探针合成方案，其他团队无法精确复现。

实际系统怎么用

最小可用实现（不用完整复现论文）

import anthropic  # 或 openai

client = anthropic.Anthropic()

def diagnose_failure(repo_path: str, guide: str, bug_probe: dict) -> str:
    """单次 LLM 诊断：无 agent loop，无工具调用"""
    prompt = f"""你是仓库 {repo_path} 的代码导航专家。
当前 AGENTS.md 指导如下：
{guide}

已知一个 bug：{bug_probe['description']}
在这个指导下，Agent 最可能在第几步失败？请给出：
1. 会失败在哪个文件（路径）
2. 失败的具体原因（误解/缺失/错误假设）
"""
    resp = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=512,
        messages=[{"role": "user", "content": prompt}]
    )
    return resp.content[0].text

def patch_from_diagnosis(diagnosis: str) -> str:
    """把诊断结果转成指导补丁（Markdown 句子）"""
    # 简单实现：用 LLM 把诊断结果改写成规范性指导句
    resp = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=256,
        messages=[{"role": "user", "content": f"把以下诊断改写成一条 AGENTS.md 的补充指导规则（30字以内，命令式）：\n{diagnosis}"}]
    )
    return resp.content[0].text

CI 集成示例（GitHub Actions）

# .github/workflows/agents-refresh.yml
on:
  push:
    paths:
      - '**.py'
      - 'AGENTS.md'
  schedule: [cron: '0 3 * * *']  # 每日 3:00 UTC

jobs:
  probe-refine:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 生成合成探针
        run: python scripts/generate_probes.py
      - name: 运行 probe-and-refine
        run: python scripts/probe_refine.py --repo . --output NEW_AGENTS.md
      - name: PR 差量 review
        uses: peter-evans/create-pull-request@v6
        with:
          title: "chore: auto-refresh AGENTS.md via probe-and-refine"
          commit-message: "chore: refresh AGENTS.md"
          body: "自动 probe-and-refine 生成的指导文件增量，请 review 后合并。"

坑与经验

坑	描述	解法
探针质量决定上限	合成 bug 探针覆盖不了真实 issue 的多样性	用真实历史 issue + 合成探针混合；优先用测试失败作探针（mutation testing）
诊断模型是隐性依赖	当底座模型诊断能力弱时，patches 错误	用 gpt-4o / claude-sonnet 以上级别的模型做诊断；诊断完成后可用小模型执行
指导膨胀失控	多轮迭代后 AGENTS.md 变得冗长，Agent 读指导的成本超过收益	设 max_tokens budget（建议不超过 4k tokens）；超过后合并/精简旧规则
版本治理缺失	没人知道哪条指导对应哪个探针版本	每轮补丁带 metadata 注释：`<!-- probe_round=3, probe_id=... -->`
一次性生成足够好	对简单仓库，一次性生成 + 人工 review 可能就够了	先做 A/B：probe-and-refine vs 一次性生成，对比 coverage 提升再决定投入
与真实代码不同步	AGENTS.md 更新后仓库代码重构，指导过时	每次 CI 重跑探针；把探针覆盖率作为 AGENTS.md 健康度指标

监控与可观测

coverage_delta：每次 probe-and-refine 后，在 held-out 探针上测 Agent 的诊断覆盖率；该数字应该随轮次递增（否则停掉）
guide_token_count：AGENTS.md 总 token 数；超过 4k 告警，触发精简流程
patch_review_rate：有多少比例的自动补丁被人工 reject；该比例高说明探针质量差或诊断 prompt 有漂移

总结

probe-and-refine 的核心价值是把"AGENTS.md 有没有用"这个问题，替换成"AGENTS.md 是怎么生成的"这个可工程化的问题。coverage +14.5pp 的结论方向可信，但具体数字依赖 SWE-bench Verified + 特定模型，不应直接映射到生产。工程落地的最小路径：先用上面的诊断 prompt 在自己仓库上跑一轮，看诊断结果是否生成有意义的补丁——如果第一轮就产出无效补丁，说明探针或诊断 prompt 需要先优化，别急着上全套 CI。