Erst die Spezifikation, dann der Code: wie ich KI-Agenten mit OpenSpec steuere

Teil 1 von 3 der Serie „KI-Entwicklung mit Leitplanken“. Teil 2 (Kontextdateien) erscheint am 5. November, Teil 3 (automatische Qualitätsprüfungen) am 12. November.

Am 17. Oktober 2023 habe ich bauernjobs.de gestartet: eine Jobplattform für die deutsche Landwirtschaft. Landwirte schreiben Stellen aus, Saisonkräfte aus Rumänien, Polen, Bulgarien oder der Ukraine bewerben sich und schreiben den Betrieben direkt. Jede Nachricht wird automatisch übersetzt. Die Plattform läuft in acht Sprachen, mit Stripe-Zahlungen, Job-Alerts per E-Mail und einem Filament-Adminbereich.

Fast der gesamte Code ist mit KI entstanden. Anfangs mit Chat-Assistenten und Copy-and-paste, später mit Agenten, die direkt im Repository arbeiten. Ich habe über 14 Jahre PHP von Hand geschrieben. Bei bauernjobs.de wollte ich wissen, wie weit man kommt, wenn man die KI schreiben lässt.

Die ehrliche Antwort: sehr weit. Und dann kommt ein Punkt, an dem es kippt.

Wo es kippt

Am Anfang ist alles schnell. Sie beschreiben eine Funktion im Chat, der Agent baut sie, Sie testen kurz im Browser, fertig. Die Commit-Historie von bauernjobs.de zeigt das deutlich: 89 Commits im Jahr 2024, 99 im Jahr 2025, 390 bis Oktober 2026.

Das Problem ist nicht die Geschwindigkeit. Das Problem ist, dass die Absicht nirgends steht. Was eine Funktion tun soll, steht nur im Chatverlauf, und der ist nach der Sitzung weg. Beim nächsten Mal liest der Agent den Code und schließt daraus, was gewollt war. Ist der Code falsch, lernt er das Falsche.

Ein konkretes Beispiel aus bauernjobs.de: Ein täglicher Befehl sollte Stellenanzeigen nach 60 Tagen deaktivieren. Er lief jeden Tag, ohne Fehler, monatelang. Beim Nachlesen stellte sich heraus:

• er rechnete mit 30 statt 60 Tagen,
• er setzte eine Spalte, die für die Sichtbarkeit gar keine Rolle spielte,
• und die Zeile, die speichert, war auskommentiert.

Der Befehl tat also nichts. Aufgefallen ist das nur, weil die Sichtbarkeit zufällig an anderer Stelle über das Datum geregelt war. Kein Test, kein Fehler im Log, kein Kunde hat sich beschwert. So sieht KI-Code aus, wenn niemand aufgeschrieben hat, was er tun soll.

Was OpenSpec ist

OpenSpec ist ein kleines Werkzeug für spezifikationsgetriebene Entwicklung mit KI-Agenten. Im Repository liegt ein Ordner openspec/ mit zwei Teilen:

• specs/: was das System heute tut, pro Fähigkeit eine Datei. Bei bauernjobs.de sind das 27 Bereiche, von listing-payments über message-translation bis gdpr-compliance.
• changes/: was sich ändern soll. Jede Änderung ist ein eigener Ordner mit Begründung, Spezifikations-Delta, Design und Aufgabenliste.

Die Spezifikationen sind in einfacher Sprache geschrieben, mit Anforderungen und Szenarien im Format „WENN … DANN …“. Kein UML, kein Pflichtenheft mit 80 Seiten.

Der Ablauf: Propose, Apply, Archive

Jede Änderung durchläuft drei Schritte, die ich als Befehle im Agenten aufrufe.

1. Propose: planen, nicht programmieren

Ich beschreibe, was ich will. Der Agent liest Code, bestehende Spezifikationen und den Projektkontext und legt vier Dateien an:

• proposal.md: warum und was, inklusive dessen, was ausdrücklich nicht Teil der Änderung ist,
• specs/…/spec.md: das Delta, also welche Anforderungen hinzukommen, sich ändern oder entfallen,
• design.md: wie, mit den technischen Entscheidungen und ihren Alternativen,
• tasks.md: kleine, prüfbare Aufgaben.

Der wichtigste Satz in diesem Schritt: Es wird kein Code geändert. Der Agent plant nur. Ich lese den Vorschlag, streiche, ergänze und entscheide. Erst dann wird gebaut.

Das klingt nach Bürokratie. In der Praxis dauert ein Vorschlag fünf bis fünfzehn Minuten. Und genau in diesen Minuten fallen die Missverständnisse auf, die sonst erst nach dem Deployment auffallen.

2. Apply: umsetzen gegen eine Checkliste

Der Agent arbeitet tasks.md ab, Aufgabe für Aufgabe, und hakt ab. Weil die Anforderungen als Szenarien formuliert sind, ergeben sich die Tests fast von selbst: Jedes „WENN … DANN …“ wird ein Testfall.

Wenn eine Sitzung abbricht oder der Kontext voll ist, steht in tasks.md, wo es weitergeht. Der nächste Agent muss nicht raten.

3. Archive: die Wahrheit nachziehen

Ist die Änderung fertig und geprüft, wird sie archiviert. Dabei wandert das Delta in die Hauptspezifikation. specs/ beschreibt danach wieder genau das, was das System tut. Die Änderung selbst bleibt mit Datum im Archiv, als Protokoll der Entscheidung.

Was sich bei bauernjobs.de geändert hat

Ich habe OpenSpec im Juni 2026 eingeführt. Der erste Schritt war nicht eine neue Funktion, sondern eine Bestandsaufnahme: Der Agent hat den vorhandenen Code gelesen und beschrieben, was er tatsächlich tut. Wo das von dem abwich, was gewollt war, wurde daraus ein Änderungsvorschlag.

Allein am 7. Juni 2026 sind auf diese Weise 17 Änderungen entstanden und abgeschlossen worden: eine Sicherheitslücke bei der Eingabeverarbeitung, Lücken im Nachrichtensystem, fehlende Datenbankindizes, gefälschte Beispielanzeigen, die zu ehrlich gekennzeichneten Beispielen wurden. Der Befehl, der nichts deaktivierte, war einer davon.

Im September 2026 kam ein vollständiges Audit dazu. Das Ergebnis ist eine Roadmap mit einer klaren Reihenfolge: erst die Testumgebung reparieren, dann Zahlungen absichern, dann E-Mail-Zustellung, erst danach neue Funktionen. Jeder Schritt verweist auf einen Änderungsordner. Der Agent weiß, woran er arbeitet und was er noch nicht anfassen darf.

Zwei Regeln aus dieser Roadmap haben sich besonders bewährt:

• Offene Entscheidungen werden als offen markiert. Bei Preisen oder Kundenbewertungen steht ausdrücklich: Nicht ohne meine Bestätigung ändern, keine erfundenen Zahlen einsetzen. KI-Modelle füllen Lücken gerne mit plausiblen Werten. Eine geschriebene Regel verhindert das.
• Ein abgehakter Task ist kein Testergebnis. Erledigt ist etwas erst, wenn die Prüfungen laufen. Mehr dazu in Teil 3.

Was Sie daraus mitnehmen können

Sie müssen nicht OpenSpec verwenden. Das Prinzip funktioniert mit jedem Werkzeug:

1. Schreiben Sie auf, was das System heute tut, bevor Sie es ändern lassen. Allein dabei finden Sie Fehler.
2. Trennen Sie Planen und Bauen. Lassen Sie den Agenten erst einen Vorschlag schreiben, lesen Sie ihn, und geben Sie dann frei.
3. Halten Sie fest, was nicht passieren soll. Ein Abschnitt „Nicht Teil dieser Änderung“ spart mehr Zeit als jeder clevere Prompt.
4. Ziehen Sie die Spezifikation nach. Eine Spezifikation, die nicht mehr stimmt, ist schlimmer als keine.

KI schreibt Code schneller als jeder Mensch. Was sie nicht kann: wissen, was Sie wollen, wenn Sie es nicht aufgeschrieben haben.

Im nächsten Teil (ab 5. November) geht es um die Dateien, die der Agent bei jeder Sitzung zuerst liest, und warum eine veraltete Kontextdatei gefährlicher ist als gar keine.

Sie setzen KI in der Entwicklung ein und merken, dass die Qualität abdriftet? Als Fractional Tech Lead richte ich diesen Ablauf in Ihrem Team ein: Spezifikationen, Kontextdateien und Prüfungen, die verhindern, dass schneller Code zu teurem Code wird. Erstgespräch buchen