Failure-tested AGENTS.md files for repository-specific coding agents
Teams using coding agents can make repository guidance part of the test workflow. A practical version starts with a short AGENTS.md file, generates synthetic bug-fix probes for that repository, asks the agent to attempt fixes, and edits the guidance only where the failed runs show missing or misleading instructions. The resulting file should name subsystem entry points, test commands, known brittle paths, and quality gates in compact form.
Probe-and-Refine gives a concrete shape to this workflow. On 500 SWE-bench Verified instances, refined guidance reached a 33.0% mean resolve rate, compared with 28.3% for a static knowledge base and 25.5% with no context. The reported gain came mainly from more evaluable patches, not higher per-patch precision. That matters for maintainers because a bad instruction file often sends an agent to the wrong file or leaves it stuck before a meaningful patch exists.
A cheap adoption test is to run the same agent on a small set of recent fixed bugs with three guidance variants: no file, a hand-written file, and a probe-refined file. Track whether the agent finds the right files, runs the right tests, and produces a patch that reaches review. If the refined file only adds generic advice, it should be rejected like any other unhelpful repository artifact.