Vibe Coding mit Leitplanken: Tickets als Vertrag mit dem Coding-Agent

Vibe Coding ist erstaunlich gut darin, den Abstand zwischen einer Idee und lauffähigem Code auf wenige Minuten zu verkürzen. Es ist deutlich schlechter darin, sich zwei Wochen später daran zu erinnern, warum eine bestimmte Entscheidung getroffen wurde, welche Randbedingungen galten und was bei der Umsetzung bewusst nicht angefasst werden sollte.

Bei einem kleinen Prototyp ist das noch kein Problem. Man beschreibt im Chat, was man haben möchte, lässt den Agenten ein paar Dateien anlegen und korrigiert, was nicht passt. Der Chatverlauf ist gleichzeitig Anforderung, Planung und Dokumentation.

Mit wachsendem Projekt funktioniert das immer schlechter. Gespräche werden länger, neue Sessions beginnen ohne den alten Kontext und verschiedene Modelle interpretieren dieselbe Anforderung unterschiedlich. Irgendwann behebt der Agent beim Einbau eines Buttons nebenbei noch die API-Struktur, tauscht eine Bibliothek aus und räumt drei Module auf, obwohl davon nie die Rede war.

Das Problem ist dabei nicht unbedingt die Qualität des Modells. Es fehlt ein dauerhafter, überprüfbarer Arbeitsauftrag.

Meine Lösung dafür sind Tickets direkt im Repository. Keine reine Aufgabenliste in Jira und auch kein Prompt, der nach Ende der Session verschwindet, sondern versionierte Markdown-Dateien, die gemeinsam mit dem Code durch den Entwicklungsprozess wandern.

Das klingt zunächst nach dem Gegenteil von Vibe Coding. Gerade diese kleine Reibung ist aber der entscheidende Punkt.

Der Chat ist kein Projektgedächtnis

Ein Coding-Agent kann viel Kontext verarbeiten. Das bedeutet noch lange nicht, dass ein Chatverlauf eine gute Spezifikation ist.

In einem typischen Gespräch entstehen Anforderungen schrittweise:

Bau einen CSV-Export ein.

Später kommt dazu:

Er soll natürlich die aktuellen Filter berücksichtigen.

Dann:

Aber nur für Daten, die der Benutzer auch in der Oberfläche sehen darf.

Und irgendwann:

Bitte keine neue CSV-Bibliothek einführen, wir haben bereits eine Utility dafür.

Für einen Menschen ist aus dem Gespräch ungefähr klar, was gemeint ist. Für einen Agenten sind es vier Nachrichten mit unterschiedlicher Priorität. Vielleicht hat er zwischenzeitlich schon eine Lösung implementiert, die auf der ersten Nachricht basiert. Vielleicht befindet sich die relevante Information inzwischen ausserhalb des geladenen Kontextfensters. Vielleicht wird die Arbeit in einer neuen Session fortgesetzt.

Ein Ticket fasst diese Diskussion zu einem eindeutigen Arbeitsauftrag zusammen. Es ist nicht einfach eine Kopie des Prompts, sondern dessen bereinigte und überprüfte Form.

Oder kürzer: Das Ticket ist der Prompt, der die Session überlebt.

Ein Kanban-Board aus Verzeichnissen

Das Grundmodell ist bewusst simpel:

tickets/
├── open/
├── in-progress/
└── done/

Ein neues Ticket beginnt unter tickets/open/. Sobald die Umsetzung startet, wird die Datei nach tickets/in-progress/ verschoben. Nach Review und Merge landet sie unter tickets/done/.

Der Status steckt damit nicht nur in einem Feld innerhalb der Datei, sondern auch im Dateipfad. Git protokolliert, wann ein Ticket erstellt, begonnen, verändert und abgeschlossen wurde.

Zu jedem Ticket gehört ein eigener Feature-Branch:

feature/APP-42-csv-export

Auf diesem Branch liegen sowohl der Code als auch die dazugehörige Ticketversion. Wird die Anforderung während der Umsetzung präzisiert, ist auch diese Änderung in der Git-Historie sichtbar.

Das ist ein wichtiger Unterschied zu einem externen Ticketsystem. Ein Coding-Agent braucht keine zusätzliche API, keine Zugangsdaten und keine spezielle Integration. Er kann das Ticket mit denselben Werkzeugen lesen wie den restlichen Quellcode.

Was in ein Ticket gehört

Ein gutes Ticket muss dem Agenten genügend Kontext geben, ohne bereits jeden einzelnen Codeblock vorwegzunehmen. Es sollte vor allem fünf Fragen beantworten:

Welches Problem soll gelöst werden?
Woran ist erkennbar, dass es gelöst ist?
Was gehört ausdrücklich nicht dazu?
Welche technischen Leitplanken sind verbindlich?
Wie wird die Umsetzung überprüft?

Ein einfaches Ticket kann beispielsweise so aussehen:

# APP-42: Gefilterte Bestellungen als CSV exportieren

**Status:** open
**Type:** feature
**Created:** 2026-07-28
**Branch:** —
**Estimated effort:** medium

## Motivation

Mitarbeiter im Support müssen die aktuell angezeigten Bestellungen
regelmässig für eine externe Auswertung exportieren. Derzeit kopieren
sie die Daten manuell aus der Oberfläche.

Der Export soll exakt den Datenbestand enthalten, den der Benutzer
mit den aktuellen Filtern, der Sortierung und seinen Berechtigungen
in der Oberfläche sieht.

## Akzeptanzkriterien

- [ ] In der Ergebnisansicht gibt es eine Aktion „Als CSV exportieren“.
- [ ] Der Export berücksichtigt die aktiven Filter.
- [ ] Der Export verwendet die aktuelle Sortierung.
- [ ] Es werden nur Datensätze exportiert, auf die der Benutzer Zugriff hat.
- [ ] Die CSV-Datei ist UTF-8-kodiert und enthält eine stabile Kopfzeile.
- [ ] Bei einem fehlgeschlagenen Export erscheint eine verständliche Fehlermeldung.
- [ ] Backend- und Frontend-Tests werden ergänzt.
- [ ] Der Changelog wird aktualisiert.

## Out of scope

- Geplante oder wiederkehrende Exporte
- Versand der Datei per E-Mail
- XLSX- oder PDF-Export
- Änderungen am Berechtigungskonzept

## Technische Leitplanken

- Die bestehende Berechtigungsprüfung im OrderQueryService muss verwendet werden.
- Berechtigungen dürfen nicht im Frontend nachgebaut werden.
- Für die CSV-Erzeugung ist die vorhandene CsvWriter-Utility zu verwenden.
- Der Export muss auch bei grossen Ergebnismengen ohne vollständiges Laden
  aller Datensätze in den Arbeitsspeicher funktionieren.

## Designfragen

- Soll der Dateiname das aktuelle Datum enthalten?
- Benötigt Excel in der Zielumgebung ein UTF-8-BOM?

## Relevante Dateien

- `src/orders/OrderQueryService.ts`
- `src/orders/OrderController.ts`
- `src/ui/orders/OrderList.tsx`
- `tests/orders/`

Die Motivation beschreibt das Problem aus Sicht des Benutzers. Die Akzeptanzkriterien definieren beobachtbares Verhalten. Der Abschnitt Out of scope verhindert, dass der Agent aus einem CSV-Export gleich ein allgemeines Reporting-System macht.

Die technischen Leitplanken enthalten nur Entscheidungen, die für das Projekt wirklich relevant sind. Sie schreiben nicht vor, wie jede Funktion heissen muss. Der Agent soll weiterhin eine passende Umsetzung finden können.

Akzeptanzkriterien statt vager Ziele

Der wichtigste Teil eines Tickets sind nicht die technischen Hinweise, sondern die Akzeptanzkriterien.

Eine Formulierung wie „Der Export soll zuverlässig funktionieren“ klingt vernünftig, ist aber nicht überprüfbar. Der Agent kann praktisch jede Implementierung als zuverlässig bezeichnen.

Besser sind konkrete Aussagen:

- [ ] Bei HTTP 429 wird der Wert aus dem Retry-After-Header berücksichtigt.
- [ ] Ohne Retry-After-Header wird ein exponentielles Backoff verwendet.
- [ ] Nach drei erfolglosen Versuchen wird kein weiterer Request gesendet.
- [ ] Der Fehler enthält den Namen des aufgerufenen Dienstes.

Damit ist klar, welche Fälle implementiert und getestet werden müssen.

Akzeptanzkriterien sollten möglichst das Verhalten beschreiben, nicht die gewünschte Implementierung. „Die Methode retryRequest() wird in Datei X angelegt“ ist meistens kein Akzeptanzkriterium. „Nach drei fehlgeschlagenen Versuchen wird der Aufruf beendet“ dagegen schon.

Die Trennung ist wichtig, weil ein Ticket sonst sehr schnell zu Source Code in Prosa wird. Das nimmt dem Agenten nicht nur sinnvolle Freiheit, sondern konserviert möglicherweise eine Lösung, die beim Schreiben des Tickets lediglich plausibel erschien.

Ein schlechtes Ticket erzeugt im schlimmsten Fall ein sehr präzise implementiertes Missverständnis.

Planung und Umsetzung bewusst trennen

Der Ticketprozess beginnt nicht mit dem Schreiben von Code.

In der ersten Phase darf der Agent das Repository untersuchen, bestehende Architekturentscheidungen lesen und einen Ticketentwurf erstellen. Er soll dabei offene Fragen erkennen, betroffene Komponenten benennen und mögliche Risiken festhalten. Änderungen am Produktcode sind in dieser Phase nicht vorgesehen.

Danach prüfe ich das Ticket selbst.

Stimmt die beschriebene Motivation? Sind die Akzeptanzkriterien vollständig? Hat der Agent eine Annahme als Tatsache dargestellt? Ist der Scope noch klein genug für einen überschaubaren Pull Request?

Erst wenn diese Fragen geklärt sind, beginnt die eigentliche Umsetzung. Dafür kann sogar eine neue Session verwendet werden. Der neue Agent benötigt nicht den gesamten vorherigen Chatverlauf. Er liest die Projektregeln, das Ticket und den relevanten Code.

Diese Trennung verhindert, dass ein Agent während einer unsauberen Diskussion bereits Fakten schafft. Gleichzeitig zwingt sie mich dazu, Anforderungen einmal vollständig zu formulieren, bevor mehrere hundert Zeilen Code entstehen.

Der Ticket-Lebenszyklus

Der Ablauf sieht in der Praxis ungefähr so aus:

1. Ticket erstellen

Das Ticket wird unter tickets/open/ angelegt. Zu diesem Zeitpunkt enthält es noch keinen Branch und keine Implementierungsdetails, die erst durch die Arbeit entstehen können.

2. Ticket prüfen

Vor Beginn der Umsetzung wird das Ticket manuell gelesen. Offene Designfragen müssen geklärt oder ausdrücklich als Entscheidungsspielraum markiert sein.

Besonders wichtig ist der Abschnitt Out of scope. Coding-Agents sind häufig sehr hilfsbereit. Genau das kann zum Problem werden, wenn sie neben der eigentlichen Aufgabe noch Refactorings, Dependency-Updates oder Architekturänderungen durchführen.

3. Feature-Branch anlegen

Die Arbeit startet immer vom aktuellen Hauptbranch. Der Agent erstellt einen Branch mit der Ticketnummer und einem kurzen Namen.

Anschliessend verschiebt er das Ticket nach tickets/in-progress/ und trägt den Branch in die Metadaten ein.

4. Nur den Ticket-Scope umsetzen

Der Agent darf angrenzende Probleme dokumentieren, aber nicht automatisch mitlösen. Ein entdecktes Folgeproblem wird entweder als neues Ticket erfasst oder zuerst mit mir besprochen.

Das schützt nicht nur vor unnötigen Änderungen. Es macht auch den späteren Review erheblich einfacher, weil der Diff tatsächlich zur beschriebenen Aufgabe gehört.

5. Tests und Dokumentation aktualisieren

Tests sind Bestandteil des Tickets und keine freiwillige Abschlussarbeit.

Ändert ein Ticket öffentliches Verhalten, muss auch die entsprechende Dokumentation angepasst werden. Ändert es eine dauerhafte Architekturregel, gehört diese nicht ausschliesslich in das Ticket, sondern in die Architekturdokumentation oder ein ADR.

Das Ticket beschreibt einen einzelnen Change. Es darf nicht zum einzigen Ort werden, an dem dauerhaft relevantes Wissen steht.

6. Arbeit stoppen und Bericht liefern

Nach der Implementierung soll der Agent nicht selbstständig den Hauptbranch aktualisieren. Er stoppt auf dem Feature-Branch und nennt:

den Branch,
den letzten Commit,
die ausgeführten Tests,
bekannte Einschränkungen,
verbleibende Risiken.

Der Merge bleibt eine bewusste menschliche Entscheidung.

Das ist für mich eine der wichtigsten Leitplanken des gesamten Prozesses. Der Agent darf weitgehend selbstständig arbeiten, aber nicht selbst entscheiden, dass seine eigene Arbeit ausreichend geprüft wurde.

7. Review, Merge und Abschluss

Nach dem Review wird der Branch gemergt. Erst danach wandert das Ticket nach tickets/done/.

Damit bleibt klar, dass „Code geschrieben“ und „Änderung abgeschlossen“ nicht dasselbe sind.

Drei Ebenen von Kontext

Repository-lokale Tickets funktionieren besonders gut, wenn die Informationen sauber auf verschiedene Ebenen verteilt werden.

Eine Datei wie AGENTS.md enthält die dauerhaften Regeln des Projekts. Dort stehen beispielsweise Architekturprinzipien, Testbefehle, verbotene Abkürzungen, Namenskonventionen und der Umgang mit externen Bibliotheken.

Das Ticket enthält nur den aktuellen Arbeitsauftrag. Es beschreibt Motivation, Scope, Akzeptanzkriterien und die für diese Änderung relevanten Leitplanken.

Tests und CI bilden schliesslich die ausführbare Kontrolle. Sie überprüfen zumindest einen Teil dessen, was im Ticket versprochen wurde.

Ergänzend dokumentiert ein Changelog das sichtbare Ergebnis, während ADRs grössere Architekturentscheidungen festhalten.

Diese Aufteilung verhindert zwei Extreme: Ein gigantisches globales Regelwerk, das bei jeder Aufgabe vollständig geladen werden muss, und Tickets, die bei jeder Änderung die gesamte Projektarchitektur neu erklären.

Was an dem Ansatz gut funktioniert

Der grösste Vorteil ist der dauerhafte Kontext. Eine neue Session oder ein anderes Modell kann die Arbeit übernehmen, ohne dass ich den bisherigen Chat rekonstruieren muss. Das Ticket liegt auf dem Branch und beschreibt den Stand, auf den sich der Code bezieht.

Ebenso wichtig ist die Scope-Kontrolle. Ein klarer Out of scope-Abschnitt ist überraschend wirksam gegen gut gemeinte Seiteneffekte. Der Agent kann weiterhin auf Probleme hinweisen, darf sie aber nicht einfach in denselben Change aufnehmen.

Auch Reviews werden leichter. Anstatt einen Diff nur nach allgemeinem Eindruck zu beurteilen, kann ich ihn gegen konkrete Akzeptanzkriterien prüfen. Fehlt ein Fehlerfall oder wurde eine Randbedingung ignoriert, lässt sich das direkt benennen.

Ein weiterer Vorteil ist die Nachvollziehbarkeit. Ticket, Branch, Commits, Tests und Dokumentationsänderungen gehören sichtbar zusammen. Wird ein Kriterium während der Umsetzung geändert, bleibt auch das in Git erhalten.

Das System ist ausserdem weitgehend werkzeugunabhängig. Ob der Code mit Claude Code, Codex, einem IDE-Agenten oder einem lokalen Modell bearbeitet wird, spielt für das Ticketformat keine Rolle. Markdown kann praktisch jedes Werkzeug lesen.

Für Solo-Projekte und kleine Teams ist auch die Einfachheit angenehm. Es braucht kein zusätzliches Board, keine Automationen und keine Synchronisation zwischen mehreren Systemen.

Schliesslich hält der manuelle Merge die Verantwortung beim Menschen. Der Agent bekommt einen grossen Handlungsspielraum innerhalb des Branches, aber keine automatische Freigabe für den produktiven Codebestand.

Wo das System an seine Grenzen kommt

So einfach das Modell ist, so einfach kann es auch inkonsistent werden.

Eine Datei kann bereits unter tickets/done/ liegen und intern noch Status: in-progress enthalten. Die Akzeptanzkriterien können weiterhin ungeprüft sein. Git verhindert das nicht. Ohne zusätzliche Validierung sind Verzeichnis, Metadaten und Checkboxen lediglich Konventionen.

Das lässt sich mit einem kleinen CI-Skript verbessern. Es kann beispielsweise prüfen, ob Tickets unter done/ den richtigen Status besitzen, keine offenen Kriterien mehr enthalten und einen zugehörigen Changelog-Eintrag haben. Vollständig lösen lässt sich das Problem damit trotzdem nicht. Eine angekreuzte Checkbox beweist noch nicht, dass ein Kriterium wirklich erfüllt wurde.

Der zweite Nachteil ist der zusätzliche Aufwand. Für eine Änderung von zwei Zeilen lohnt sich kein mehrseitiges Ticket. Wer jede Kleinigkeit in denselben Prozess zwingt, baut sich schnell eine private Bürokratie.

Es braucht daher eine sinnvolle Untergrenze. Ein offensichtlicher Tippfehler oder eine kleine Konfigurationskorrektur kann direkt erledigt werden. Sobald eine Änderung mehrere Dateien betrifft, neues Verhalten einführt oder eine Designentscheidung enthält, zahlt sich ein Ticket meistens aus.

Ein weiteres Risiko ist Ticket-Inflation. Coding-Agents können beeindruckend detaillierte Implementierungspläne schreiben. Ein grosses Ticket wächst dadurch schnell auf mehrere hundert Zeilen an, inklusive vorgeschlagener Klassen, Methodensignaturen und Beispielcode.

Mehr Text bedeutet aber nicht automatisch mehr Klarheit. Lange Tickets verbrauchen Kontext, werden schwer prüfbar und legen Lösungen fest, bevor der vorhandene Code vollständig verstanden wurde.

Ich behandle deshalb nur drei Arten von Aussagen als verbindlich:

das gewünschte Verhalten,
explizite Architekturregeln,
klar benannte technische Einschränkungen.

Ein Implementierungsplan ist dagegen zunächst ein Vorschlag. Stellt sich bei der Arbeit heraus, dass eine andere Lösung besser zur Codebasis passt, darf der Agent abweichen. Die Abweichung muss allerdings begründet und sichtbar gemacht werden.

Problematisch ist auch, wenn derselbe Agent das Ticket erstellt, implementiert und anschliessend selbst als erledigt bewertet. Dann besteht die Gefahr eines geschlossenen Bestätigungskreises. Ein Missverständnis aus der Planungsphase wird in Code übersetzt und danach anhand der selbst formulierten Kriterien für korrekt erklärt.

Die menschliche Prüfung des Tickets vor Beginn der Umsetzung ist deshalb keine Formalität. Sie ist der wichtigste Review im gesamten Ablauf.

Für grössere Teams fehlen dem dateibasierten Kanban ausserdem viele Funktionen klassischer Ticketsysteme: Zuweisungen, Benachrichtigungen, Abhängigkeiten, Priorisierung, Suchfilter, Dashboards und belastbare Auswertungen. Sobald mehrere Entwickler parallel planen und priorisieren, wird das Repository allein schnell unübersichtlich.

Mögliche Alternativen

Das Ticketmodell ist nicht für jede Situation die beste Lösung.

Nur im Chat arbeiten

Für einen Spike, ein Wegwerfskript oder einen sehr kleinen Prototyp ist ein formaler Workflow oft unnötig. Ein direkter Prompt ist schneller und hält die Einstiegshürde niedrig.

Die Grenze ist erreicht, sobald die Arbeit über mehrere Sessions geht oder Entscheidungen später nachvollziehbar sein müssen.

Ein gemeinsames `PLAN.md`

In der frühen Projektphase kann ein zentrales PLAN.md sinnvoller sein als viele einzelne Tickets. Es eignet sich gut für einen linearen MVP-Aufbau mit aufeinanderfolgenden Meilensteinen.

Mit der Zeit wird eine solche Datei allerdings immer länger. Abgeschlossene, aktuelle und zukünftige Arbeiten vermischen sich. Parallele Änderungen führen leichter zu Konflikten und einzelne Aufgaben besitzen keine eigene Historie.

Ein guter Zeitpunkt für den Wechsel zu Tickets ist erreicht, wenn der initiale Aufbau abgeschlossen ist und Änderungen zunehmend unabhängig voneinander umgesetzt werden.

GitHub Issues, Linear oder Jira

Für Teams sind klassische Ticketsysteme meistens überlegen. Sie bieten Zustände, Verantwortlichkeiten, Kommentare, Verknüpfungen und Automationen.

Der Nachteil für Coding-Agents ist die Trennung vom Repository. Das Werkzeug benötigt Zugriff auf das jeweilige System und muss das richtige Ticket aktiv laden. Ausserdem kann die Beschreibung im Issue von der tatsächlichen Implementierung auf dem Branch abweichen.

Eine brauchbare Kombination ist ein externes Issue für Diskussion, Priorisierung und Zusammenarbeit sowie eine kompakte Spezifikation im Repository für die konkrete Umsetzung. Beide werden miteinander verlinkt.

RFCs und ADRs

Bei grösseren Architekturänderungen reicht ein normales Feature-Ticket nicht aus. Wenn mehrere Systeme, Datenmodelle oder öffentliche Schnittstellen betroffen sind, sollte zuerst ein RFC oder ADR entstehen.

Die Architekturentscheidung wird dabei unabhängig von der Implementierung geprüft. Erst danach wird sie in kleinere Tickets zerlegt.

Das ist langsamer, verhindert aber, dass ein Coding-Agent eine weitreichende Systementscheidung innerhalb eines vermeintlich normalen Features trifft.

Tests als Ausgangspunkt

Bei klar reproduzierbaren Fehlern kann ein fehlgeschlagener Test die beste Spezifikation sein.

Zuerst wird ein Test geschrieben, der den Fehler sichtbar macht. Danach implementiert der Agent die kleinste Änderung, mit der der Test erfolgreich wird.

Das ist sehr effektiv, bildet aber nicht alle Anforderungen ab. Benutzerführung, Dokumentation, Performance, Sicherheit und bewusste Nicht-Ziele lassen sich nicht immer ausreichend durch einen einzelnen Test ausdrücken.

Der sinnvollste Ansatz ist meistens hybrid

In der Praxis kombiniere ich mehrere Ebenen:

Ein Ticketsystem oder eine einfache Liste dient der Priorisierung.
Das Markdown-Ticket im Repository bildet den konkreten Arbeitsauftrag.
AGENTS.md enthält dauerhafte Projektregeln.
ADRs dokumentieren grössere Entscheidungen.
Tests und CI kontrollieren die Umsetzung.
Der Pull Request bleibt die Review- und Freigabegrenze.

Damit muss kein einzelnes Werkzeug alles leisten.

Das Repository-Ticket ist vor allem die Schnittstelle zwischen Mensch und Coding-Agent. Es enthält genau den Kontext, den der Agent für diese Änderung benötigt, und bleibt gemeinsam mit dem Code versioniert.

Aus Vibe Coding wird nicht automatisch Engineering

Ein Ticketprozess macht eine schlechte Anforderung nicht gut. Er verhindert auch keine fehlerhafte Implementierung und ersetzt keinen Review.

Was er verändert, ist der Zeitpunkt, an dem Unklarheiten sichtbar werden.

Ohne Ticket tauchen sie meistens während oder nach der Implementierung auf. Mit Ticket müssen sie zumindest teilweise beantwortet werden, bevor der Agent loslegt.

Das kostet am Anfang ein paar Minuten. Bei grösseren Änderungen spart es dafür mehrere Runden aus Nachbesserungen, Seiteneffekten und Diskussionen darüber, was ursprünglich eigentlich gemeint war.

Der Agent darf innerhalb des Tickets weiterhin kreativ sein. Er kann bestehende Muster erkennen, passende Abstraktionen finden und eine bessere Lösung vorschlagen als die, die ich selbst im Kopf hatte. Er darf aber nicht unbemerkt das Ziel verändern, den Scope erweitern oder die eigene Arbeit freigeben.

Genau darin liegt für mich der Unterschied zwischen reinem Vibe Coding und AI Engineering: Nicht weniger Geschwindigkeit, sondern ein kontrollierter Rahmen dafür, wo Geschwindigkeit sinnvoll ist.