KI schreibt zu gut Code – diese Lösung bewahrt den Überblick

Die Geschwindigkeit von KI-Coding-Agenten ist atemberaubend. Innerhalb weniger Stunden entstehen aus einer vagen Idee funktionierende Prototypen mit Authentifizierung, Datenbank und Deployment. Tools wie Cursor, Claude Code oder Codex ermöglichen es Entwickler:innen, ganze Produkte an einem Nachmittag zu bauen – oder zumindest die Grundlage dafür zu legen.

Doch genau hier liegt das Problem: Die Tools sind zu gut darin, Code zu generieren, aber sie vergessen die Entscheidungen dahinter.

Wer in einem Chat-Thread mit einem Agenten arbeitet, trifft unzählige kleine Entscheidungen: Welche Authentifizierungsmethode? Welche Datenbank? Wie definiert man „fertig“ für ein Feature? Diese Überlegungen werden oft nur flüchtig festgehalten – in einem Thread, der nach dem Session-Ende verschwinden kann, oder in Notizen, die niemand mehr findet. Das Ergebnis: Ein funktionierender Code, aber ohne klare Dokumentation der Architektur. Und genau das bremst Projekte aus, sobald das Team wächst oder neue Entwickler:innen dazukommen.

Um dieses Problem zu lösen, habe ich Persist OS entwickelt – ein Open-Source-CLI-Tool, das diese Entscheidungen direkt in deinem Repository speichert und mit klaren Regeln durchsetzt. Ohne Cloud-Dienste, ohne Telemetrie, ohne zusätzliche KI-Aufrufe.

Warum Chat-Verlauf keine verlässliche Quelle ist

Die meisten KI-Entwicklungsumgebungen behandeln Chat-Verläufe als einzige Wissensbasis. Doch diese sind flüchtig: Sie werden gelöscht, komprimiert oder gehen im Tagesgeschäft unter. Persist OS dreht dieses Prinzip um: Das Repository wird zur zentralen Instanz für Architektur-Entscheidungen, Konventionen und Qualitätsstandards.

Jede Session startet nicht bei Null, sondern mit dem vollständigen Kontext der vorherigen Arbeit. Akzeptierte ADRs (Architecture Decision Records), Modulverantwortlichkeiten und technische Richtlinien werden automatisch geladen. Falls es Konflikte zwischen Chat-Anweisungen und Repository-Regeln gibt, stoppt der Agent – statt stillschweigend eine Entscheidung zu treffen.

So strukturiert Persist OS dein Repository

Ein einfacher Befehl genügt, um das gesamte Framework zu initialisieren:

npx persist-os@latest init

Es erstellt eine klare Ordnerstruktur unter docs/ und eine Konfiguration in .persist/config.json. Die wichtigsten Komponenten sind:

• `docs/00-product/` – Produktvision, Roadmap, PRD (Product Requirements Document)
• `docs/10-architecture/` – Technologie-Stack, Systemgrenzen, Architekturentscheidungen
• `docs/20-security/` – Bedrohungsmodell und Sicherheitsrichtlinien
• `docs/30-modules/` – Verantwortlichkeiten pro Modul
• `docs/40-features/` – Features mit PRD, Akzeptanzkriterien und Testplänen
• `docs/50-quality/` – Qualitätsstandards und Gate-Kriterien
• `docs/60-engineering/` – Entwicklungskonventionen und Agenten-Regeln
• `docs/adrs/` – Architekturentscheidungen (vorgeschlagen und akzeptiert)

Zusätzlich generiert Persist OS Dateien, die KI-Agenten direkt nutzen können:

• `AGENTS.md` – Anweisungen für den Agenten, welche Regeln er einhalten muss
• `CLAUDE.md` – Spezifische Anweisungen für Claude Code („Lies AGENTS.md, vertraue nicht dem Chat“)
• `.cursor/rules/persist-memory.mdc` – Eine Always-Apply-Regel für Cursor
• `.persist/hooks/pre-commit` – Ein Hook, der vor jedem Commit persist doctor ausführt

Für gängige Tech-Stacks wie Next.js, Python FastAPI oder Laravel-React gibt es vorkonfigurierte Vorlagen. Jede Entscheidung bleibt zunächst als „vorgeschlagen“ markiert, bis sie explizit akzeptiert wird – so vermeidest du, dass Standardvorgaben unbemerkt zur Regel werden.

Ein Beispiel: Ein Checkout-Flow in einem Tag

Angenommen, du willst für eine:n Freund:in einen einfachen Checkout-Prozess bauen – schnell, aber mit nachhaltiger Dokumentation. So geht’s mit Persist OS:

1. Grundgerüst vor dem ersten Codezeile erstellen

persist feature create checkout

Dieser Befehl erzeugt einen Ordner docs/40-features/F-###-checkout/ mit allen notwendigen Dokumenten: PRD, Akzeptanzkriterien, Testplan und eine Aufgabenliste. Der Agent soll nicht sofort in den Code springen, sondern erst die Anforderungen klar definieren.

2. Entscheidungen als Vorschläge festhalten und akzeptieren

persist adr create payment-provider

Ein neuer Eintrag im Ordner docs/adrs/proposed/ wird erstellt. Mit

persist adr accept payment-provider

wird die Entscheidung formal akzeptiert und in den Hauptordner docs/adrs/ verschoben. So bleibt nachvollziehbar, wer wann welche Wahl getroffen hat – und warum.

3. Agenten-Regeln für jede Session laden

Die generierte AGENTS.md-Datei enthält klare Anweisungen für den Agenten:

• Repository-Regeln haben Vorrang vor Chat-Anweisungen.
• Bei Konflikten muss der Agent stoppen und den Widerspruch melden.
• Vor der Fertigstellung einer Aufgabe muss persist doctor erfolgreich durchlaufen.

In Claude Code wird bei jedem Session-Start eine Live-Karte der akzeptierten ADRs und Module angezeigt. In Cursor gilt die Always-Apply-Regel. Codex liest AGENTS.md direkt. Alle Tools nutzen denselben Kontext – ohne manuelles Nachfragen.

4. „Fertig“ bedeutet: Nachweis statt Bauchgefühl

Bevor der Agent behaupten darf, eine Funktion sei abgeschlossen, muss er folgende Schritte durchlaufen:

pnpm test:run && pnpm typecheck && persist doctor

persist doctor überprüft, ob alle Qualitätsstandards eingehalten wurden und ob die Dokumentation mit dem Code übereinstimmt. Erst dann gilt ein Feature als wirklich fertig.

Warum das Tool die Entwicklung beschleunigt – statt sie zu bremsen

Persist OS zwingt dich nicht, langsamer zu arbeiten. Im Gegenteil: Es ermöglicht dir, die Geschwindigkeit der KI-Agenten zu nutzen, ohne die Kontrolle über die Architektur zu verlieren.

Das Tool ist bewusst einfach gehalten:

• Keine Cloud-Abhängigkeiten – alles läuft lokal.
• Keine Telemetrie – deine Daten bleiben bei dir.
• Keine versteckten KI-Aufrufe – nur das, was du explizit erlaubt hast.

Es ist eine Investition in die Zukunft deines Projekts: Jede Entscheidung, jede Konvention und jeder Qualitätsstandard ist dokumentiert und durchsetzbar. Das spart Zeit, wenn neue Teammitglieder einsteigen, und verhindert, dass technische Schulden unbemerkt entstehen.

Die Zukunft des KI-Codings wird hybrid sein: Tools wie Cursor oder Claude Code liefern den Code, Persist OS sorgt dafür, dass die Entscheidungen dahinter nicht verloren gehen. Es ist die perfekte Ergänzung für alle, die Geschwindigkeit mit Nachhaltigkeit verbinden wollen – ohne Kompromisse bei der Produktivität.

Persist OS ist als Open-Source-Projekt auf GitHub verfügbar und lässt sich mit wenigen Befehlen in jedes Projekt integrieren. Probier es aus und beobachte, wie sich die Qualität deiner Architektur verbessert – ohne dass du langsamer wirst.