Warum „einfach mal probieren" bei KI-Assistenten nicht reicht

Stell dir folgendes Szenario vor: Du hast eine klare Idee für ein Feature. Du öffnest deinen Lieblings-KI-Coding-Assistenten, formulierst eine schnelle Anfrage – und siehst zu, wie das Tool selbstbewusst große Teile deiner Codebasis umschreibt. Eine Stunde später starrst du auf einen Pull Request, der ein Problem löst, das du gar nicht lösen wolltest – auf eine Weise, die andere Dinge kaputtmacht.

Kommt dir bekannt vor? Du bist nicht allein. Während KI-Coding-Agenten sich von simplen Frage-Antwort-Maschinen zu echten Code-Editoren entwickelt haben, merken immer mehr Entwickler: Dieselbe lässige Art zu prompten, die bei Chatbots funktioniert, stößt bei echten Repositories an ihre Grenzen.

Die Lösung ist nicht ein detaillierterer Prompt. Es geht um einen grundlegenden Perspektivwechsel – hin zu einer anderen Art von Dokumenten für diese Agenten.

Prompts vs. Specs: Warum der Unterschied entscheidend ist

Prompts sind für den Einstieg gemacht. Sie eignen sich für schnelle Erklärungen, Wegwerf-Skripte und explorative Gespräche. Ein Prompt lebt in einer Chat-Session, darf Abkürzungen nutzen und geht oft von Kontext aus, den nur der Autor kennt.

Das funktioniert, solange du nur Fragen stellst.

Aber wenn ein KI-Agent gleich echten Code bearbeiten, Terminal-Befehle ausführen und Branches erstellen soll, die Kollegen reviewen müssen? Dann wird aus deinem lockeren Prompt eine Art Arbeitsauftrag. Und Aufträge brauchen mehr als eine gute Formulierung – sie brauchen den richtigen Kontext, klare Grenzen, konkrete Beispiele und Prüfkriterien.

Genau hier kommen Specs ins Spiel.

Eine Spec ist kein schönerer Prompt. Sie ist ein strukturiertes Dokument, das festhält: Welches Problem lösen wir? Was soll sich ändern? Was muss gleich bleiben? Und woran erkennen wir, ob die Arbeit erfolgreich war? Anders als ein Prompt, der verschwindet, sobald der Agent loslegt, bleibt eine Spec während des gesamten Workflows sichtbar – sie leitet den Agenten an, hilft Reviewern und gibt zukünftigen Maintainern den nötigen Kontext.

Was eine gute KI-Agent-Spec ausmacht

Du brauchst kein 20-seitiges Dokument. Fünf Kernelemente reichen völlig aus:

1. Kontext: Warum gibt es diese Aufgabe? Welches User-Problem oder welche technische Schuld steckt dahinter? Welche Einschränkungen im Code sollte der Agent kennen?

2. Verhalten, das sich ändert: Was genau soll modifiziert, ergänzt oder entfernt werden? Konkret sein zahlt sich aus – „User erhalten E-Mail-Benachrichtigungen, wenn X passiert" ist besser als „Notification-System verbessern".

3. Grenzen, die eingehalten werden müssen: Was darf sich auf keinen Fall ändern? Welche existierenden Features, API-Verträge oder Performance-Eigenschaften müssen intakt bleiben?

4. Beispiele für korrektes Verhalten: Konkrete Szenarien, die zeigen, was „gut" bedeutet. Given/When/Then-Format funktioniert gut, aber auch ein paar explizite Testfälle helfen dem Agenten, deine Erwartungen zu verstehen.

5. Prüfkriterien: Woran erkennt ein Reviewer, ob die Arbeit fertig ist? Was sollte geprüft werden? Welche Fragen sollte er stellen?

Dieses Framework klingt vertraut, wenn du schon mit BDD-Szenarien, Issue-Templates mit Akzeptanzkriterien oder Design-Dokumenten gearbeitet hast. Das spezifische Format ist weniger wichtig als die richtigen Informationen in einem teilen- und prüfbaren Format.

Wo Specs im Workflow leben

Das Beste an Specs ist ihre Flexibilität. Sie müssen keine separaten Dokumente sein, die dich ausbremsen. Eine Spec kann überall leben, wo es für dein Team sinnvoll ist:

• Ein GitHub Issue mit expliziten Akzeptanzkriterien
• Eine PR-Beschreibung, die das geänderte Verhalten benennt
• Ein BDD-Szenario in deinen Feature-Dateien
• Eine lightweight Design-Notiz vor der Implementierung
• Tools wie OpenSpec oder GitHub Spec Kit, die dieses Pattern formalisieren

Der Kern ist: Kontext und Prüfkriterien müssen sichtbar und persistent sein. Deine Spec sollte nicht verschwinden, wenn die Chat-Session endet. Sie sollte die Arbeit begleiten und Kollegen etwas Konkretes zum Evaluieren geben.

Die Assignment Layer: Intent von Execution trennen

Hier wird es richtig interessant.

Die stärksten Specs funktionieren wie kleine Behavior-Verträge. Sie trennen drei distincte Fragen:

1. Welches Verhalten soll sich ändern? (Die Anforderung)
2. Welche Grenzen oder Beispiele definieren Korrektheit? (Die Akzeptanzkriterien)
3. Welcher Implementierungsweg scheint gerade sinnvoll? (Der technische Ansatz)

Diese Fragen hängen zusammen, sollten aber nicht zu einem einzigen Informationshaufen verschmelzen.

Warum ist das bei KI-Coding-Agenten so wichtig? Weil der Agent, wenn du Intent und Implementierung zu früh vermischst, für das falsche Ziel optimieren kann. Er folgt vielleicht gewissenhaft einem vorgeschlagenen Implementierungsdetail, verfehlt aber das eigentliche Verhalten, das du wolltest. Oder er produziert Code, der technisch interessant ist, aber das formulierte Problem nicht löst.

Eine Assignment Layer hält die Anforderung stabil, während die Implementierung sich entwickeln darf. Wenn der Agent die Codebasis liest, Komplikationen entdeckt und seinen Ansatz verfeinert – die Spec bleibt der Anker: „Hat die Arbeit das erfüllt, was wir wollten?"

Das ist besonders wertvoll für bestehende Codebases. Die meiste Entwicklungsarbeit ist kein Greenfield – du veränderst Verhalten, das bereits existiert. Eine gute Spec sagt: So verhält sich der Code aktuell, und so soll er sich ändern. Reviewer müssen dann nicht erst deinen Intent aus Implementierungsdetails rekonstruieren.

Den Shift machen

Wenn du KI-Coding-Agenten gewöhnt bist wie supergeladene Suchmaschinen zu behandeln, könnte sich das hier nach Overthinking anfühlen. Aber bedenk die Alternative: Unkontrollierte Änderungen an shared Code, PRs, die schwer zu reviewen sind, und Arbeit, die nicht ganz passt.

Der Shift hin zu spec-getriebener KI-Zusammenarbeit geht nicht um Bürokratie. Es geht darum, sowohl Menschen als auch Maschinen die Klarheit zu geben, die sie für effektive Zusammenarbeit brauchen.

Fang klein an. Das nächste Mal, wenn du einen KI-Coding-Agenten auf ein Repository loslassen willst – nimm dir fünf Minuten und schreib auf: den Kontext, die Verhaltensänderung und die Erfolgskriterien. Leg es irgendwo ab, wo es sichtbar ist – selbst wenn es nur die PR-Beschreibung ist.

Dein zukünftiges Ich (und deine Kollegen) werden es dir danken.

Fazit: KI-Coding-Agenten sind mächtige Collaborators. Behandle sie wie Collaborators. Gib ihnen ein ordentliches Briefing, und du bekommst Arbeit, die sich zu reviewen lohnt.