Wie man gute Spezifikationen für AI-Agenten schreibt

• Wenn man einem AI-Coding-Agenten auf einmal eine riesige Spezifikation vorsetzt, funktioniert er nicht richtig; der Schlüssel liegt in der smarten Spezifikationserstellung
• Empfohlen wird ein Vorgehen, bei dem zunächst eine Vision auf hoher Ebene vorgegeben wird, die AI dann den Detailplan ausarbeitet, dieser in Plan Mode schreibgeschützt geprüft wird und erst danach in die Phase der Code-Erstellung gewechselt wird
• Die Analyse von mehr als 2.500 Agenten-Konfigurationsdateien auf GitHub zeigt, dass effektive Spezifikationen sechs Kernbereiche enthalten: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
• Große Aufgaben sollten nicht als ein einziger riesiger Prompt, sondern in modularisierte kleine Tasks aufgeteilt werden, wobei nur der für den jeweiligen Task nötige Kontext mitgegeben werden sollte, um Qualitätsverluste zu vermeiden
• Zum Kern eines spezifikationsbasierten Entwicklungs-Workflows gehört, in die Spezifikation dreistufige Grenzen (Always/Ask first/Never), Selbstüberprüfung und Eignungstests einzubauen sowie sie kontinuierlich zu testen, zu iterieren und weiterzuentwickeln

---

TL;DR

• Eine klare Spezifikation schreiben, die ein angemessenes Maß an Details (Struktur, Stil, Tests, Grenzen usw.) enthält
• Große Aufgaben sollten nicht als ein einziger Prompt-Block, sondern in kleine Einheiten zerlegt werden
• Die Planung zuerst im schreibgeschützten Modus erstellen, dann ausführen und kontinuierlich verbessern

Kernprinzip: smarte Spezifikationserstellung

• Es scheitert, einem AI-Agenten einfach eine riesige Spezifikation hinzuwerfen; man stößt dabei an die Grenzen des Kontextfensters und das Aufmerksamkeitsbudget (attention budget) des Modells
• Eine „smarte Spezifikation“ ist ein Dokument, das den Agenten klar anleitet, innerhalb einer praktikablen Kontextgröße bleibt und sich mit dem Projekt weiterentwickelt
• Die aus der Nutzung von Coding-Agenten wie Claude Code und Gemini CLI gewonnenen Prinzipien werden in Form eines Frameworks zusammengefasst

Prinzip 1: Erst das große Bild geben, Details von der AI entwerfen lassen

• Statt von Anfang an alles übermäßig detailliert zu entwerfen, beginnt man besser mit einer klaren Zielbeschreibung und einigen zentralen Anforderungen
• Diese anfängliche Spezifikation wird wie ein „Produktbriefing“ behandelt, und der Agent bekommt die Aufgabe, darauf aufbauend eine detaillierte Spezifikation auszuarbeiten
• LLM-basierte Agenten füllen Details gut aus, wenn Anweisungen auf hoher Ebene klar sind; ist die Mission unklar, schweifen sie leicht ab
• Der entscheidende Punkt ist daher, dem Agenten zu Beginn eine klare Mission mitzugeben, damit er nicht vom Weg abkommt

• Plan Mode nutzen

  • Der Plan Mode von Claude Code hält den Agenten im schreibgeschützten Zustand und lässt ihn nur die Codebasis analysieren und einen detaillierten Plan erstellen
  • Wenn man mit Shift+Tab in den Plan Mode wechselt und beschreibt, „was man bauen möchte“, sichtet der Agent den bestehenden Code und erstellt einen ersten Spezifikationsentwurf
  • Dabei kann man verlangen, dass zusammen mit dem Plan auch Architektur, Best Practices, Sicherheitsrisiken und Teststrategie geprüft werden
  • Der Plan Mode sollte beibehalten werden, bis der Plan eindeutig und ohne Interpretationsspielraum ausgearbeitet ist; erst danach beendet man den Plan Mode und wechselt in die Umsetzungsphase

• Die Spezifikation als Kontext nutzen

  • Die bestätigte Spezifikation wird in einer Datei wie SPEC.md gespeichert, und bei der Arbeit werden dem Agenten jeweils nur die benötigten Abschnitte erneut gegeben
  • Weil die Spezifikationsdatei zwischen Sitzungen erhalten bleibt, dient sie auch beim Wiederaufnehmen des Projekts dazu, die AI auf denselben Bezugspunkt zu fixieren
  • Das hilft, Vergessen zu reduzieren, das durch lange Gesprächsverläufe oder einen Neustart des Agenten entsteht
  • So übernimmt sie – ähnlich wie ein gemeinsam genutztes PRD (Produktanforderungsdokument) im Team – die Rolle eines „einzigen Referenzdokuments“, auf das sich Menschen und AI gleichermaßen beziehen

• Zielorientiert bleiben

  • Eine Spezifikation auf hoher Ebene sollte sich von Anfang an eher auf what/why konzentrieren, statt alle Implementierungswege auszuschreiben; das konkrete how sollte später folgen
  • Die Struktur kann wie bei User Stories und Akzeptanzkriterien aufgebaut sein: „Wer ist der Nutzer? / Was wird benötigt? / Woran erkennt man Erfolg?“
  • Auch das GitHub Spec Kit betont den Ablauf, zunächst eine hochrangige Erklärung dazu zu geben, was und warum gebaut wird, und dann den Coding-Agenten die detaillierte Spezifikation mit Fokus auf Nutzererlebnis und Erfolgskriterien erstellen zu lassen

Prinzip 2: Die Spezifikation wie ein professionelles PRD (oder SRS) strukturieren

• Es ist wichtig, eine AI-Spezifikation nicht als bloße Sammlung von Notizen zu behandeln, sondern als strukturiertes Dokument mit klaren Abschnitten
• Eine umfassende und geordnete Form wie bei einem PRD oder Systemdesign-Dokument passt besonders gut zu einer AI, die Inhalte wörtlich interpretiert
• Die Analyse von mehr als 2.500 Agent-Konfigurationsdateien auf GitHub zeigte, dass effektive Spezifikationen durchgehend 6 Kernbereiche enthalten

  • 1. Commands

    • Ausführbare Befehle am Anfang des Dokuments platzieren
    • Nicht nur den Tool-Namen angeben, sondern den vollständigen Befehl einschließlich Flags: npm test, pytest -v, npm run build

  • 2. Testing

    • Konkret festhalten, wie Tests ausgeführt werden, welches Framework verwendet wird, wo die Testdateien liegen und welches Coverage-Niveau erwartet wird

  • 3. Project Structure

    • Die Orte von Quellcode, Tests und Dokumentation klar voneinander trennen
    • Beispiel: „src/ für Anwendungscode, tests/ für Unit-Tests, docs/ für Dokumentation“

  • 4. Code Style

    • Ein einziges echtes Code-Snippet ist viel wirksamer, als den Stil langatmig zu beschreiben
    • Benennungsregeln, Formatierungsstandards und Beispiele für gewünschte Ausgaben gemeinsam angeben

  • 5. Git Workflow

    • Wenn Branch-Namensregeln, Commit-Message-Format und PR-Anforderungen festgelegt sind, folgt auch der Agent diesem Ablauf

  • 6. Boundaries

    • Klar festlegen, welche Bereiche der Agent auf keinen Fall anfassen darf
    • Secrets, Vendor-Verzeichnisse, Produktionskonfigurationen, bestimmte Ordner usw.
    • Die GitHub-Studie zeigte, dass „niemals Secrets committen“ die am häufigsten genannte nützliche Einschränkung war

• Den Stack konkret angeben

  • Statt pauschal „React-Projekt“ zu schreiben, ist es wichtig, konkret wie „React 18 + TypeScript + Vite + Tailwind CSS“ zu formulieren
  • Versionen und zentrale Abhängigkeiten sollten mit angegeben werden; eine vage Spezifikation führt am Ende zu vagem Code

• Ein konsistentes Format verwenden

  • Klarheit ist am wichtigsten, und viele Entwickler trennen Abschnitte mit Markdown-Überschriften oder XML-ähnlichen Tags
  • AI-Modelle verarbeiten gut strukturierten Text deutlich zuverlässiger als frei formulierte Prosa
  • Auch Anthropic-Ingenieure empfehlen eine klar getrennte Abschnittsstruktur wie <background>, <instructions>, <tools>, <output_format>

• Die Spezifikation in die Toolchain integrieren

  • Die Spezifikation nicht nur als Dokument behandeln, sondern als „ausführbares Artefakt“, das mit Versionsverwaltung und CI/CD verbunden ist
  • GitHub Spec Kit verwendet einen 4-stufigen Gate-Workflow, der die Spezifikation ins Zentrum des Engineering-Prozesses stellt
    • Specify: Eine High-Level-Beschreibung liefern, was und warum gebaut wird, und den Coding-Agenten die detaillierte Spezifikation erstellen lassen
    • Plan: Einen technischen Plan mit gewünschtem Stack, Architektur und Randbedingungen ausarbeiten
    • Tasks: Spezifikation und Plan in reale Arbeitseinheiten aufteilen und diese jeweils in testbare Größen zerlegen
    • Implement: Der Coding-Agent bearbeitet die Tasks einzeln oder parallel

• Spezialisierte Personas über agents.md

  • In Tools wie GitHub Copilot lassen sich spezialisierte Agent-Personas definieren
  • Rollen wie @docs-agent (technische Dokumentation), @test-agent (QA) und @security-agent (Code Review) können getrennt werden
  • Jede agents.md-Datei dient als fokussierte Spezifikation, die das Verhalten, die Befehle und die Grenzen der jeweiligen Persona festhält

• Agent Experience (AX) entwerfen

  • So wie APIs auf Developer Experience (DX) ausgelegt werden, sollten auch Spezifikationen mit Blick auf die Agent Experience (AX) entworfen werden
  • Ein sauberes, leicht parsbares Format ist wichtig
    • OpenAPI-Schema der APIs, die der Agent verwenden wird
    • Dokumentationszusammenfassungen für den LLM-Konsum (llms.txt)
    • Explizite Typdefinitionen
  • Je stärker eine Spezifikation Standards wie MCP (Model Context Protocol) folgt, desto stabiler kann der Agent sie verstehen und danach arbeiten

• Als lebendes Dokument pflegen

  • Eine Spezifikation ist kein Dokument, das einmal geschrieben und dann abgeschlossen ist, sondern wird fortlaufend aktualisiert, wenn gemeinsam mit der AI Entscheidungen getroffen werden oder neue Fakten sichtbar werden
  • In spezifikationsgetriebenen Workflows steuert die Spezifikation Implementierung, Tests und Task-Zerlegung; bevor die Spezifikation validiert ist, geht es nicht in die nächste Phase
  • Diese Spezifikation ist nicht nur ein Dokument für AI, sondern ein zentrales Werkzeug, mit dem Entwickler den gesamten Ablauf überwachen und sicherstellen, dass die Ergebnisse der AI die tatsächlichen Anforderungen erfüllen

Prinzip 3: Aufgaben in modulare Prompts und Kontexte aufteilen

• Statt alles in einen einzigen riesigen Prompt zu packen, den Kontext so bereitstellen, dass sich der Agent jeweils nur auf eine Aufgabe gleichzeitig konzentriert
• Wenn Anforderungen, Code und Anweisungen des gesamten Projekts in einem einzigen Prompt stecken, führt das eher zu zusätzlicher Verwirrung
• Neben dem Risiko, an Token-Grenzen zu stoßen, kann auch der „Fluch der Anweisungen (curse of instructions)“ die Konzentrationsfähigkeit des Modells drastisch verringern

• Fluch der Anweisungen

  • Forschungsergebnisse zeigen, dass die Fähigkeit, einzelne Anweisungen präzise zu befolgen, spürbar abnimmt, je mehr Anweisungen oder Daten in einen Prompt gepackt werden
  • Selbst leistungsstarke Modelle wie GPT-4 oder Claude tun sich schwer damit, viele Anforderungen gleichzeitig zu erfüllen
  • Gibt man zum Beispiel 10 detaillierte Regeln als Bullet Points vor, werden oft nur die ersten Regeln eingehalten, während spätere nach und nach ignoriert werden
  • Die bessere Strategie ist iterative Fokussierung: jeweils nur auf ein Teilproblem konzentrieren und erst danach zum nächsten übergehen

• Spezifikationen in Schritte oder Komponenten aufteilen

  • Wenn ein Spezifikationsdokument lang ist oder einen großen Umfang abdeckt, sollte man es in mehrere Teile aufteilen
  • Beispiel: „Backend API Spec“ und „Frontend UI Spec“ als getrennte Abschnitte
  • Wer am Backend arbeitet, muss nicht ständig auch die Frontend-Spezifikation mitgeliefert bekommen
  • In einer Multi-Agent-Umgebung kann es außerdem separate Agenten oder Teilprozesse pro Bereich geben
  • Auch der DigitalOcean-AI-Guide warnt davor, „Authentifizierungsaufgaben und Änderungen am Datenbankschema auf einmal zu vermischen“

• Erweiterte TOC/Zusammenfassung für große Spezifikationen

  • Ein Ansatz ist, den Agenten zunächst ein erweitertes Inhaltsverzeichnis (TOC) der gesamten Spezifikation erstellen zu lassen
  • Dabei wird jeder Abschnitt auf einige Kernpunkte oder Schlüsselwörter verdichtet und zusammen mit einem Verweis auf die Stelle mit den Details festgehalten
  • Beispiel: „Security: HTTPS verwenden, API-Schlüssel schützen, Eingabevalidierung implementieren (siehe vollständige Spezifikation §4.2)“
  • Mit einer solchen hierarchischen Zusammenfassung bleibt im Prompt nur das große Bild erhalten, während Details bei Bedarf nachgereicht werden können
  • Das erweiterte TOC fungiert als eine Art Index und macht dem Agenten bewusst: „Aha, es gibt einen Security-Abschnitt“, sodass er diesen Teil gezielt anfordern kann
  • Diese Methode der hierarchischen Zusammenfassung hilft LLMs dabei, eine übergeordnete Struktur beizubehalten

• Sub-Agenten oder „Skills“ nutzen

  • Wie bei den von Anthropic beschriebenen Sub-Agenten (oder „Skills“) lassen sich mehrere Agenten mit getrennten Rollen einsetzen
  • Jeder Sub-Agent wird auf ein bestimmtes Fachgebiet ausgerichtet und erhält nur den entsprechenden Teil der Spezifikation
  • Beispiel: Ein Database-Designer-Sub-Agent kennt nur den Abschnitt zum Datenmodell, ein API-Coder-Sub-Agent nur die Spezifikation der API-Endpunkte
  • So arbeitet jeder Agent mit kleinerem Kontext und klarerer Rolle, was höhere Genauigkeit und paralleles Arbeiten ermöglicht
  • Claude Code unterstützt das Definieren von Sub-Agenten mit eigenem System-Prompt und eigenen Tools

• Parallele Agenten für mehr Durchsatz

  • Mehrere Agenten gleichzeitig laufen zu lassen, gilt zunehmend als nächste Stufe der Entwicklerproduktivität
  • Statt auf das Ende eines einzelnen Agenten zu warten, setzt man Agenten parallel auf Aufgaben an, die sich nicht überschneiden
  • Simon Willison beschreibt das als „parallel coding agents embrace“ und merkt an, dass es erstaunlich effektiv, mental aber ziemlich anstrengend sei
  • Entscheidend ist, den Aufgabenbereich klar zu trennen, damit sich die Agenten nicht gegenseitig in die Quere kommen
  • Orchestrierungs-Frameworks wie LangGraph oder OpenAI Swarm helfen bei dieser Koordination,
  • und wenn man eine Vektordatenbank wie Chroma als Shared Memory nutzt, ist gemeinsamer Kontext ohne redundantes Prompting zugänglich

• Einzelner vs. Multi-Agent: Wann sollte man was verwenden?

  Aspekt	Einzelner Agent	Parallele/Multi-Agenten
  Vorteile	Einfaches Setup, geringer Overhead, Debugging und Nachverfolgung des Ablaufs sind leicht	Hoher Durchsatz, Umgang mit komplexen Abhängigkeiten und Spezialisierung nach Fachdomänen möglich
  Nachteile	Kontextüberlastung bei großen Projekten, langsamere Iteration, Single Point of Failure	Höhere Koordinationskosten, Konfliktpotenzial, Bedarf an Shared Memory
  Geeignet für	Isolierte Module, kleine bis mittlere Projekte, frühes Prototyping	Große Codebases, Trennung von Coding, Testing und Review, Entwicklung unabhängiger Features
  Tipp	Spezifikationszusammenfassungen nutzen, Kontext pro Aufgabe aktualisieren, Sessions häufig zurücksetzen	Anfangs auf 2–3 Agenten begrenzen, Tools über MCP teilen, Grenzen klar definieren

• Jeden Prompt auf eine Aufgabe bzw. einen Abschnitt fokussieren

  • Auch ohne komplexe Multi-Agent-Umgebung lässt sich Modularität manuell gut erzwingen
  • Beispiel: Nach dem Schreiben der Spezifikation im Schritt „Step 1: Datenbankschema implementieren“ nur den Database-Abschnitt der Spezifikation bereitstellen
  • Den Kontext immer dann neu zusammenstellen, wenn sich die Hauptaufgabe ändert, um Ablenkung durch veraltete oder irrelevante Informationen zu reduzieren
  • Einige Leitfäden empfehlen, bei größeren Funktionswechseln eine neue Session zu starten, um den Kontext zu bereinigen

• Inline-Anweisungen und Code-TODOs nutzen

  • Aufgaben als // TODO-Kommentare im Code festhalten und vom Agenten nacheinander ausfüllen lassen
  • Jedes TODO fungiert als Mini-Spezifikation für eine kleine Aufgabe
  • Dadurch konzentriert sich die AI letztlich sehr eng auf Vorgaben wie: „Implementiere nur diese Funktion entsprechend diesem Spezifikations-Snippet“

Prinzip 4: Selbstprüfung, Constraints und menschliche Expertise einbauen

• Behandle die Spezifikation nicht bloß als Aufgabenliste für den Agenten, sondern als Leitfaden zur Qualitätssicherung, in den du deine eigene Expertise aktiv einfließen lässt
• Eine gute Spezifikation zeigt im Voraus auf, wo die AI Fehler machen könnte, und errichtet an diesen Stellen Guardrails
• Sie enthält Domänenwissen, Edge Cases und verschiedene „Hinweise“, damit die AI nicht in einem kontextlosen Vakuum arbeitet
• Es hilft, die Spezifikation als Coach und Schiedsrichter der AI zu sehen: Sie lenkt auf den richtigen Ansatz und bremst falsches Verhalten sofort
• Laut der Analyse von mehr als 2.500 Agent-Dateien auf GitHub verwenden die effektivsten Spezifikationen nicht einfach nur eine Liste von Verboten, sondern ein dreistufiges Grenzsystem
  • Es macht klar, wann der Agent einfach weitermachen kann, wann er stoppen und nachfragen sollte und wann er vollständig abbrechen muss

  • ✅ Always do (immer ausführen)

    • Aufgaben, die ohne Rückfrage erledigt werden sollen
    • Beispiel: „Vor jedem Commit immer Tests ausführen“, „Namenskonventionen des Styleguides immer einhalten“, „Fehler immer in den Monitoring-Service loggen“

  • ⚠️ Ask first (zuerst fragen)

    • Aufgaben, die menschliche Freigabe erfordern
    • Beispiel: „Vor Änderungen am Datenbankschema fragen“, „Vor dem Hinzufügen neuer Dependencies fragen“, „Vor Änderungen an der CI/CD-Konfiguration fragen“
    • Technisch mag das möglich sein, aber hier werden Änderungen herausgefiltert, die wegen ihres großen Wirkungsbereichs menschliches Urteil erfordern

  • 🚫 Never do (niemals tun)

    • Klar definierte Hard-Stop-Bereiche
    • Beispiel: „Secrets oder API-Keys niemals committen“, „node_modules/ oder vendor/ niemals bearbeiten“, „Fehlgeschlagene Tests niemals ohne ausdrückliche Freigabe entfernen“
    • Auch in der Studie wurde „Niemals Secrets committen“ als die am häufigsten genannte nützliche Restriktion bestätigt

• Selbstvalidierung fördern

  • Den Agenten dazu anhalten, seine Ergebnisse selbst anhand der Spezifikation zu prüfen
  • Wenn die Tools es erlauben, sollte der Workflow so gestaltet sein, dass nach der Code-Erzeugung selbstständig Unit-Tests oder Linting ausgeführt werden
  • Auch auf Prompt-Ebene lassen sich Anweisungen zur Gegenprüfung geben
    • Beispiel: „Vergleiche nach der Implementierung das Ergebnis mit der Spezifikation, prüfe, ob alle Anforderungen erfüllt sind, und liste nicht erfüllte Punkte auf“
  • Das verringert Auslassungen, indem das LLM seine eigene Ausgabe mit der Spezifikation abgleicht

• LLM-as-a-Judge für subjektive Prüfungen

  • Für Kriterien, die sich schwer automatisieren lassen, etwa Code-Stil, Lesbarkeit oder die Einhaltung von Architekturmustern, lässt sich der Ansatz LLM-as-a-Judge nutzen
  • Ein zweiter Agent (oder ein separater Prompt) prüft die Ausgabe des ersten Agenten anhand der Qualitätskriterien der Spezifikation
  • Beispiel: „Prüfe, ob dieser Code unserem Styleguide entspricht, und markiere Verstöße“
  • Der Agent in der Rolle des Schiedsrichters gibt Feedback zurück, das dann übernommen oder als Anlass für Korrekturen genutzt wird

• Konformitätstests

  • Willison empfiehlt den Aufbau einer Conformance Suite
  • Sprachunabhängige Tests, oft auf YAML-Basis, dienen als Vertrag, den jede Implementierung zwingend bestehen muss
  • Wenn man eine API baut, definiert die Conformance Suite erwartete Ein- und Ausgaben, und der vom Agenten erzeugte Code muss sie vollständig erfüllen
  • Im Abschnitt Success der Spezifikation lassen sich Kriterien wie „Alle Fälle in conformance/api-tests.yaml müssen bestanden werden“ festhalten

• Tests in der Spezifikation nutzen

  • Wenn möglich, sollten Testplan oder echte Tests direkt in Spezifikation und Prompt-Flow aufgenommen werden
  • Wie bei TDD machen Testfälle Anforderungen eindeutig
    • Beispiel: In den Success Criteria kann stehen: „Diese Beispiel-Eingabe muss zwingend diese Ausgabe erzeugen“
  • Willison beschreibt eine robuste Test-Suite als faktische Superkraft für Agenten
  • Denn bei Testfehlern kann sofort validiert und iteriert werden
  • In einer Subagenten-Konfiguration kann es außerdem einen dedizierten Test-Agenten geben, der auf Basis der Spezifikationskriterien die Code-Ausgabe fortlaufend prüft

• Domänenwissen einfließen lassen

  • Eine Spezifikation sollte praxisnahe Einsichten enthalten, die nur erfahrene Entwickler oder Personen mit Kontextwissen kennen
  • Beispiel: Beim Erstellen eines E-Commerce-Agenten sollte klar festgehalten werden, dass „products“ und „categories“ in einer Many-to-Many-Beziehung stehen
    • Man sollte nicht erwarten, dass die AI das von selbst erschließt
  • Wenn eine bestimmte Bibliothek heikel ist, sollten häufige Fallstricke und Hinweise ebenfalls ausdrücklich genannt werden
  • So fließt die eigene Mentorschaft in die Spezifikation ein
    • Beispiel: „Bei der Verwendung von Library X gibt es in Version Y ein Memory-Leak-Problem, daher Workaround Z anwenden“

• Minimalismus bei einfachen Tasks

  • Eine gründliche Spezifikation ist wichtig, aber ein Teil von Expertise besteht auch darin zu wissen, wann Einfachheit besser ist
  • Bei vergleichsweise einfachen und isolierten Aufgaben kann eine überladene Spezifikation eher Verwirrung stiften
  • Für Aufgaben wie „Ein div auf der Seite zentrieren“ reicht oft schon
    • „Die Lösung kompakt halten und kein unnötiges Markup oder Styling hinzufügen“
  • Umgekehrt braucht eine komplexe Aufgabe wie „Einen OAuth-Flow mit Token-Refresh und Fehlerbehandlung implementieren“ eine detaillierte Spezifikation
  • Ein praxisnaher Maßstab ist, die Dichte der Spezifikation an die Komplexität der Aufgabe anzupassen

• Den Menschen als letzten Qualitätsfilter beibehalten

  • Die Spezifikation delegiert zwar Befugnisse an den Agenten, aber die endgültige Qualitätsverantwortung liegt beim Entwickler
  • Selbst wenn der Agent die Spezifikation technisch erfüllt, sollte man dem eigenen Urteil vertrauen, wenn Tonalität oder Kontext nicht stimmen
  • Falls nötig, ist es ganz natürlich, die Spezifikation weiter zu verfeinern oder das Ergebnis direkt selbst zu überarbeiten
  • Willison vergleicht die Arbeit mit AI-Agenten mit „einer sehr seltsamen Form von Management“ und „auf unangenehme Weise der Betreuung eines menschlichen Praktikanten erstaunlich ähnlich“
  • Letztlich bleibt es die Aufgabe des Menschen, klare Anweisungen (die Spezifikation), ausreichend Kontext und umsetzbares Feedback zu geben

Prinzip 5: Testen, Iterieren, Spezifikation weiterentwickeln (die richtigen Tools nutzen)

• Das Schreiben von Spezifikationen und der Aufbau von Agenten sollten nicht als einmalige Aufgabe verstanden werden, sondern als iterative Schleife
  • Ein Ablauf, bei dem man schnell testet, Feedback sammelt, die Spezifikation verfeinert und Prüfungen mit Tools automatisiert
• Die erste Spezifikation ist kein Endprodukt, sondern der Ausgangspunkt eines Zyklus

• Kontinuierliches Testen

  • Nicht warten, bis die gesamte Implementierung abgeschlossen ist, sondern an wichtigen Meilensteinen oder auf Funktionsbasis Tests oder einfache manuelle Prüfungen durchführen
  • Wenn Fehler entdeckt werden, nicht einfach weitermachen, sondern zuerst die Spezifikation oder den Prompt anpassen
  • Automatisierte Tests sind besonders effektiv; wenn Tests vorhanden sind, kann der Agent Befehle wie npm test selbst ausführen
  • Die Ergebnisse fehlgeschlagener Tests direkt als Eingabe für den nächsten Prompt verwenden
    • Beispiel: „Die Ausgabe erfüllt bei X, Y, Z die Spezifikation nicht, also korrigiere sie“
  • Die agentische Schleife aus Code → Test → Korrektur → Wiederholung ist ein sehr wirkungsvoller Ansatz

• Iteration der Spezifikation selbst

  • Wenn der Agent etwas missverstanden hat oder fehlende Anforderungen sichtbar werden, das Problem nicht kaschieren, sondern zuerst das Spezifikationsdokument anpassen
  • Die überarbeitete Spezifikation anschließend explizit erneut mit dem Agenten synchronisieren
    • Beispiel: „Ich habe die Spezifikation wie folgt aktualisiert. Passe den Plan an diese Änderungen an oder refaktoriere den Code entsprechend.“
  • Die Spezifikation immer als Single Source of Truth pflegen
  • Wenn möglich, per Commit-Message oder Notizen einen Versionsverlauf hinterlassen, damit nachvollziehbar bleibt, was sich warum geändert hat

• Kontextverwaltung und Nutzung von Memory-Tools

  • Das Tool-Ökosystem, das die Kontext- und Wissensverwaltung von AI-Agenten unterstützt, wächst rasant
  • Mit dem Muster RAG (Retrieval-Augmented Generation) kann ein Agent aus einer Wissensbasis wie einer Vektor-Datenbank sofort nur die benötigten Informationen abrufen
  • Wenn die Spezifikation sehr groß ist, können Abschnitte eingebettet werden, sodass der Agent statt des gesamten Dokuments nur die relevantesten Teile abruft
  • Auf MCP (Model Context Protocol) basierende Frameworks stellen automatisch den zum aktuellen Task passenden Kontext bereit
  • Tools wie Context7(context7.com) laden abhängig von der aktuellen Arbeit automatisch relevante Snippets aus der Dokumentation

• Sorgfältige Parallelisierung

  • Einige Entwickler beschleunigen die Arbeit, indem sie mehrere Agent-Instanzen parallel für unterschiedliche Tasks ausführen
  • Beispiel: Ein Agent generiert Code, während ein anderer gleichzeitig Tests schreibt
  • Wer diesen Ansatz wählt, sollte sicherstellen, dass die Tasks tatsächlich unabhängig oder klar voneinander getrennt sind, um Konflikte zu vermeiden
  • Beispiel: Beschränkungen setzen, damit nicht zwei Agenten gleichzeitig dieselbe Datei ändern
  • Um den Verwaltungsaufwand gering zu halten, ist es realistisch, anfangs mit höchstens 2–3 Agenten zu starten

• Versionsverwaltung und Spezifikations-Freeze

  • Die Arbeit des Agenten mit Versionsverwaltungstools wie Git sorgfältig nachverfolgen
  • Je stärker man AI einsetzt, desto wichtiger werden gute Gewohnheiten in der Versionsverwaltung
  • Auch die Spezifikationsdatei selbst ins Repository committen, um die Änderungshistorie festzuhalten
  • Der Agent kann auch git diff oder blame lesen und so den Kontext von Änderungen verstehen
    • Tatsächlich sind LLMs ziemlich gut darin, Diffs zu interpretieren
  • Liegt die Spezifikation im Repo, können Entwickler und AI gemeinsam die Entwicklung des Projekts nachvollziehen
  • Willison formuliert es so, dass Modelle „wahnsinnig kompetent in Git“ seien

• Kosten und Geschwindigkeit berücksichtigen

  • Aufgaben mit großen Modellen und langem Kontext können langsam und teuer sein
  • Die Modellauswahl strategisch aufteilen
    • Für erste Entwürfe oder wiederholbare Arbeiten schnelle und günstige Modelle
    • Für finale Ausgaben oder komplexes Schlussfolgern die leistungsfähigsten (teuren) Modelle
  • Beispiel: GPT-4 oder Claude für Planung und Schlüsselschritte, einfache Erweiterungen oder Refactorings dagegen lokalen Modellen oder kleinen API-Modellen überlassen
  • Für Test-Runner-Agenten oder Linter-Agenten reichen vergleichsweise kleine Modelle oft aus
  • Auch die Kontextgröße muss aktiv gemanagt werden
    • Für einen Task, der mit 5k Tokens auskommt, muss man nicht 20k Tokens hineingeben
    • Mit steigender Token-Zahl kann die Effizienz sinken

• Alles überwachen und protokollieren

  • In komplexen Agent-Workflows sind Logs über Verhalten und Ausgaben des Agenten unverzichtbar
  • Über Logs lässt sich prüfen, ob der Agent von der Absicht abgewichen ist oder Fehler aufgetreten sind
  • Viele Frameworks bieten Trace-Logs oder unterstützen die Ausgabe schrittweiser Gedankengänge
  • Ein Blick in die Logs zeigt, wo die Spezifikation oder die Anweisung falsch interpretiert wurde

• Lernen und verbessern

  • Jedes Projekt als Lerngelegenheit nutzen, um die eigene Fähigkeit zum Schreiben von Spezifikationen zu schärfen
  • Man kann beobachten, ob bestimmte Formulierungen die AI wiederholt verwirren oder welche Spezifikationsstruktur zuverlässiger eingehalten wird
  • Solche Erkenntnisse aktiv in die nächste Spezifikation einfließen lassen
  • Das Feld der AI-Agenten entwickelt sich schnell weiter, und ständig entstehen neue Tools und Best Practices

Häufige Fehler vermeiden

• Die Analyse von mehr als 2.500 Agent-Dateien auf GitHub zeigt, dass die häufigste Ursache für Fehlschläge übermäßig vage Spezifikationen und Anweisungen sind

• Vage Prompts

  • Anfragen wie „Mach etwas Cooles“ oder „Sorge dafür, dass es besser funktioniert“ geben dem Agenten überhaupt keinen Beurteilungsmaßstab
  • Eingaben, Ausgaben und Randbedingungen sollten so konkret wie möglich formuliert werden
  • Allgemeine Rollenfestlegungen wie „Du bist ein hilfreicher Coding-Assistent“ haben kaum Wirkung
  • Dagegen funktioniert eine Kombination aus Rolle, Umfang und Einschränkungen wie „Du bist ein Testingenieur, der React-Komponententests schreibt, diesem Beispiel folgt und den Quellcode niemals verändert“ deutlich besser

• Zu viel Kontext ohne Zusammenfassung

  • Ein 50-seitiges Dokument einfach in den Prompt zu kippen und zu erwarten, dass das Modell es von selbst versteht, scheitert in den meisten Fällen
  • Stattdessen braucht es hierarchische Zusammenfassungen oder RAG, damit nur Inhalte sichtbar werden, die direkt mit dem aktuellen Task zusammenhängen
  • Mehr Kontextlänge kann fehlende Qualität des Kontexts nicht ersetzen

• Menschliche Prüfung überspringen

  • Willisons persönliche Regel: „Code, den ich niemand anderem erklären kann, committe ich nicht.“
  • Nur weil ein Agent etwas erzeugt hat, das Tests besteht, heißt das noch lange nicht, dass der Code sofort korrekt, sicher und wartbar ist
  • Gerade kritische Codepfade sollten immer von Menschen direkt geprüft werden
  • Auf AI-generierten Code passt das Bild eines „Kartenhauses“ gut: Er wirkt auf den ersten Blick solide, kann aber bei ungetesteten Edge Cases zusammenbrechen

• Vibe Coding und Production Engineering verwechseln

  • Schnelles Prototyping mit AI, oft als „Vibe Coding“ bezeichnet, eignet sich für Explorationsphasen oder einmalige Projekte
  • Wer solche Ergebnisse ohne strenge Spezifikationen, Tests und Reviews direkt in Produktion bringt, riskiert Probleme
  • „Vibe Coding“ und „AI-unterstütztes Engineering“ müssen klar getrennt werden; Letzteres erfordert die in diesem Leitfaden beschriebenen Disziplinen und Prozesse
  • Wichtig ist, sich bewusst zu sein, in welchem Modus man gerade arbeitet

• Die „fatale Dreierkombination“ ignorieren

  • Drei Eigenschaften, vor denen Willison warnt und die AI-Agenten riskant machen
    • Geschwindigkeit: Ergebnisse werden schneller erzeugt, als Menschen sie prüfen können
    • Nichtdeterminismus: Selbst bei identischer Eingabe fällt die Ausgabe von Lauf zu Lauf unterschiedlich aus
    • Kosten: Sie verleiten dazu, Abkürzungen zu nehmen, statt gründlich zu validieren
  • Spezifikationen und Review-Prozesse müssen so gestaltet werden, dass alle drei Punkte von vornherein berücksichtigt werden
  • Vor allem muss bewusst kontrolliert werden, dass die Geschwindigkeit nicht die Fähigkeit zur Verifikation überholt

• Die 6 Kernbereiche auslassen

  • Wenn eine Spezifikation Commands, Testing, Project Structure, Code Style, Git Workflow und Boundaries nicht behandelt, fehlt dem Agenten leicht wichtige Arbeitsgrundlage
  • Vor der Übergabe an den Agenten ist ein zusätzlicher Check mit einer Checkliste der 6 Bereiche sinnvoll

Fazit

• Für das Verfassen effektiver Spezifikationen für AI-Coding-Agenten braucht es sowohl solide Software-Engineering-Prinzipien als auch ein Verständnis der Eigenschaften von LLMs und einen darauf abgestimmten Ansatz
• Alles beginnt damit, das Ziel klar zu definieren; darauf aufbauend wird die Rollenverteilung so gestaltet, dass die AI Planung und Details ausarbeitet
• Spezifikationen sollten nicht als Notizen, sondern als ernsthafte Designdokumente behandelt werden, die sechs Kernbereiche enthalten und als mit der Toolchain verbundene ausführbare Artefakte gelten
• Statt alles auf einmal zu geben, sollte man Inhalte nach Arbeitseinheiten aufteilen, damit der Agent fokussiert bleibt
  (eine zusammenfassende TOC, Subagenten und parallele Orchestrierung sind praktische Mittel, um mit umfangreichen Spezifikationen umzugehen)
• Mit dreistufigen Grenzen (Always / Ask first / Never), Selbstprüfungen und Eignungstests lassen sich typische Fallstricke für AI im Voraus abfangen
• Entscheidend ist, Spezifikationen und Implementierung nicht als starre Endprodukte, sondern als iterativen Prozess zu behandeln und Spezifikation und Code durch Tests und Feedback gemeinsam kontinuierlich weiter zu verfeinern
• Wenn man diese Richtlinien befolgt, lässt sich die Wahrscheinlichkeit, dass AI-Agenten in großen Kontexten die Orientierung verlieren oder in Unsinn abgleiten, spürbar verringern