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

Das erste Prinzip empfiehlt, mit einer übergeordneten Vision zu beginnen, anstatt 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, explizite Projektstruktur, Codestil-Beispiele, Git-Workflow und klare Abgrenzungen. Osmani schlägt ein dreistufiges Regelsystem vor: „Always do“ (unbedenkliche Aktionen), „Ask first“ (Änderungen mit hoher Auswirkung), „Never do“ (harte Stopps wie das Committen von Secrets).

Das dritte Prinzip unterteilt die Arbeit in modulare Aufgaben. Untersuchungen zeigen einen „Fluch der Anweisungen“ (curse of instructions), bei dem zu viele gleichzeitige Vorgaben die Befolgungsrate des Modells erheblich verringern. 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 überprüfen. YAML-Konformitätstests dienen als sprachunabhängige Verträge. Fachwissen 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 dominante Fehlermodus), das Überspringen des menschlichen Reviews, weil Tests bestehen, sowie die Verwechslung von schnellem „vibe coding“ mit Produktionsengineering. Er identifiziert eine „tödliche Trias“ (lethal trifecta): Geschwindigkeit (schwer zu überprüfen), Nicht-Determinismus (inkonsistente Ausgaben) und Kosten (begünstigt 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.