# Prompting: wie du AI-Agents präzise anweist

AI-Agents wie Claude Code, Cursor, Codex oder Antigravity sind brillante Junior-Entwickler mit Amnesie. Sie können alles, vergessen aber zwischen den Sessions, was sie gestern gemacht haben, und raten gerne, wenn du ihnen keinen Kontext gibst. Dein Job ist es, präzise zu briefen.

Schlechtes Prompting kostet dich heute mehrere Stunden, weil der Agent Dinge baut, die du nicht wolltest, in einem Stil, den du nicht magst, mit Libraries, die du nicht brauchst.

## Das Grund-Pattern: Rolle, Kontext, Aufgabe, Format

Jeder gute Prompt hat vier Teile.

**Rolle**: Wer ist der Agent gerade?
> "Du bist ein erfahrener Next.js 15 Entwickler, der Tailwind v4 und Server Components nutzt."

**Kontext**: Was muss er wissen?
> "Ich baue eine Buchungs-App für Cafés. Tech-Stack: Next.js 15 App Router, Tailwind v4, Postgres mit Prisma, Fastify Backend. Das Datenmodell ist Tisch und Reservierung (siehe schema.prisma)."

**Aufgabe**: Was soll er machen?
> "Baue die Seite /tische, die alle Tische in einer Tabelle anzeigt mit Spalten Nummer, Sitzplätze, Status. Klick auf eine Zeile öffnet /tische/[id]."

**Format**: Wie soll das Ergebnis aussehen?
> "Server Component, kein 'use client'. Nutze die globals.css-Klassen card und data-table. Keine externen UI-Libraries. Antworte mit dem fertigen File-Inhalt."

Wenn du alle vier Teile gibst, bekommst du in 90 Prozent der Fälle beim ersten Versuch ein brauchbares Ergebnis.

## Plan-Mode statt direkt bauen

Lass den Agent erst einen Plan schreiben, dann erst Code. Das spart dir Stunden Refactoring.

Schlecht:
> "Bau mir die Reservierungs-API."

Besser:
> "Plane die Reservierungs-API. Welche Endpoints? Welche Validierungen? Welche Edge-Cases? Erst Plan, kein Code. Dann warte auf mein OK."

Der Agent listet dir dann zum Beispiel:

1. POST /api/reservierungen, body validieren (tisch_id existiert, start_zeit in Zukunft, Tisch frei in Zeitraum)
2. GET /api/reservierungen?datum=YYYY-MM-DD
3. DELETE /api/reservierungen/:id

Jetzt kannst du sagen "Plan ok, aber lass DELETE weg, kein Storno im Prototyp" und sparst dir, dass er es baut und du es löschst.

## Kontext-Hygiene

Agents haben ein begrenztes Kontext-Fenster. Wenn du in einer langen Session bist und plötzlich der Agent vergisst, was er vor 20 Minuten gemacht hat, oder die Antworten langsam werden, ist es Zeit für einen Reset.

Pattern:
1. Bevor du resettest: lasse den Agent eine kurze Zusammenfassung schreiben ("Fasse zusammen was wir bisher gebaut haben und welche Files wichtig sind").
2. Speichere die Zusammenfassung in einer Datei wie `NOTES.md`.
3. Starte neue Session, gib `NOTES.md` als ersten Kontext mit.

Die meisten Tools haben einen `/clear`-Befehl oder einen "New Chat"-Button. Nutze ihn, wenn die Antworten anfangen, sich zu wiederholen oder zu halluzinieren.

## Token sparen

Token sind Geld und Zeit. Je mehr Kontext, desto langsamer und teurer.

Spar-Regeln:
- Schick nicht den ganzen Codebase mit, wenn nur eine Funktion relevant ist.
- Schick keine `node_modules` oder `.next` Ordner.
- Schick keine Prisma-Migrationsdateien mit, wenn nur das Schema relevant ist.
- Wenn der Agent ein File ändert, lass ihn nur die geänderten Teile zurückgeben, nicht das ganze File neu (außer es ist klein).
- Komprimiere lange Logs vor dem Pasten ("hier die relevanten Zeilen 240 bis 280: ...").

Konkretes Beispiel: statt "lies alle Files in /src" sag "lies src/lib/db.ts und src/app/api/reservierungen/route.ts".

## Anti-Patterns

| Schlecht | Besser |
|---|---|
| "Bau mir mal eine App." | "Bau die Page /tische als Server Component, Tabelle mit den Feldern X, Y, Z, Klick öffnet /tische/[id]." |
| "Mach das schöner." | "Erhöhe den Abstand zwischen den Cards auf 24px und nutze die accent-Farbe für den Primärbutton statt grau." |
| "Es funktioniert nicht." | "Wenn ich auf Speichern klicke, kommt Fehler 500. Log sagt: 'TypeError: Cannot read property id of undefined' in route.ts Zeile 42. Hier die Funktion: ..." |
| "Nutze die beste Library dafür." | "Nutze Recharts für Charts. Keine andere Library." |
| "Schreibe noch Tests dazu." | "Schreibe einen Vitest-Test für die Funktion calculatePrice, deckt Fälle: 0 Gäste, 1 Gast, 10 Gäste, negative Anzahl." |

Je vager der Prompt, desto kreativer der Agent. Kreativität willst du beim Design des Prototyps, nicht beim Bauen.

## Wiederverwendbare System-Prompts

Lege dir am Anfang des Projekts ein File `AGENTS.md` oder `CLAUDE.md` an mit deinen festen Regeln. Die meisten Tools lesen das automatisch.

Beispiel-Inhalt:

```markdown
# Projekt-Regeln für AI-Agents

## Stack
- Next.js 15 App Router, TypeScript strict
- Tailwind v4, eigene Komponenten in globals.css
- Prisma + Postgres, Migrationen via prisma migrate dev
- Fastify Backend, ESM, gebundelt mit tsup

## Stil
- Keine UI-Libraries (kein shadcn, MUI, Chakra)
- Keine Inline-Hex-Farben, nur CSS-Variablen aus globals.css
- Server Components als Default, "use client" nur wenn nötig
- Server Actions für Forms, kein /api/-Endpoint dafür

## Verbote
- Kein `npm install` ohne Rückfrage
- Kein Force-Push, kein git reset --hard
- Keine Migration löschen oder umbenennen
- Keine eingehenden Tests anpassen damit sie grün werden
```

Mit so einem File wendet der Agent deine Konventionen automatisch an, ohne dass du jedes Mal alles wiederholst.

## Beispiel-Prompt für deinen Workshop-Tag

Initial-Prompt nach `npm create next-app`:

> Du bist ein Senior Next.js Entwickler. Ich baue eine Buchungs-App für Cafés.
>
> Stack: Next.js 15 App Router, Tailwind v4, TypeScript strict, Prisma mit Postgres, später Fastify als Backend. Aktuell Single-Repo, kein Monorepo.
>
> Featureliste Prototyp:
> - Tabelle aller Tische auf /
> - Klick öffnet /tisch/[id] mit Reservierungen
> - Form auf /reservieren mit Tisch-Auswahl, Datum, Uhrzeit, Name, Email
> - Speichert in Postgres
>
> Datenmodell: Tisch (id, nummer, sitzplaetze), Reservierung (id, tischId, gastName, gastEmail, startZeit, dauerMinuten)
>
> Aufgabe jetzt: Plane die Schritte (Schema, Migration, Pages, Forms). Erst Plan, kein Code. Liste die Files mit Pfaden auf. Warte auf mein OK.

Danach gehst du Schritt für Schritt durch.

## Wenn der Agent halluziniert

Symptome: erfundene Library-Funktionen, falsche Imports, Endpoints die nicht existieren.

Gegenmittel:
1. Klein-Schritte: nur eine Funktion pro Prompt.
2. Beweise verlangen: "Zeige die Doku-Stelle für diese Funktion."
3. Tests laufen lassen und Fehler zurückgeben.
4. Bei wiederholter Halluzination: Session resetten, mit präziserem Kontext neu starten.
5. Modell wechseln: andere Modelle haben unterschiedliche Stärken.

## Nächster Schritt

Bevor du loslegst, schreibe deine erste Konversation. Ein `AGENTS.md`-File mit Stack und Verboten, dann den Initial-Prompt mit Featureliste. Erst dann startest du den Agent. Lies parallel webapp-techstack.md damit du weißt, welchen Stack du angibst.