Ein guter Prompt für einen KI-Coding-Agenten sagt vier Dinge: was du willst, wo er anfangen soll, was sich nicht ändern darf und woran man erkennt, dass es funktioniert. Die meisten schlechten Ergebnisse entstehen, weil einer dieser Punkte fehlt, nicht wegen falscher Formulierungen. Der Agent kann deinen Code lesen, Befehle ausführen und Dateien bearbeiten; die Aufgabe des Prompts ist also, diese Arbeit in die richtige Richtung zu lenken und ihr eine Ziellinie zu geben.
Diese Anleitung stellt schlechte und gute Prompts nebeneinander und behandelt dann Kontext, Pläne, das Aufteilen von Arbeit, Prüfung und den Ort für Prompts, die du wiederverwendest. Die Beispiele nutzen Claude Code und Codex CLI, die Gewohnheiten gelten aber genauso für Gemini CLI und jeden anderen Coding-Agenten.
Warum ein Agent anders gepromptet wird als ein Chatbot
Ein Chatbot hat nur deine Nachricht. Ein Coding-Agent hat dein ganzes Repository, eine Shell und eine Schleife: Er liest Dateien, macht eine Änderung, führt etwas aus, schaut sich das Ergebnis an und versucht es erneut. Das ändert, was ein Prompt leisten muss:
- Du musst keinen Code einfügen. Verweise auf Dateien und lass den Agenten sie lesen.
- Du musst Grenzen setzen. Ein Agent, der alles bearbeiten darf, bearbeitet vielleicht Dinge, die du nicht gemeint hast.
- Du brauchst eine Abbruchregel. Ohne sie entscheidet der Agent selbst, wann die Arbeit gut genug ist, und seine Messlatte ist vielleicht nicht deine.
Jede zusätzliche Datei, die der Agent liest, füllt außerdem sein Kontextfenster. Ein fokussierter Prompt hält den Agenten fokussiert und die Session günstiger.
Schlechter Prompt vs. guter Prompt
So sieht ein typischer erster Versuch aus:
fix the login bugDer Agent muss raten, welcher Bug gemeint ist, wo er steckt und was „behoben“ bedeutet. Vielleicht ändert er die falsche Datei, schreibt eine Funktion um, die in Ordnung war, oder „behebt“ das Symptom, indem er den Fehler abfängt.
Hier dieselbe Anfrage, geschrieben für einen Agenten:
Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.
Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.
Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.Er ist länger, aber jede Zeile erspart dem Agenten eine Vermutung. Das leistet jeder Teil:
| Teil | Beispiel | Warum es hilft |
|---|---|---|
| Symptom | „gibt trotz richtigem Passwort 401 zurück“ | Der Agent weiß, was er reproduzieren soll |
| Ursache, falls bekannt | „speichert E-Mails so, wie sie eingegeben wurden“ | Erspart eine lange Suche |
| Einstiegsdateien | src/auth/login.ts | Weniger Lesen, weniger falsche Vermutungen |
| Grenzen | „ändere das Datenbankschema nicht“ | Hält die Änderung klein und sicher |
| Fertig-Kriterien | ein benannter Test plus pnpm test | Eine Ziellinie, die der Agent prüfen kann |
Die Ursache kennst du nicht immer. Das ist in Ordnung: Sag es und bitte den Agenten, sie zu finden, bevor er etwas behebt. „Finde heraus, warum X passiert, und erkläre es, bevor du etwas änderst“ ist für sich schon ein starker Prompt.
Gib Kontext, keine Aufsätze
Der nützlichste Kontext ist konkret und überprüfbar. Grob nach Wert geordnet:
- Dateipfade und Symbole.
src/billing/invoice.ts,calculateTax(). In Claude Code und Codex tippst du@, um eine Datei auszuwählen und anzuhängen. - Fehlerausgabe. Füge den genauen Stacktrace oder die Ausgabe des fehlschlagenden Tests ein, keine Zusammenfassung davon.
- Grenzen. Bibliotheken, die du nutzt oder nicht nutzt, Ordner, die unangetastet bleiben, APIs, die abwärtskompatibel bleiben müssen.
- Beispiele in der Codebasis. „Folge dem Muster in
src/routes/users.ts“ schlägt einen Absatz, der das Muster beschreibt. - Das Warum. Ein Satz zum Ziel aus Nutzersicht hilft dem Agenten, sinnvolle Entscheidungen zu treffen, die du nicht ausformuliert hast.
Was du weglassen kannst: die lange Geschichte des Projekts, deine Meinung zu Code, der nichts mit der Aufgabe zu tun hat, und Anweisungen, die für jede Aufgabe gelten. Letztere gehören in eine Projektdatei, mehr dazu unten.
Bei UI-Arbeit helfen Screenshots. Claude Code und Codex nehmen beide Bilder an; Codex akzeptiert auf der Kommandozeile außerdem codex --image path/to/file.png.
Zuerst einen Plan anfordern
Bei allem, was über einen kleinen Fix hinausgeht, trennst du Denken und Umsetzen. Bitte den Agenten, den Code zu lesen und einen Plan vorzuschlagen, prüfe ihn und lass ihn dann umsetzen.
- Claude Code: Drücke Shift+Tab, bis die Statusleiste den Plan-Modus zeigt, tippe
/planvor einen einzelnen Prompt oder starte mitclaude --permission-mode plan. Im Plan-Modus liest Claude und macht Vorschläge, bearbeitet aber nichts. Details stehen in Claude Code Plan-Modus. - Codex CLI:
/planlässt Codex planen, bevor es umsetzt. Du kannst auch eine Session nur mit Leserechten starten, indem du/permissionsauf Read Only stellst. - Jeder Agent: Sag es in Worten: „Bearbeite noch nichts. Lies die relevanten Dateien und gib mir einen nummerierten Plan mit den Dateien, die du ändern wirst.“
Ein Planungs-Prompt, der gut funktioniert:
We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.Den Plan zu lesen dauert eine Minute und fängt die teuren Fehler ab: den falschen Ordner, eine neue Abhängigkeit, die du nicht willst, eine Migration, mit der du nicht gerechnet hast. Ist der Plan falsch, korrigierst du ihn in einfachen Worten („nutze den vorhandenen Helper toRows() statt eines neuen Parsers“) und bittest um einen überarbeiteten Plan.
Große Aufgaben in Schritte teilen
Agenten arbeiten am besten an Aufgaben, die du in einem Durchgang prüfen kannst. Ein Prompt wie „baue das Abrechnungssystem“ erzeugt einen großen Diff, der schwer zu prüfen und schwer rückgängig zu machen ist. Teile ihn auf:
Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.Schritt 2 ist dann die API, Schritt 3 die UI, Schritt 4 die E-Mails. Nach jedem Schritt prüfst du, committest und startest den nächsten. Zwei Gewohnheiten sorgen dafür, dass das klappt:
- Zwischen den Schritten committen. Ein sauberer Commit ist ein Checkpoint. Geht Schritt 3 schief, setzt du auf das Ende von Schritt 2 zurück, statt einen gemischten Diff zu entwirren. Claude-Code-Änderungen rückgängig machen listet die Möglichkeiten auf.
- Frischer Kontext für fremde Arbeit. Nutze
/clearin Claude Code oder/newin Codex, wenn du das Thema wechselst. Alter Kontext kostet Tokens und zieht den Agenten zurück zur vorherigen Aufgabe.
Unabhängige Schritte können auch parallel laufen, jeder Agent in seinem eigenen Git-Worktree, damit sie sich nicht gegenseitig die Dateien überschreiben.
Sag dem Agenten, wie geprüft wird
„Mach, dass es läuft“ überlässt dem Agenten, was „läuft“ bedeutet. Eine Prüfanweisung holt diese Entscheidung zu dir zurück. Gute Prüfanweisungen sind Befehle mit eindeutigem Ergebnis:
Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.Ein paar Muster, die die Messlatte höher legen:
- Test zuerst. „Schreib einen Test, der den Bug reproduziert, führe ihn aus und zeig mir, dass er fehlschlägt. Dann korrigiere den Code, bis er besteht.“ So ist bewiesen, dass der Test den Bug wirklich abdeckt. Mehr dazu in Unit-Tests mit KI schreiben.
- Belege statt Behauptungen verlangen. „Füge die Ausgabe ein“ ist schwerer vorzutäuschen als „bestätige, dass es funktioniert“.
- Benennen, was nicht kaputtgehen darf. „Die bestehenden Tests in
tests/auth/müssen weiterhin bestehen.“ - Abkürzungen verbieten. „Überspringe oder lösche keine Tests und füge keine
any-Casts hinzu, um Typfehler zum Schweigen zu bringen.“ Agenten, die eine Prüfung unbedingt bestehen sollen, nehmen manchmal genau diese Wege.
Lies dann den Diff. Ein zweites Modell, das die Änderung reviewt, findet viel; siehe KI-Code-Review.
Prompts, die schiefgehen, und wie es besser geht
| Prompt | Was meistens passiert | Besser |
|---|---|---|
| „Räum diese Datei auf“ | Großes Umschreiben, umbenannte Funktionen, kaputte Imports an anderer Stelle | „Lagere das Parsen in parse.ts in eine eigene Funktion aus; die öffentliche API bleibt unverändert“ |
| „Füge Tests hinzu“ | Oberflächliche Tests, die bestätigen, dass der Code tut, was er tut | „Füge Tests für leere Eingabe, eine 10-MB-Datei und einen fehlerhaften Header hinzu; jeder muss fehlschlagen, wenn ich die Prüfung in Zeile 40 entferne“ |
| „Mach es schneller“ | Zufällige Mikrooptimierungen | „Der Endpoint /search braucht für 10k Zeilen 2 s. Profile ihn, sag mir, wo die Zeit verloren geht, und schlag dann einen Fix vor“ |
| „Halte dich an Best Practices“ | Was das Modell diesmal für das Beste hält | Benenne die Praxis: „nutze das Repository-Muster aus src/db/users.ts“ |
| Eine Liste mit zehn unabhängigen Fixes | Halb erledigt, Kontext bei Punkt sechs voll | Eine Aufgabe pro Prompt oder zehn Aufgaben in einer Warteschlange |
Prompts wiederverwendbar machen
Wenn du in jeder Session dieselbe Anweisung tippst, nimm sie aus deinen Prompts heraus.
Projektregeln: CLAUDE.md, AGENTS.md, GEMINI.md
Jeder Agent liest zu Beginn einer Session eine Projektdatei mit Anweisungen: CLAUDE.md für Claude Code, AGENTS.md für Codex (und mehrere andere Agenten), GEMINI.md für Gemini CLI. Schreib Befehle und Konventionen hinein, kurz und konkret:
## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck
## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.Jetzt ist „führe die Tests aus, bevor du sagst, dass du fertig bist“ Teil jedes Prompts, ohne dass du es tippst. /init erzeugt in Claude Code, Codex und Gemini CLI einen ersten Entwurf. CLAUDE.md und AGENTS.md erklärt, wie du einen Regelsatz für mehrere Agenten pflegst.
Wiederkehrende Abläufe: Skills und eigene Befehle
Für eine Aufgabe, die du ab und zu wiederholst, etwa ein Release, eine Migration oder eine Review-Checkliste, schreibst du einmal einen Skill oder eigenen Befehl und rufst ihn über seinen Namen auf.
Claude Code nutzt Skills: einen Ordner mit einer SKILL.md-Datei, in .claude/skills/<name>/ für das Projekt oder ~/.claude/skills/<name>/ für dich. Der Ordnername wird zum Befehl, und $ARGUMENTS erhält, was du danach tippst:
---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.Jetzt führt /fix-issue 123 den ganzen Prompt aus. Ältere Markdown-Dateien in .claude/commands/ funktionieren weiterhin genauso, aber die Dokumentation von Anthropic empfiehlt für Neues Skills, weil ein Skill-Ordner auch Skripte und Referenzdateien enthalten kann. Claude lädt einen Skill außerdem von selbst, wenn deine Anfrage zu seiner Beschreibung passt. Mehr in Claude Code Skills.
Codex liest Skills aus .agents/skills im Projekt und ~/.codex/skills für dich, im selben SKILL.md-Format.
Gemini CLI nutzt eigene TOML-Befehle in .gemini/commands/ (Projekt) oder ~/.gemini/commands/ (Benutzer). {{args}} wird durch das ersetzt, was du nach dem Befehl tippst, und Unterordner werden zu Namensräumen, git/commit.toml ist also /git:commit:
description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""Eine gute Faustregel: Regeln, die immer gelten, gehören in die Projektdatei, Abläufe, die du manchmal brauchst, in Skills, und der Prompt selbst trägt nur, was für die heutige Aufgabe spezifisch ist.
Eine Prompt-Vorlage zum Kopieren
Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>Nicht jede Zeile ist jedes Mal nötig. Für einen Tippfehler reicht „Goal“. Für ein neues Feature füllst du alle aus.
Agenten in AgentVera prompten
AgentVera ist eine Desktop-App für macOS, Windows und Linux, die Claude Code, Codex, Gemini CLI und andere CLI-Agenten in echten Terminals nebeneinander ausführt. Die Prompts bleiben dieselben; einige Funktionen übernehmen die wiederkehrenden Teile:
- Verify: Die Fertig-Kriterien, die du in deine Nachricht schreibst, werden als Abnahmekriterien herausgezogen. Wenn der Agent seinen Turn beendet, liest ein separater Prüfer den Diff, führt die erlaubten Testbefehle aus und markiert jedes Kriterium mit Belegen als bestanden oder fehlgeschlagen. Er kann keine Dateien bearbeiten. Verify gehört zu den Tarifen Pro und Team.
- Code-Review: Wenn ein Turn endet, reviewt ein zweites Claude-Modell, was der Agent geschrieben hat, und die Befunde können direkt an den Agenten zurückgehen.
- Send to agent: Schick einen Terminalfehler, einen Diff, ein Log oder eine Codezeile mit ⌘⇧L an einen Agenten, statt sie in deinen Prompt zu kopieren.
- Skill-Galerie: Skills für Claude Code und Codex in einer Liste erstellen, bearbeiten und ein- oder ausschalten und geteilte Skills nach einem Sicherheitsscan installieren.
- Workspace: ein Raster von Agenten pro Projekt, sodass du jedem aufgeteilten Schritt einen eigenen Agenten und Worktree geben kannst.
Lade AgentVera herunter und probiere deinen nächsten Prompt damit aus.
Fazit
Schreib Prompts wie ein Ticket für eine fähige Kollegin, die gerade neu im Team ist: das Ziel, wo sie suchen soll, was sie in Ruhe lassen soll und wie du das Ergebnis beurteilst. Fordere einen Plan an, wenn die Aufgabe groß ist, teile sie in prüfbare Schritte und gib immer einen Befehl mit, der beweist, dass sie erledigt ist. Was du wiederholst, verschiebst du in CLAUDE.md, AGENTS.md oder einen Skill. Dieselben Gewohnheiten zählen noch mehr, wenn der Agent eine Datenbank anfasst; SQL und Migrationen mit KI schreiben wendet sie auf Schemas und Migrationen an.