Addy Osmani veröffentlicht einen umfassenden Leitfaden zum Verfassen effektiver Spezifikationen für KI-Coding-Agenten und behandelt dabei das Kernproblem, dass umfangreiche Spezifikationen eine Kontextüberlastung verursachen und die Modellleistung verschlechtern.

Das erste Prinzip plädiert dafür, mit einer übergeordneten Vision zu beginnen, statt von Anfang an zu überkonstruieren. Die Nutzung des Plan Mode (Shift+Tab in Claude Code) ermöglicht eine schreibgeschützte Exploration vor der Codegenerierung. Der Agent arbeitet die Details anschließend in einer persistenten SPEC.md-Datei aus, um Konsistenz über mehrere Sitzungen hinweg zu gewährleisten.

Das zweite Prinzip strukturiert Spezifikationen als professionelle PRDs, die sechs wesentliche Bereiche abdecken: ausführbare Befehle mit Flags, Testverfahren, eine explizite Projektstruktur, Codestil-Beispiele, den Git-Workflow und klare Grenzen. Osmani schlägt ein dreistufiges Regelsystem vor: „Always do" (sichere Aktionen), „Ask first" (Änderungen mit hoher Auswirkung) und „Never do" (harte Stopps, etwa das Committen von Geheimnissen).

Das dritte Prinzip unterteilt die Arbeit in modulare Aufgaben. Untersuchungen zeigen einen „Fluch der Anweisungen" auf: Zu viele gleichzeitige Anweisungen verringern die Regeltreue des Modells erheblich. Lösungsansätze umfassen getrennte Spezifikationsdateien (SPEC_backend.md, SPEC_frontend.md), spezialisierte Sub-Agenten und parallele Agenten für sich nicht überschneidende Arbeiten.

Das vierte Prinzip integriert Selbstverifikation. Das Muster „LLM-as-a-Judge" nutzt einen zweiten Agenten, um die Einhaltung von Stil und Architektur zu prüfen. YAML-Konformitätstests dienen als sprachunabhängige Verträge. Fachwissen aus der Domäne muss explizit einbezogen werden: Präferenzen, bibliotheksspezifische Fallstricke, erwartete Formate.

Das fünfte Prinzip behandelt Spezifikationen als lebende Dokumente, die zusammen mit dem Code versioniert werden. Der kontinuierliche Zyklus testet nach jedem Meilenstein, speist Fehlschläge in den nächsten Prompt zurück und aktualisiert das Dokument, wenn sich Annahmen als unvollständig erweisen.

Osmani warnt vor gängigen Fallstricken: zu vage Spezifikationen (laut der GitHub-Studie der vorherrschende Fehlermodus), das Auslassen menschlicher Überprüfung, weil Tests bestehen, sowie die Verwechslung von schnellem „vibe coding" mit Produktionsentwicklung. Er identifiziert eine „tödliche Dreifaltigkeit": Geschwindigkeit (schwer zu überprüfen), Nichtdeterminismus (uneinheitliche Ausgaben) und Kosten (begünstigen Abkürzungen).

Die zentrale Metapher vergleicht KI-Agenten mit „kompetenten Praktikanten", die klare Anweisungen, relevanten Kontext und umsetzbares Feedback benötigen. Der Erfolg hängt davon ab, vollständige Spezifikationen mit fokussierten Kontextfenstern in Einklang zu bringen.