# osmani-how-write-good-spec-ai-agents-2026-01-13

## Veille

Addy Osmani – Spezifikationen für KI-Agenten schreiben, 5 Prinzipien, Plan Mode, strukturiertes PRD, Modularität

## Titre Article

How to write a good spec for AI agents

## Date

2026-01-13

## URL

https://addyosmani.com/blog/good-spec/

## Keywords

Spezifikation, Spezifikationen, KI-Agenten, Claude Code, Plan Mode, PRD, Modularität, Kontextfenster, Sub-Agenten, Tests, vibe coding, Prompt Engineering, SPEC.md

## Authors

Addy Osmani

## Ton

Profil: Technischer Blogartikel, pädagogisches und präskriptives Register, Perspektive einer Engineering-Führungskraft (Google Chrome).
Stil: Gegliedert in 5 nummerierte Prinzipien mit detaillierten Unterabschnitten. Verwendet konkrete Codebeispiele und Vergleichstabellen. Balanciert Theorie und Praxis. Verweist auf GitHub-Studien (über 2.500 analysierte Agenten). Warnungen vor häufigen Fallstricken. Zielgruppe: Entwickler, die KI-Coding-Agenten einsetzen, Tech Leads, Architekten.

## Pense-betes

- **Kernproblem**: Umfangreiche Spezifikationen verursachen Kontextüberlastung und verschlechterte Modellleistung
- **5 Prinzipien** für effektive Spezifikationen: 1. **Übergeordnete Vision zuerst**: prägnantes Briefing, die KI arbeitet die Details aus 2. **Professionelle PRD-Struktur**: 6 wesentliche Bereiche 3. **Modulare Aufteilung**: monolithische Prompts vermeiden 4. **Eingebaute Selbstverifikation**: Regeln und Fachwissen 5. **Testen, iterieren, weiterentwickeln**: Spezifikationen als lebende Dokumente
- **Plan Mode** (Shift+Tab Claude Code): schreibgeschützte Exploration vor der Codegenerierung
- **SPEC.md**: persistente Datei für Konsistenz über mehrere Sitzungen hinweg
- **6 PRD-Bereiche**: Befehle, Tests, Projektstruktur, Codestil, Git-Workflow, Grenzen
- **Dreistufiges System**: ✅ Always do, ⚠️ Ask first, 🚫 Never do
- **„Fluch der Anweisungen"**: verschlechterte KI-Leistung bei zu vielen gleichzeitigen Anweisungen
- **Lösung für Modularität**: getrennte SPEC_backend.md, SPEC_frontend.md
- **Sub-Agenten/Skills**: domänenspezialisierte Agenten
- **LLM-as-a-Judge**: Überprüfung von Stil/Architektur durch einen zweiten Agenten
- **Konformitätstests**: YAML-Suiten als Verträge
- **Häufige Fallstricke**: zu vage Spezifikationen (vorherrschend), Auslassen menschlicher Überprüfung, Verwechslung von vibe coding mit Produktionsentwicklung
- **„Tödliche Dreifaltigkeit"**: Geschwindigkeit (schwer zu überprüfen) + Nichtdeterminismus + Kosten (begünstigen Abkürzungen)
- **Metapher**: Agenten als „kompetente Praktikanten" behandeln – klare Anweisungen, relevanter Kontext, umsetzbares Feedback
- **Erwähnte Tools**: Claude Code, GitHub Spec Kit, Cursor, LangGraph, OpenAI Swarm, Chroma, Context7, MCP

## RésuméDe400mots

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.

## GrapheDeConnaissance

- Addy Osmani —publie→ guide specs agents IA (DOCUMENT, 0.98)
- Addy Osmani —travaille_chez→ Google (ORGANISATION, 0.95)
- specs massives —réduit→ performance du modèle (surcharge de contexte) (CONCEPT, 0.95)
- Plan Mode —permet→ exploration read-only avant code (CONCEPT, 0.93)
- spec.md —permet→ cohérence cross-sessions (CONCEPT, 0.9)
- malédiction des instructions —réduit→ adhérence modèle (CONCEPT, 0.92)
- modularité specs —résout→ surcharge contexte (CONCEPT, 0.9)
- LLM-as-a-Judge —permet→ vérification de l'adhérence style et architecture (CONCEPT, 0.88)
- vitesse, non-déterminisme et coût —fait_partie_de→ triade létale (CONCEPT, 0.85)
- vibe coding —s_oppose_à→ ingénierie production (METHODOLOGIE, 0.83)
- Addy Osmani —recommande→ traiter les agents IA comme des stagiaires compétents (AFFIRMATION, 0.88)

---
Canonical: https://www.thekb.eu/de/fiches/osmani-how-write-good-spec-ai-agents-2026-01-13/