Wie man effektive Spezifikationen für AI-Agenten schreibt – Addy Osmani

• Der größte Hebel für die Produktivität von AI-Agenten → eine klare und strukturierte SPEC
• Schlechte SPEC = Unklarheit → AI-Drift, wiederholte Fehlschläge, Überschreiten des Kontexts
• Gute SPEC = lebendes Dokument (SPEC.md) + kontinuierliche Updates

Kernbestandteile einer guten SPEC

• Ziel / Vision (warum es gebaut wird, für wen)
• Funktionsliste + Prioritäten
• Tech-Stack (konkret, z. B. React 18 + TS, Node 20)
• Ausführungsbefehle (npm test, lint, build usw.)
• Testkriterien (welche Tests erfolgreich laufen müssen)
• Codestruktur / Styleguide
• Git-Workflow (Branch-Regeln, Commit-Messages)
• Klare Grenzen (✅ immer / ⚠️ nachfragen / 🚫 niemals tun)

Effektive Muster für den Start-Prompt

• „Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan“
• Zuerst Plan Mode → die AI einen SPEC-Entwurf erstellen lassen
• Danach Anweisungen in kleine Arbeitseinheiten aufteilen

Praxistipps (nur das Wesentliche)

• SPEC.md als separate Datei pflegen → pro Aufgabe nur die relevanten Abschnitte einfügen
• Modularisieren + Unteraufgaben trennen
• Nach jeder Aufgabe automatische Tests + Prüfung auf SPEC-Konformität
• Die dreistufigen Grenzregeln klar definieren (Always / Ask / Never)