Stell dir vor, du hast einen neuen Praktikanten eingestellt. Er ist unglaublich schnell, kennt sich theoretisch mit allem aus und arbeitet rund um die Uhr. Klingt perfekt, oder? Der Haken: Er nimmt alles wörtlich, vergisst manchmal wichtige Details und braucht glasklare Anweisungen. Genau so verhält es sich mit KI-Coding-Agenten wie Claude Code, GitHub Copilot oder Gemini CLI.

Das Problem kennen viele Entwickler: Du schreibst eine ausführliche Spezifikation, wirfst sie dem KI-Agenten vor – und das Ergebnis ist trotzdem nicht das, was du dir vorgestellt hast. Entweder ist der Kontext zu groß und das Modell verliert den Faden, oder wichtige Anforderungen gehen unter. Die gute Nachricht: Mit der richtigen Technik kannst du KI-Agenten so anleiten, dass sie tatsächlich liefern, was du brauchst.

Warum normale Dokumentation für KI-Agenten nicht ausreicht

Wenn du einem menschlichen Kollegen eine Aufgabe gibst, kann er zwischen den Zeilen lesen. Er versteht Kontext, fragt nach und nutzt sein Erfahrungswissen. KI-Agenten funktionieren anders: Sie sind wie eine extrem leistungsfähige Maschine, die aber nur das verarbeiten kann, was du ihr explizit gibst.

Das klassische Vorgehen, ein riesiges Dokument mit allen Anforderungen, funktioniert dabei selten. Studien zeigen, dass selbst fortschrittliche Modelle wie GPT-5 oder Claude Schwierigkeiten bekommen, wenn sie zu viele Anweisungen gleichzeitig befolgen sollen. Man spricht vom sogenannten "Fluch der Instruktionen": Je mehr Regeln du auf einmal gibst, desto wahrscheinlicher übersieht das Modell einige davon.

Die fünf Grundprinzipien für erfolgreiche KI-Spezifikationen

Prinzip 1: Mit der Vision starten und die KI die Details ausarbeiten lassen

Denk an einen Architekten: Er beginnt nicht mit den Steckdosen, sondern mit der Grundidee des Hauses. Genauso solltest du bei KI-Agenten vorgehen. Starte mit einer kurzen, klaren Beschreibung dessen, was du erreichen willst – wie ein Produktbriefing.

Anstatt sofort jedes technische Detail festzulegen, gibst du dem Agenten eine Zielbeschreibung: "Baue eine Web-App, mit der Teams ihre Aufgaben verwalten können. Es braucht Benutzerkonten, eine Datenbank und eine einfache Benutzeroberfläche." Aus dieser Vorgabe kann der Agent dann eine detaillierte Spezifikation erstellen, die ihr gemeinsam verfeinert.

Der Plan-Modus: Erst denken, dann handeln

Viele moderne Tools wie Claude Code bieten einen sogenannten Plan-Modus an. Dabei arbeitet der Agent im Nur-Lesen-Modus: Er analysiert deinen Code, erstellt detaillierte Pläne, schreibt aber noch keine einzige Zeile Code. Das ist wie eine Planungssitzung vor dem eigentlichen Bau.

In diesem Modus kannst du den Agenten bitten, Unklarheiten zu identifizieren, die Architektur zu prüfen und Sicherheitsrisiken zu benennen. Erst wenn der Plan wasserdicht ist, gibst du grünes Licht für die Umsetzung. So vermeidest du den häufigsten Fehler: direkt loszucoden, bevor die Spezifikation steht.

Prinzip 2: Die Spezifikation wie ein Profi-Dokument strukturieren

Stell dir vor, du gibst einem Handwerker einen Zettel mit wirren Notizen versus einen ordentlichen Bauplan. Der Unterschied im Ergebnis ist offensichtlich. KI-Agenten profitieren enorm von einer klaren Struktur.

Die sechs Kernbereiche einer guten Spezifikation

Eine Analyse von über 2.500 Agenten-Konfigurationsdateien hat gezeigt, dass die erfolgreichsten Spezifikationen sechs Bereiche abdecken:

Befehle: Setze ausführbare Kommandos an den Anfang – nicht nur Tool-Namen, sondern vollständige Befehle mit allen Parametern. Also nicht "npm test", sondern "npm test -- --coverage --watchAll=false".

Tests: Wie werden Tests ausgeführt? Welches Framework wird verwendet? Wo liegen die Test-Dateien? Welche Code-Abdeckung wird erwartet?

Projektstruktur: Wo liegt der Quellcode? Wo gehören Tests hin? Wo die Dokumentation? Sei explizit: "src/ für Anwendungscode, tests/ für Unit-Tests, docs/ für Dokumentation."

Code-Stil: Ein echtes Code-Beispiel, das deinen Stil zeigt, ist wertvoller als drei Absätze Beschreibung. Zeige Namenskonventionen, Formatierungsregeln und Beispiele für gute Ausgaben.

Git-Workflow: Branch-Benennung, Commit-Message-Format, Pull-Request-Anforderungen. Der Agent kann diese Regeln befolgen, wenn du sie klar formulierst.

Grenzen: Was darf der Agent auf keinen Fall anfassen – Secrets, Vendor-Verzeichnisse, Produktionskonfigurationen. Die Regel "Niemals Secrets committen" war die häufigste hilfreiche Einschränkung in der Analyse.

Ein Beispiel für eine gut strukturierte Spezifikation

# Projekt-Spec: Team-Aufgaben-App

## Ziel

Web-App für kleine Teams zur Aufgabenverwaltung entwickeln

## Tech-Stack

- React 18+, TypeScript, Vite, Tailwind CSS
- Node.js/Express Backend, PostgreSQL, Prisma ORM

## Befehle

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint --fix`

## Projektstruktur

- `src/` – Anwendungs-Quellcode
- `tests/` – Unit- und Integrationstests
- `docs/` – Dokumentation

## Grenzen

- ✅ Immer: Tests vor Commits ausführen
- ⚠️ Erst fragen: Datenbankschema-Änderungen
- 🚫 Niemals: Secrets committen

Prinzip 3: Aufgaben aufteilen statt alles in einen Prompt packen

Stell dir vor, du erklärst jemandem gleichzeitig, wie man Auto fährt, ein Fünf-Gänge-Menü kocht und Steuererklärung macht. Das Ergebnis wäre Chaos. Genauso geht es KI-Agenten, wenn sie zu viele verschiedene Dinge auf einmal erledigen sollen.

Teile und herrsche

Der bessere Ansatz: Zerlege deine Spezifikation in logische Teile und gib dem Agenten immer nur den relevanten Abschnitt. Wenn er am Backend arbeitet, braucht er die Frontend-Spezifikation nicht zu sehen. Das reduziert nicht nur die Kontextgröße, sondern erhöht auch die Qualität der Ergebnisse erheblich.

Die Zusammenfassungs-Technik

Bei sehr umfangreichen Spezifikationen hilft eine clevere Technik: Lass den Agenten ein erweitertes Inhaltsverzeichnis mit Kurzfassungen erstellen. Jeder Abschnitt wird auf ein bis zwei Kernpunkte verdichtet. Dieses Inhaltsverzeichnis bleibt im Prompt, während die Details nur bei Bedarf geladen werden. So behält der Agent den Überblick, ohne von Informationen überflutet zu werden.

Spezialisierte Sub-Agenten einsetzen

Für komplexe Projekte kannst du auch mit mehreren spezialisierten Agenten arbeiten: Ein Datenbank-Agent kennt nur das Datenmodell, ein API-Agent nur die Endpunkte. Wie ein Team von Spezialisten, die jeweils ihr Fachgebiet beherrschen. Moderne Tools wie Claude Code unterstützen dieses Konzept durch sogenannte Subagenten mit eigenen Kontextfenstern und Systemprompts.

Prinzip 4: Selbstprüfungen und klare Grenzen einbauen

Eine gute Spezifikation ist nicht nur eine Aufgabenliste – sie ist auch ein Qualitätssicherungssystem. Denk an sie wie an einen Trainer, der nicht nur sagt, was zu tun ist, sondern auch aufpasst, dass keine Fehler passieren.

Das Drei-Stufen-Grenzensystem

Die effektivsten Spezifikationen nutzen ein dreistufiges System statt einfacher Verbote:

Immer tun: Aktionen, die der Agent ohne Nachfrage ausführen soll. "Immer Tests vor Commits ausführen." "Immer die Namenskonventionen des Style-Guides befolgen."

Erst fragen: Aktionen, die menschliche Genehmigung erfordern. "Vor Änderungen am Datenbankschema fragen." "Vor dem Hinzufügen neuer Dependencies fragen."

Niemals tun: Harte Stopps. "Niemals Secrets oder API-Keys committen." "Niemals node_modules bearbeiten." "Niemals einen fehlgeschlagenen Test ohne explizite Genehmigung entfernen."

Selbstverifikation aktivieren

Du kannst den Agenten auch anweisen, seine eigene Arbeit zu überprüfen: "Nach der Implementierung vergleiche das Ergebnis mit der Spezifikation und bestätige, dass alle Anforderungen erfüllt sind. Liste alle nicht adressierten Punkte auf." Das klingt simpel, fängt aber erstaunlich viele Fehler ab.

Prinzip 5: Testen, iterieren und die Spezifikation weiterentwickeln

Die erste Version deiner Spezifikation ist nicht das Ende – sie ist der Anfang eines kontinuierlichen Verbesserungsprozesses. Wie beim agilen Entwickeln: Du testest früh, sammelst Feedback und passt an.

Der Iterations-Kreislauf

Nach jedem wichtigen Meilenstein solltest du prüfen, ob der Agent die Spezifikation korrekt umgesetzt hat. Automatisierte Tests sind dabei Gold wert: Lass den Agenten nach jeder Aufgabe die Tests ausführen. Fehlschläge werden zum Feedback für den nächsten Durchgang.

Wenn du merkst, dass die Spezifikation unvollständig oder unklar war, aktualisiere sie sofort. Dann synchronisiere den Agenten mit der neuen Version: "Ich habe die Spezifikation wie folgt aktualisiert... Passe den Plan entsprechend an." So bleibt die Spezifikation die einzige Quelle der Wahrheit.

Häufige Fehler, die du vermeiden solltest

Die Analyse tausender Agenten-Konfigurationen hat einen deutlichen Unterschied gezeigt: Die meisten scheitern, weil sie zu vage sind. Hier die wichtigsten Fallstricke:

Vage Prompts wie "Bau mir etwas Cooles" geben dem Agenten keinen Ankerpunkt. Sei spezifisch über Eingaben, Ausgaben und Einschränkungen.

Überladene Kontexte ohne Zusammenfassung funktionieren selten. 50 Seiten Dokumentation in einen Prompt zu werfen und zu hoffen, dass das Modell es schon richtet, ist keine Strategie.

Menschliche Überprüfung überspringen ist gefährlich. Nur weil der Agent Code produziert hat, der Tests besteht, heißt das nicht, dass er korrekt, sicher oder wartbar ist.

Fazit: Der Schlüssel zum Erfolg mit KI-Agenten

Das Schreiben effektiver Spezifikationen für KI-Coding-Agenten verbindet solide Software-Engineering-Prinzipien mit einem Verständnis für die Eigenheiten großer Sprachmodelle. Der Kern lässt sich auf fünf Punkte verdichten: Starte mit einer klaren Vision und lass die KI den Plan ausarbeiten. Strukturiere die Spezifikation wie ein professionelles Dokument mit den sechs Kernbereichen. Halte den Fokus des Agenten eng, indem du ihm jeweils nur ein Puzzleteil gibst. Baue Selbstprüfungen und dreistufige Grenzen ein. Und behandle den gesamten Prozess als iterativ – nutze Tests und Feedback, um sowohl die Spezifikation als auch den Code kontinuierlich zu verbessern.

Mit diesen Techniken wird dein "digitaler Praktikant" vom unberechenbaren Helfer zum verlässlichen Teammitglied. Es erfordert anfangs mehr Aufwand, aber die Investition zahlt sich schnell aus: weniger Nacharbeit, bessere Ergebnisse und ein KI-Agent, der tatsächlich liefert, was du brauchst.

Häufig gestellte Fragen (FAQ)

Wie lang sollte eine Spezifikation für KI-Agenten idealerweise sein?

Die Länge hängt von der Komplexität der Aufgabe ab. Für einfache, isolierte Aufgaben reichen wenige Sätze mit klaren Anforderungen. Bei komplexen Projekten kann eine Spezifikation mehrere Seiten umfassen – wichtig ist dann aber, sie in modulare Abschnitte aufzuteilen und dem Agenten nur den jeweils relevanten Teil zu geben. Als Faustregel gilt: So kurz wie möglich, so detailliert wie nötig. Ein überladener Kontext schadet mehr, als dass er hilft.

Kann ich dieselbe Spezifikation für verschiedene KI-Agenten wie Claude Code und GitHub Copilot verwenden?

Grundsätzlich ja, da die Kernprinzipien universell sind. Allerdings haben verschiedene Tools unterschiedliche Stärken und Eigenheiten. Claude Code unterstützt beispielsweise Subagenten und einen Plan-Modus, während GitHub Copilot andere Integrationsmöglichkeiten bietet. Es lohnt sich, die Spezifikation leicht anzupassen und die spezifischen Fähigkeiten des jeweiligen Tools zu nutzen. Die sechs Kernbereiche (Befehle, Tests, Projektstruktur, Code-Stil, Git-Workflow, Grenzen) sind jedoch überall relevant.

Was mache ich, wenn der KI-Agent trotz guter Spezifikation falsche Ergebnisse liefert?

Zunächst solltest du prüfen, ob die Spezifikation wirklich so klar ist, wie du denkst – oft liegt das Problem in mehrdeutigen Formulierungen. Dann hilft es, die Aufgabe in kleinere Teile zu zerlegen und jeden einzeln abzuarbeiten. Aktiviere Selbstverifikation, indem du den Agenten bittest, sein Ergebnis gegen die Spezifikation zu prüfen. Und schließlich: Aktualisiere die Spezifikation basierend auf dem Fehler. Wenn der Agent etwas falsch verstanden hat, formuliere den betreffenden Abschnitt um und mache ihn expliziter. Behandle es als Lernprozess für beide Seiten.