Anthropic warnt: Vager Auftrag 'Fix the Login Bug' ist ein schlechtes Beispiel
Anthropic fuehrt den kurzen Auftrag 'Fix the Login Bug' als Negativbeispiel fuer schlechtes Agent-Prompting an. Statt dessen empfiehlt sich ein strukturiertes Briefing mit sechs Feldern fuer praezisere Ergebnisse.
Öffnet man die Best-Practices-Seite von Claude Code und schaut auf die Tabelle unter "Provide specific context in your prompts", findet man in der letzten Zeile eine Spalte "Before". Dort steht als Prompt "fix the login bug".
Das "After" ist länger: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it". Es nennt das Symptom, wo man suchen soll und wie das Ergebnis nach einer Lösung aussieht.
Du hast die "Before"-Version getippt. Alle anderen auch. Der Agent wählt seinen eigenen Umfang und entscheidet selbst, wann er fertig ist. Zurück kommt ein Diff, das du erst einmal rückwärts entziffern musst, und ob es mergebar ist, hängt von Entscheidungen ab, die du nie gesehen hast.
Die Lösung ist ein kurzes Briefing mit sechs Feldern. Jedes davon schließt eine Lücke, die der Agent sonst durch Raten füllen würde.
Die Hersteller dieser Agenten sagen genau dasselbe in ihren eigenen Dokumentationen.
Anthropics Anleitung empfiehlt, "reference specific files, mention constraints, and point to example patterns" zu beachten. Sie beschreibt die nützlichsten Specs außerdem als solche, die "name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step".
OpenAIs Codex Prompting Guide sagt, ein nützlicher Prompt "names the behavior you want, points to the relevant code or reproduction steps, preserves important constraints, and says how to verify the change".
GitHubs Guidance für den Copilot Coding Agent listet, was eine ideale Aufgabe enthält: eine klare Beschreibung des Problems, "complete acceptance criteria on what a good solution looks like" und "directions about which files need to be changed".
Stellt man diese Angaben nebeneinander, ergeben sich die sechs Felder. Die Reihenfolge ist dabei weniger wichtig als deren vollständige Abdeckung.
Eine Zeile lässt sechs Entscheidungen beim Agenten. Sechs Felder geben sie an dich zurück.
Das laufende Beispiel ist der Login-Bug aus Anthropics Tabelle, in einem TypeScript-Repository.
Gut: Nutzer, deren Session abgelaufen ist, erhalten beim erneuten Login einen 401. Nach der Fix kann sich ein Nutzer mit abgelaufener Session beim ersten Versuch anmelden.
Warum das Verhalten verändert: Der Agent braucht einen Endpunkt, den er erkennen kann. "Fix the bug" hat keinen. Ein Symptom plus eine Beschreibung des behobenen Zustands liefern genau das, was der Zeile "Describe the symptom" in Anthropics Tabelle entspricht.
Schlecht: nichts. Der Agent durchsucht das Repository und liest alles, was auf "login" passt.
Gut: Beginne in src/auth/session.ts und src/auth/refresh.ts. Lege den neuen Test in tests/auth/ ab.
Warum: Jede Datei, die der Agent liest, landet in seinem Context Window, und Anthropics Dokumentation sagt, dass die Performance "degrades as it fills". Der Verweis auf die richtigen Dateien spart dieses Budget für den Fix. Er sagt dem Agenten außerdem, wo du den Diff erwartest, sodass eine Änderung an anderer Stelle für beide auffällt.
Gut: Fasse die Login-UI, die Form der öffentlichen API, package.json oder die Lockfile nicht an. Formatiere keine Dateien um, die du nicht veränderst. Wenn der Fix scheinbar eines davon erfordert, stoppe und sag es mir.
Warum: Agenten reparieren alles, was ihnen unterwegs auffällt. Ein umbenannter Helper oder ein aufgeräumter Importblock macht aus einem Zwei-Dateien-Fix eine Prüfung des gesamten drumherum. Codex' eigenes Bug-Fix-Beispiel enthält die Zeile "Do not change the API shape". Die Zeile "stop and tell me" gibt dem Agenten einen legalen Ausweg, statt die Änderung stillschweigend auszuweiten.
Gut: Halte den Fix minimal. Schreibe zuerst einen fehlschlagenden Test, der den Timeout reproduziert, und behebe dann den Fehler. Keine neuen Dependencies. Folge dem bereits in src/auth/refresh.ts vorhandenen Refresh-Pattern.
Warum: Constraints bestimmen, wie der Agent ans Ziel kommt. "Keep the fix minimal and add a regression test if feasible" ist eine Zeile aus OpenAIs Beispiel-Prompt, und Anthropics Beispiele enthalten Formulierungen wie "avoid mocks" und "build from scratch without libraries other than the ones already used in the codebase". "Write good code" legt nichts fest, weil der Agent ohnehin davon überzeugt ist, genau das zu tun.
Gut: Fertig bedeutet, dass npm test -- tests/auth durchläuft und npm run lint mit Exit-Code 0 endet. Führe beides aus, bevor du mir sagst, dass du fertig bist.
Warum: In Anthropics Worten "stops Claude when the work looks done. Without a check it can run, 'looks done' is the only signal available, and you become the verification loop". Ein Befehl mit Bestehen oder Scheitern erlaubt es dem Agenten, selbst zu laufen, zu lesen und erneut zu versuchen. Wenn du nur ein Feld ergänzt, dann dieses.
Schlecht: nichts. Du erhältst einen fröhlichen Absatz, der behauptet, der Bug sei behoben.
Gut: Wenn du fertig bist, antworte mit: der Ursache in einem Satz, den geänderten Dateien, den ausgeführten Befehlen samt Ergebnissen und allem, was dir aufgefallen ist, aber unverändert geblieben ist.
Warum: Dieselbe Anthropic-Anleitung sagt, der Agent solle "show evidence rather than asserting success", weil "reviewing evidence is faster than re-running the verification yourself". OpenAis Formulierung lautet "Report the commands and results." Probleme, die der Agent außerhalb seines Umfangs entdeckt hat, kommen als Liste zurück, die du priorisieren kannst, und der Diff bleibt so groß wie angefragt.
Hier ist das Template. Behalte die Überschriften bei; der Agent liest sie als Struktur.
GOAL <was falsch ist und wie das behobene Ergebnis aussieht> IN SCOPE <zu lesende und ändernde Dateien oder Ordner> OUT OF SCOPE <was nicht anzufassen ist; bei Bedarf stoppen und nachfragen> CONSTRAINTS <zu befolgende Patterns, Dependencies, Test zuerst, Umfang> DONE WHEN <Befehle, die bestehen müssen, bevor du fertig meldest> REPORT BACK <was deine letzte Nachricht enthalten muss> Und hier der Login-Bug vollständig ausgeschrieben:
GOAL Nutzer, deren Session abgelaufen ist, erhalten beim erneuten Login einen 401. Nach der Fix kann sich ein Nutzer mit abgelaufener Session beim ersten Versuch anmelden. IN SCOPE src/auth/session.ts, src/auth/refresh.ts, neuer Test in tests/auth/.
OUT OF SCOPE Login-UI, Form der öffentlichen API, package.json, Lockfile. Kein Reformatting anderer Dateien. Wenn der Fix eines davon erfordert, stoppen und nachfragen.
CONSTRAINTS Minimaler Fix. Zuerst der fehlschlagende Test, dann die Behebung. Keine neuen Dependencies.
Folge dem Pattern in src/auth/refresh.ts. DONE WHEN npm test -- tests/auth läuft durch. npm run lint endet mit Exit-Code 0. REPORT BACK Ursache in einem Satz.
Geänderte Dateien. Ausgeführte Befehle samt Ergebnissen. Alles, was aufgefallen ist, aber unverändert geblieben ist.
Das meiste, was spezifisch für den Login-Bug ist, steckt im Goal und in den Pfaden. Die Out-of-Scope-Liste, der Stil der Constraints und die Report-Back-Zeilen lassen sich fast unverändert auf die nächste Aufgabe übertragen.
Ich baue Hermes IDE, bewerte diesen Abschnitt also entsprechend. Es ist eine kostenlose, quellverfügbare (BSL 1.1) Desktop-App für macOS, Windows und Linux, die Claude Code, Codex und andere CLI-Agenten nebeneinander laufen lässt, jeweils in einem eigenen Terminal. Sie steht in keiner Verbindung zu Anthropic, OpenAI oder Nous Research.
Drei Teile der App greifen das Briefing auf.
Das Briefing ist der erste Prompt. Drücke ⌘N (Ctrl+Shift+N unter Windows und Linux) und füge das Briefing als Aufgabe ein. Jede Aufgabe startet auf ihrem eigenen hermes/<name>-Branch in einem eigenen Worktree, "with the task as the agent's first prompt" (README). Die sechs Felder werden unverändert übernommen, und das New-Task-Sheet zeigt unter "Hermes will run" vorab den Befehl. Es gibt keine zweite Nachricht, in der du an vergessene Constraints denken musst.
Das ⌘N New-Task-Sheet (mit einer anderen Aufgabe gezeigt): Claude Code, ein neuer hermes/-Worktree, Accept Edits und die Vorschau "Hermes will run" des Befehls.
Speichere das Briefing und verwende es wieder. Prompts öffnet sich mit ⌘J (Ctrl+Shift+M unter Windows und Linux). Dort liegen deine eigenen Prompts neben der kostenlosen Hodios-Bibliothek: eine auswählen, die Lücken ausfüllen und in die Session oder eine neue Aufgabe legen (README). Eine Prompts-Datei lässt sich auch importieren (v2.2.7 Release Notes). So bleibt das obige Template mit deiner üblichen Out-of-Scope-Liste und den Report-Back-Zeilen in Prompts. Beim nächsten Mal mit ⌘J öffnen, nur Goal und Dateien anpassen und an eine neue Aufgabe senden.
Der Fertig-Check kann zu einem Hermes Check werden. In Hermes können eigene Checks "decide when a task is done" (README), sodass die Befehle in DONE WHEN entscheiden können, statt im Prompt als Bitte zu stehen. Wie man Checks pro Repository einrichtet, steht in der Worktree-Rezept-Dokumentation. Behalte das DONE WHEN Feld trotzdem im Briefing: Es zeigt dem Agenten ab dem ersten Zug, welche Befehle zählen.
Schreibe das Briefing einmal, fülle die zwei Felder aus, die sich ändern, und sende es an den Agenten, der die Aufgabe übernimmt.
Ein Briefing ist eine Anfrage. Die Dokumentation von Anthropic zieht die Grenze zwischen Anweisungen in CLAUDE.md, die als beratend bezeichnet werden, und Hooks, die als deterministisch beschrieben werden und die Ausfuehrung der Aktion garantieren (Quelle). Dasselbe gilt fuer dein OUT OF SCOPE Feld. Nichts hindert einen Agenten daran, es zu ueberschreiten, also ueberpruefst du das.
Zwei guenstige Checks, sobald der Agent zurueckmeldet:
# Welche Dateien wurden vom Branch geaendert? git diff --stat main...HEAD # Hat sich die Lockfile veraendert? git diff --name-only main...HEAD -- package-lock.json Enter fullscreen mode Exit fullscreen mode Fuehre den Agenten in einem eigenen Branch oder Worktree aus, damit eine Scope-Abweichung auf diesem Branch bleibt. Fuer den Done-Check kann der Stop-Hook von Claude Code selbst verhindern, dass ein Durchlauf endet, bis dein Skript erfolgreich ist, mit oder ohne Hermes.
Noch zwei Einschraenkungen. Erstens gehoeren Zeilen, die in jedem Briefing identisch sind (dein Test-Runner, dein Lint-Befehl, deine Stilregeln) in CLAUDE.md (Claude Code) oder AGENTS.md (Codex), die dein Agent in jeder Sitzung liest. Das Briefing ist fuer das, was sich pro Aufgabe veraendert. Zweitens benoetigt nicht jede Aufgabe sechs Felder. Der Leitfaden von Anthropic sagt, dass man den Plan weglassen kann, wenn man den Diff in einem Satz beschreiben koennte. Eine Tippfehlerkorrektur ist ein Satz. Ein Login-Bug, der zwei Dateien und einen Test betrifft, ist es nicht.
Die sechs Felder sind Prompting, angewendet auf einen Coding-Agent: ein klares Ziel, enge Grenzen und eine feste Form fuer die Antwort. Wenn du dieselben Gewohnheiten nutzen moechtest, wenn du ein Modell aus deinem eigenen TypeScript-Code aufrufst, fuehrt AI That Answers durch eine erste LLM-App in TypeScript: das Schreiben der Prompts, das Erhalten strukturierter Ausgaben statt eines fröhlichen Absatzes und die Kontrolle der Token-Kosten. Wenn du das Briefing in Prompts (⌘J) gespeichert haben moechtest und deine eigenen Checks entscheiden sollen, wann die Aufgabe erledigt ist, ist Hermes IDE ein kostenloser Download, und der Code liegt auf GitHub.
Es ist Buch 1 von AI in TypeScript, fuenf Buecher, die von deinem ersten LLM-Aufruf bis zu Agenten in der Produktion fuehren: die gesamte Serie findest du hier.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
Open the Claude Code best practices page and look at the table under "Provide specific context in your prompts". The last row has a "Before" column. The prompt in it is "fix the login bug".
The "After" is longer: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it". It names the symptom, where to look and what fixed looks like.
You have typed the "Before" version. Everyone has. The agent picks its own scope and decides on its own when it is finished. You get back a diff you now have to reverse-engineer, and whether it is mergeable depends on guesses you never saw it make.
The fix is a short brief with six fields. Each one closes a gap the agent would otherwise fill by guessing.
The vendors who build these agents say the same thing in their own docs.
Anthropic's guide says to "reference specific files, mention constraints, and point to example patterns." It also describes the most useful specs as ones that "name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step" ( source ).
OpenAI's Codex prompting guide says a useful prompt "names the behavior you want, points to the relevant code or reproduction steps, preserves important constraints, and says how to verify the change."
GitHub's guidance for the Copilot coding agent lists what an ideal task includes: a clear description of the problem, "complete acceptance criteria on what a good solution looks like", and "directions about which files need to be changed."
Put those side by side and you get the six fields. The order matters less than having all of them.
One line leaves six decisions to the agent. Six fields hand them back to you.
The running example is the login bug from Anthropic's table, in a TypeScript repo.
Good: Users whose session timed out get a 401 when they log in again. After the fix, a timed-out user can log in on the first try.
Why it changes behaviour: the agent needs a stopping point it can recognise. "Fix the bug" has none. A symptom plus what fixed looks like gives it one, which is exactly the "Describe the symptom" row in Anthropic's table.
Bad: nothing. The agent greps the repo and reads whatever matches "login".
Good: Start in src/auth/session.ts and src/auth/refresh.ts. Put the new test in tests/auth/.
Why: every file the agent reads lands in its context window, and Anthropic's docs say performance "degrades as it fills" ( source ). Pointing at the right files saves that budget for the fix. It also tells the agent where you expect the diff to be, so a change somewhere else stands out to both of you.
Good: Don't touch the login UI, the public API shape, package.json or the lockfile. Don't reformat files you aren't changing. If the fix seems to need any of these, stop and tell me.
Why: agents fix things they notice on the way. A renamed helper or a tidied import block turns a two-file fix into a review of everything around it. Codex's own bug-fix example carries the line "Do not change the API shape" ( source ). The "stop and tell me" line gives the agent a legal move other than quietly widening the change.
Good: Keep the fix minimal. Write a failing test that reproduces the timeout first, then fix it. No new dependencies. Follow the refresh pattern already in src/auth/refresh.ts.
Why: constraints decide how the agent gets there. "Keep the fix minimal and add a regression test if feasible" is a line from OpenAI's example prompt, and Anthropic's examples say things like "avoid mocks" and "build from scratch without libraries other than the ones already used in the codebase." "Write good code" constrains nothing, because the agent already believes it does that.
Good: Done means npm test -- tests/auth passes and npm run lint exits 0. Run both before you tell me you are done.
Why: in Anthropic's words, "Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available, and you become the verification loop" ( source ). A command with a pass or fail result lets the agent run, read and retry on its own. If you only add one field, add this one.
Bad: nothing. You get a cheerful paragraph saying the bug is fixed.
Good: When done, reply with: the root cause in one sentence, the files you changed, the commands you ran with their results, and anything you noticed but did not change.
Why: the same Anthropic guide says to have the agent "show evidence rather than asserting success", because "reviewing evidence is faster than re-running the verification yourself." OpenAI's version is "Report the commands and results." Problems the agent spotted outside its scope come back as a list you can triage, and the diff stays the size you asked for.
Here is the template. Keep the headings; the agent reads them as structure.
GOAL <what is wrong, and what fixed looks like> IN SCOPE <files or folders to read and change> OUT OF SCOPE <what not to touch; stop and ask if needed> CONSTRAINTS <patterns to follow, deps, test-first, size> DONE WHEN <commands that must pass before you say done> REPORT BACK <what your final message must contain> Enter fullscreen mode Exit fullscreen mode And the login bug, written out:
GOAL Users whose session timed out get a 401 when they log in again. After the fix, a timed-out user logs in on the first try. IN SCOPE src/auth/session.ts, src/auth/refresh.ts, new test in tests/auth/.
OUT OF SCOPE Login UI, public API shape, package.json, lockfile. No reformatting of other files. If the fix needs any of these, stop and ask.
CONSTRAINTS Minimal fix. Failing test first, then the fix. No new dependencies.
Follow the pattern in src/auth/refresh.ts. DONE WHEN npm test -- tests/auth passes. npm run lint exits 0. REPORT BACK Root cause in one sentence.
Files changed. Commands run and their results. Anything you noticed but did not change.
Enter fullscreen mode Exit fullscreen mode Most of what is specific to the login bug sits in the goal and the paths. The out-of-scope list, the constraints style and the report-back lines carry over to the next task almost unchanged.
I build Hermes IDE, so weigh this section with that in mind. It is a free, source-available (BSL 1.1) desktop app for macOS, Windows and Linux that runs Claude Code, Codex and other CLI agents side by side, each in its own terminal. It is not affiliated with Anthropic, OpenAI or Nous Research.
Three parts of it line up with the brief.
The brief is the first prompt. Press ⌘N (Ctrl+Shift+N on Windows and Linux) and paste the brief in as the task. Each task starts on its own hermes/<name> branch in its own worktree, "with the task as the agent's first prompt" ( README ). The six fields go in as written, and the New task sheet previews the command under "Hermes will run" before you start it. There is no second message where you remember the constraints you forgot.
The ⌘N New task sheet (shown with a different task): Claude Code, a new hermes/ worktree, Accept edits, and the "Hermes will run" preview of the command.
Save the brief and reuse it. Prompts opens with ⌘J (Ctrl+Shift+M on Windows and Linux). It holds your own prompts next to the free Hodios library: pick one, fill in the blanks, and put it in the session or a new task ( README ). A prompts file can also be imported ( v2.2.7 release notes ). So the template above, with your usual out-of-scope list and report-back lines already in it, stays in Prompts. Next time, open it with ⌘J, rewrite only the goal and the files, and send it to a new task.
The done-check can become a Hermes check. In Hermes, your own checks "can decide when a task is done" ( README ), so the commands in DONE WHEN can do the deciding instead of sitting in the prompt as a request. How to set checks per repository is in the worktree recipe docs. Keep the DONE WHEN field in the brief anyway: it tells the agent which commands matter from the first turn.
Write the brief once, fill in the two fields that change, send it to whichever agent gets the task.
A brief is a request. Anthropic's docs draw the line between instructions in CLAUDE.md, which are "advisory", and hooks, which are "deterministic and guarantee the action happens" ( source ). The same holds for your OUT OF SCOPE field. Nothing stops an agent from crossing it, so you check.
Two cheap checks once the agent reports back:
# which files did the branch touch? git diff --stat main...HEAD # did the lockfile change? git diff --name-only main...HEAD -- package-lock.json Enter fullscreen mode Exit fullscreen mode Run the agent on its own branch or worktree so a scope miss stays on that branch. For the done-check, Claude Code's own Stop hook can block a turn from ending until your script passes, with or without Hermes.
Two more limits. First, lines that are the same in every brief (your test runner, your lint command, your style rules) belong in CLAUDE.md (Claude Code) or AGENTS.md (Codex), which your agent reads every session. The brief is for what changes per task. Second, not every task needs six fields. Anthropic's guide says that if you "could describe the diff in one sentence", you can skip the plan. A typo fix is one sentence. A login bug that crosses two files and a test is not.
The six fields are prompting applied to a coding agent: a clear goal, tight limits and a fixed shape for the answer. If you want to use the same habits when you call a model from your own TypeScript code, AI That Answers walks through a first LLM app in TypeScript: writing the prompts, getting structured output back instead of a cheerful paragraph, and keeping an eye on token cost. If you want the brief saved in Prompts (⌘J) and your own checks deciding when the task is done, Hermes IDE is a free download, and the code is on GitHub.
It is book 1 of AI in TypeScript, five books that go from your first LLM call to agents in production: the whole series is here.