# Teste deine Coding-Agent-Instruktionen wie Code Canonical URL: https://huecki.com/blog/coding-agent-instruktionen-testen/ Markdown URL: https://huecki.com/blog/coding-agent-instruktionen-testen.md Language: German Published: 2026-06-22 Updated: 2026-06-22 Author: Dominic Hückmann Topic: AI Agent Workflows - Agent topics: Agent Harnesses, Context Engineering, Agent Evals - Tags: Coding Agents, AI Engineering, Developer Workflow, AGENTS.md, Evals Content status: field-note ## Summary Eine gute AGENTS.md ist kein Prompt-Dokument, das man einmal schreibt. Sie ist ein kleines Betriebshandbuch fuer den Agenten. Und Betriebshandbuecher werden besser, wenn man sie gegen konkrete Fehler testet. ## Description Probe-and-Refine Tuning zeigt einen praktischen Workflow: AGENTS.md nicht einmal schreiben und hoffen, sondern mit synthetischen Bugfix-Proben testen, Fehler diagnostizieren und gezielt nachschärfen. ## Body ## Die kurze Version Viele Teams schreiben eine `AGENTS.md` wie einen guten Vorsatz. Einmal anlegen. Ein paar Regeln rein. "Bitte Tests ausfuehren." "Bitte bestehende Patterns beachten." "Bitte keine grossen Refactorings." Danach hoffen alle, dass der Coding Agent schon versteht, was gemeint ist. Das ist zu weich. Eine `AGENTS.md` ist kein Deko-Prompt. Sie ist ein kleines Betriebshandbuch fuer ein System, das Dateien aendert. Also sollte sie wie ein Systemartefakt behandelt werden: testen, Fehler finden, nachschaerfen, erneut testen. Genau darum geht es in [*Probe-and-Refine Tuning of Repository Guidance for Coding Agents*](https://arxiv.org/abs/2606.20512). Die praktische Idee ist einfach: ```txt Schreibe nicht einfach bessere Agenten-Anweisungen. Erzeuge Aufgaben, an denen schlechte Anweisungen sichtbar scheitern. ``` Der wichtige Punkt ist nicht die genaue Zahl. Der wichtige Punkt ist die Richtung: Die bessere Guidance kam nicht aus mehr Prompt-Magie, sondern aus Fehlerbeobachtung. ## Das Problem mit AGENTS.md Coding Agents brauchen Wissen, das nicht sauber im Code steht. Zum Beispiel: - Welche Datei ist der Einstiegspunkt fuer welche Funktion? - Welche Tests sind schnell genug fuer lokale Iteration? - Welche generierten Dateien darf man nicht manuell anfassen? - Welche Migrationsreihenfolge ist im Projekt heikel? - Welche alten Workarounds sehen falsch aus, sind aber absichtlich da? - Welche Aenderungen brechen gern CI, obwohl sie lokal harmlos wirken? Das ist operationales Repo-Wissen. Menschen lernen es durch Schmerz. Agenten sehen es oft erst, nachdem sie einen Patch in die falsche Richtung gebaut haben. Eine statische `AGENTS.md` versucht, dieses Wissen vorab aufzuschreiben. Das hilft manchmal. Aber es hat eine Schwachstelle: Du weisst selten, welche Anweisung fehlt, bis der Agent falsch abbiegt. ## Der Workflow Probe-and-Refine ist im Kern ein kleiner Eval-Loop fuer Repo-Anweisungen. Praktisch kann das so laufen: 1. Erzeuge eine erste `AGENTS.md` aus Repo-Struktur, Paketmanager, Testbefehlen und bekannten Konventionen. 2. Generiere 5 bis 10 synthetische Bugfix-Issues, die typische Repo-Fallen beruehren. 3. Lass einen Agenten oder ein Diagnose-LLM pro Issue sagen, wo ein Coding Agent vermutlich falsch abbiegt. 4. Schreibe fuer jeden echten Failure Mode genau die Guidance-Zeile, die geholfen haette. 5. Wiederhole den Lauf und pruefe, ob die neue Guidance die Fehler besser abfaengt. Der Prompt zum Stehlen: ```txt Generiere 10 synthetische Bugfix-Issues fuer dieses Repository. Ziel: Die Issues sollen fehlendes operationales Wissen in AGENTS.md sichtbar machen. Fuer jedes Issue: - beschreibe den wahrscheinlichen falschen Pfad eines Coding Agents - nenne die Datei- oder Modulgrenze, die er missverstehen koennte - nenne den Testbefehl, den er wahrscheinlich falsch oder gar nicht ausfuehrt - formuliere genau eine neue AGENTS.md-Zeile, die diesen Fehler verhindert haette ``` ## Beispiel 1: Der Agent testet zu breit Angenommen, ein Webapp-Repo hat langsame End-to-End-Tests und schnelle Unit-Tests. Ein Agent aendert eine kleine Parser-Funktion und startet danach die komplette Test-Suite. Nach zehn Minuten bricht der Lauf wegen eines flaky Browser-Tests ab. Der Agent interpretiert das als eigenes Problem und faengt an, an Playwright-Konfiguration herumzuschrauben. Das eigentliche Problem war nicht der Code. Es war fehlende Guidance. Schlechte `AGENTS.md`: ```md - Run tests before finishing. ``` Bessere `AGENTS.md` nach Probe: ```md - For parser-only changes under `src/lib/parser/`, run `npm test -- parser`. Do not run Playwright unless files under `src/routes/checkout/` or `tests/e2e/` changed. If an unrelated Playwright test fails, report it as unrelated instead of editing test config. ``` Das ist nicht laenger, weil jemand gern Regeln schreibt. Es ist praeziser, weil ein konkreter Fehler sichtbar wurde: Der Agent konnte lokale Verifikation und globale CI-Signale nicht unterscheiden. ## Beispiel 2: Der Agent repariert im falschen Layer Ein Backend hat drei Schichten: ```txt routes -> services -> repositories ``` Ein Bug: Die API gibt fuer geloeschte Accounts noch Status `active` zurueck. Der Agent findet den failing Endpoint-Test und patcht die Route direkt: ```ts if (account.deletedAt) { return { status: "deleted" }; } ``` Der Test wird gruen. Aber die gleiche Account-Logik wird in Jobs, Admin UI und Billing ebenfalls gebraucht. Der Fix gehoert in den Service, nicht in die Route. Schlechte `AGENTS.md`: ```md - Follow the existing architecture. ``` Bessere `AGENTS.md` nach Probe: ```md - Business state transitions for accounts belong in `src/accounts/account.service.ts`. Routes may validate input and shape HTTP responses, but must not duplicate account status rules. If an endpoint test fails because account state is wrong, inspect the service before patching the route. ``` "Follow the architecture" klingt gut, ist aber fuer einen Agenten oft nur Nebel. Eine getestete Guidance benennt die Stelle, an der der Fehler wirklich passiert. ## Beispiel 3: Der Agent editiert generierte Dateien Ein TypeScript-Projekt generiert API-Typen aus OpenAPI. Ein Agent sieht einen Type Error in `src/generated/api.ts`, editiert die Datei manuell und macht den Build gruen. Beim naechsten Codegen-Lauf ist der Fix weg. Wieder: kein Intelligenzproblem. Ein fehlendes Betriebshandbuch-Problem. Schlechte `AGENTS.md`: ```md - Do not edit generated files. ``` Bessere `AGENTS.md` nach Probe: ```md - Never edit files under `src/generated/`. API types are generated from `openapi/schema.yaml` via `npm run codegen`. If a type in `src/generated/api.ts` looks wrong, patch the schema or mapper, then run `npm run codegen`. ``` Die gute Regel nennt nicht nur das Verbot. Sie nennt den erlaubten Pfad. ## Was in eine gute AGENTS.md gehoert Eine gute Agenten-Anweisung ist nicht alles, was ein Mensch ueber das Repo weiss. Sie ist das Wissen, das einen Agenten von falschen, teuren oder schwer reviewbaren Wegen abhaelt. Der Unterschied ist hart: ```txt Schwach: "Be careful with migrations." Gut: "For Prisma migrations, never edit an applied migration. Create a new migration with `npm run db:migrate:create`, then run `npm run db:test-reset`." ``` ```txt Schwach: "Use existing patterns." Gut: "New billing rules go in `billingRules.ts`; UI components may display derived billing state but must not compute eligibility." ``` ```txt Schwach: "Run the relevant tests." Gut: "For changes under `packages/search`, run `pnpm --filter search test` and `pnpm --filter web test search-panel`." ``` ## Wo der Ansatz kippt Probe-and-Refine kann auch schlechte Anweisungen produzieren. Wenn deine synthetischen Issues unrealistisch sind, optimierst du die `AGENTS.md` auf Theater. Wenn das Diagnosemodell schwach ist, erfindet es Failure Modes, die im Repo gar nicht relevant sind. Wenn du jede einzelne Probe in eine neue Regel verwandelst, entsteht ein Dokument, das zwar lang ist, aber niemandem mehr Orientierung gibt. ## Die eigentliche Lehre Der spannende Teil des Papers ist nicht: "`AGENTS.md` funktioniert." Die bessere Lehre ist: ```txt Repo-Guidance wird wertvoll, wenn sie aus Fehlern entsteht. ``` Das passt zu allem, was bei produktiven Coding Agents gerade wichtig wird. Wir bewegen uns weg von Prompt-Folklore und hin zu kleinen Betriebssystemen um Agenten herum: Repo-Regeln, Evals, Tool-Grenzen, Verifikationsbefehle, Review-Evidenz. Eine gute `AGENTS.md` ist dabei kein langer Wunschzettel. Sie ist ein komprimiertes Fehlergedaechtnis des Repos. Wenn ein Agent dreimal in die falsche Datei laeuft, ist das nicht nur ein schlechter Run. Es ist ein Testfall fuer deine Anleitung. ## Mini-Workflow fuer dein Repo Wenn du heute anfangen willst, mach es klein: 1. Nimm deine aktuelle `AGENTS.md`. 2. Erzeuge fuenf synthetische Issues fuer typische Repo-Fallen. 3. Lass pro Issue diagnostizieren, wo ein Agent falsch abbiegen wuerde. 4. Schreibe pro echtem Failure Mode eine konkrete neue Regel. 5. Fuehre denselben Probe-Lauf erneut aus. 6. Behalte nur Regeln, die Fehlverhalten wirklich reduzieren. Das Ergebnis muss nicht perfekt sein. Es muss nur besser sein als "bitte sei vorsichtig". Der Satz, den ich mir merken wuerde: ```txt Dein Coding Agent braucht keinen laengeren Prompt. Er braucht Tests fuer seine Anleitung. ``` ## Quellen - [Probe-and-Refine Tuning of Repository Guidance for Coding Agents](https://arxiv.org/abs/2606.20512) - [arXiv HTML: Probe-and-Refine Tuning of Repository Guidance for Coding Agents](https://arxiv.org/html/2606.20512) - Private Huecki radar artifact: `content-research/radar/2026-06-22.md` ## FAQ ### Was ist Probe-and-Refine Tuning? Ein Workflow, bei dem synthetische Bugfix-Aufgaben genutzt werden, um fehlende oder falsche Repo-Anweisungen zu finden. Danach wird die AGENTS.md gezielt gepatcht und erneut getestet. ### Warum reicht eine statische AGENTS.md nicht? Weil viele wichtige Informationen erst sichtbar werden, wenn ein Agent an echten oder synthetischen Aufgaben scheitert: falsche Testbefehle, falsche Modulgrenzen, versteckte Konventionen oder historische Failure Modes. ### Braucht man dafuer ein grosses Eval-System? Nein. Fuer kleine Teams reichen am Anfang 5 bis 10 synthetische Issues, ein Review der Agenten-Fehler und konkrete neue Zeilen in der AGENTS.md.