Warum dein KI-Coding-Agent ständig den Überblick verliert – und wie du das änderst

Du kennst das bestimmt. Du arbeitest mit einem KI-Assistenten über mehrere Tage an einem Projekt. Am ersten Tag läuft alles rund: API-Skelett steht, Tests laufen, Dokumentation ist sauber. Am nächsten Tag startet eine neue Session – und der Agent hat keine Ahnung mehr, was bisher passiert ist. Du erklärst alles von vorne. Am dritten oder vierten Tag wühlst du dich durch 70.000 Token Chat-Verlauf, nur um eine Entscheidung von vor zwei Sessions wiederzufinden.

Das Problem liegt nicht nur am Context Window. Es liegt daran, dass wir Projektzustände an der falschen Stelle speichern.

Chat als Speicher – eine schlechte Idee

Chats sind super für den Austausch. Als Projektarchiv taugen sie nicht.

• Entscheidungen verschwinden im Verlauf und lassen sich kaum wiederfinden.
• Es gibt keine verbindliche Quelle. Welche Version der API-Spezifikation gilt jetzt eigentlich?
• Jede neue Session startet bei null.
• Widersprüche häufen sich, weil niemand den Überblick behält.

Der eigentliche Flaschenhals bei KI-gestützter Entwicklung ist nicht die Code-Qualität. Es ist die Frage, ob der Agent wirklich versteht, was gebaut wird – und warum.

Die langweilige, aber wirksame Lösung

Die Antwort liegt auf der Hand: Projektzustände einfach als versionierte Dateien im Repository ablegen. Kein separates Tool, kein Wiki – nur strukturierte Markdown-Dateien mit wenigen Metadaten.

So könnte so eine Datei aussehen:

# Architekturentscheidung Projekt

Lifecycle: active
Role: spec
Project: payment-service
Updated: 2024-01-15

Related:
- implements: charter-payment-api
- pairs-with: implementation-log-payment-core

## Übersicht

Wir nutzen die direkte Stripe-API statt einer Wrapper-Bibliothek, weil...

## Wichtige Entscheidungen

- Idempotenz-Schlüssel bei allen Operationen
- Asynchrone Webhook-Verarbeitung mit Backoff
- PII niemals lokal speichern

## Offene Fragen

- Sollte der Rate-Limit-Status gecacht werden?

Keine komplizierte Syntax. Nur Titel, Metadaten, Beziehungen und Inhalt.

Ein kleines CLI-Tool kann damit umgehen: neue Einträge anlegen, alte archivieren, Beziehungen prüfen, einen Index erstellen. Alles ohne manuelle Pflege.

Warum das den Unterschied macht

Statt den Agenten durch den Chat-Verlauf zu jagen, gibst du ihm einfach einen Befehl:

docs list --project=payment-service --role=spec
docs check

Der Agent sieht sofort, was aktuell ist, was abgeschlossen wurde und wo es noch offene Punkte gibt. Und er kann den Zustand nicht nur lesen, sondern auch gezielt ändern – über klare Kommandos, nicht durch direktes Editieren von Dateien.

Beispiel:

docs create --role=log "Rate Limiting implementiert"
docs archive --record=spec-v2-deprecated

Das Tool sorgt dafür, dass Metadaten, Beziehungen und Index konsistent bleiben.

Frischer Agent, bekannter Zustand

Genau hier liegt der Vorteil: Eine neue Session bedeutet nicht mehr Kontextverlust. Der Agent startet, ruft docs list auf und weiß sofort, wo das Projekt steht. Kein Herumrätseln mehr. Der Chat wird austauschbar – der Zustand liegt im Repository.

Für wen das relevant ist

Das hilft vor allem bei:

• Mehr-Tage-Projekten mit KI-Pair-Programming
• Agenten-Workflows, die ohne vollständigen Kontext-Transfer weiterlaufen sollen
• CI/CD-Pipelines, die Projektkonsistenz prüfen müssen
• Teams, die eine gemeinsame Entscheidungsgrundlage brauchen
• Schnellen Iterationen, bei denen der aktuelle Stand schnell greifbar sein muss

Es ersetzt weder Git noch Tests. Es ist die fehlende Schicht, die KI-gestützte Entwicklung über mehrere Sessions hinweg sinnvoll macht.

Der unspektakuläre, aber entscheidende Punkt

Du baust kein neues System. Du nutzt nur Markdown, Git und ein CLI – Dinge, die ohnehin schon da sind. Genau das macht den Ansatz robust: Er ist langweilig genug, um zuverlässig zu funktionieren.