Harness Design: Wie man KI-Coding-Agenten über 100+ Sessions produktiv hält

TL;DR

KI-Coding-Agenten wie Claude Code sind beeindruckend gut -- aber sie vergessen alles zwischen Sessions. In einem Projekt mit 139 Sessions, 24 Regeldateien und 14.000+ Commits zeige ich, wie ich ein "Harness" gebaut habe, das den Agenten konsistent, sicher und produktiv hält. Nicht die Prompts machen den Unterschied. Das System drumherum macht ihn.

Was ist ein Harness?

Wer mit einem KI-Coding-Agenten arbeitet, hat ein Problem: Der Agent hat kein Gedächtnis zwischen Sessions. Session 1 und Session 100 starten mit dem gleichen Wissensstand. Der Agent kennt weder die Architektur, noch die Konventionen, noch die Fehler, die er gestern gemacht hat.

Ein Harness ist die Lösung. Es ist die Summe aller Dateien und Systeme, die dem Agenten bei jedem Start den nötigen Kontext geben. Man kann sich das vorstellen wie ein Onboarding-Paket für einen neuen Entwickler -- nur dass dieser Entwickler jeden Tag neu anfängt.

In meinem Fall besteht das Harness aus vier Schichten:

1. CLAUDE.md: Das Hauptdokument. Befehle, Stack, Architekturentscheidungen.
2. Rules: 24 Regeldateien, die spezifische Standards definieren.
3. Memory: Persistente Informationen, die über Sessions hinweg gelten.
4. Session-Handovers: 102 Übergabedokumente, die den Stand zwischen Sessions weitergeben.

Schicht 1: CLAUDE.md als Hauptdokument

Die CLAUDE.md ist das erste, was der Agent liest. Sie muss kurz, präzise und aktuell sein. In meinem Projekt enthält sie:

• Befehle: bun dev, npm test, tsgo --noEmit. Der Agent muss wissen, wie er den Code überprüft.
• Stack: Next.js 16.2.1, React 19, TypeScript 5.9, Tailwind 4. Kein Rätselraten.
• Architektur: Drei Supabase-Client-Patterns (Browser, Server, Admin). Wer was wann verwendet.
• Quality Gate: tsgo --noEmit && bun run build && npm test. Vor jedem Deploy.

Ein Fehler, den viele machen: Die CLAUDE.md wird zu lang. Alles reinpacken, 500 Zeilen. Der Agent überfliegt das und vergisst die Hälfte. Meine Lösung: unter 100 Zeilen bleiben. Alles Detaillierte lebt in den Rules.

Schicht 2: Rules als Domain-spezifische Standards

24 Dateien in .claude/rules/. Jede behandelt genau ein Thema:

• error-handling-catch.md: Kein .catch(() => {}). Jeder Catch muss loggen.
• api-response-consistency.md: Alle API-Antworten über apiResponse.*(). Kein rohes NextResponse.json().
• test-colocation.md: Tests gehören in __tests__/-Verzeichnisse neben dem Quellcode.
• voice-consistency.md: "Ich"-Perspektive, kein "Wir" auf der Website.
• content-writing-standards.md: Keine Em-Dashes. Keine KI-Buzzwords.

Der Schlüssel: Jede Rule enthält nicht nur die Regel, sondern auch Anti-Patterns und korrekte Beispiele. Ein Agent, der nur "Verwende apiResponse" liest, macht immer noch Fehler. Ein Agent, der ein konkretes WRONG- und CORRECT-Beispiel sieht, trifft die richtige Entscheidung.

Schicht 3: Session-Handovers als Gedächtnisbrücke

Nach jeder Session schreibe ich ein Handover-Dokument. 102 davon über 139 Sessions. Jedes Handover enthält:

• Was wurde gemacht (Commits, Änderungen)
• Was ist offen (offene Issues, bekannte Bugs)
• Nächste Schritte (priorisiert)

Der Agent der nächsten Session liest das Handover und weiß sofort, wo er anfangen muss. Ohne Handover würde Session 140 bei Null anfangen und möglicherweise Arbeit wiederholen, die in Session 138 erledigt wurde.

Schicht 4: Automatisierte Quality Gates

Menschen vergessen Dinge. Agenten auch. Deshalb automatisiere ich alles, was prüfbar ist:

• TypeScript: tsgo --noEmit. 0 Fehler als Baseline. Nicht verhandelbar.
• Build: bun run build. Fehlende Translations, kaputte Imports, alles fliegt hier auf.
• Tests: 7.474 Tests in 250 Dateien. Jeder Lauf dauert 27 Sekunden.
• Content-Checks: 23 automatisierte Prüfungen. Em-Dashes, KI-Buzzwords, i18n-Parität, CTA-Wiederholungen.
• ESLint: Spezielle Regeln gegen console.log (PII-Leak-Prävention) und error.message in Responses (SEC-015).

Die Quality Gates laufen vor jedem Deploy. Der Agent kann nicht deployen, ohne dass alle Checks grün sind.

Typische Fehlerquellen ohne Harness

Was passiert ohne Harness:

Context Drift: Session 50 fängt an, Patterns zu verwenden, die Session 30 schon abgelöst hat. Ohne Rules gibt es keine Referenz, was "aktuell" ist.

Halluzinations-Akkumulation: Der Agent erfindet eine Funktion, die es nicht gibt. Ohne Quality Gates fällt das erst in Production auf.

Architektur-Erosion: Jede Session macht kleine Abweichungen. Nach 20 Sessions gibt es fünf verschiedene Error-Handling-Patterns im gleichen Projekt.

Wiederholte Fehler: Der Agent macht den gleichen Fehler wie vor 10 Sessions. Ohne Feedback-Memory gibt es keinen Lerneffekt.

Was sich über 139 Sessions bewährt hat

Ein paar Muster, die sich bewährt haben:

1. SSOT-Dateien für alles, was sich ändern kann. Preise, biografische Fakten, Service-Definitionen. Eine Datei, eine Wahrheit. Der Agent erfindet nichts, er liest nach.

2. Composable Middleware statt Copy-Paste. withErrorHandler(), withAdminAuth(), withRateLimit(). Drei Wrapper, die sich kombinieren lassen. Kein Boilerplate in 62 Admin-Routes.

3. Regeln mit "Warum". Nicht nur "Verwende apiResponse". Sondern: "Weil rohes NextResponse.json() inkonsistente Error-Shapes produziert und die Tests brechen." Agenten, die das "Warum" kennen, wenden Regeln auch in Grenzfällen richtig an.

4. Feedback-Memory als Lernschleife. Wenn der Agent einen Fehler macht und ich ihn korrigiere, speichere ich das als Memory. Nächste Session: gleicher Fehler tritt nicht auf.

Das Harness wächst mit dem Projekt

In Session 1 hatte ich eine CLAUDE.md mit 30 Zeilen. In Session 139 habe ich 24 Rules, 102 Handovers, ein Memory-System und automatisierte Quality Gates mit 23 Content-Checks.

Das Harness ist kein Projekt, das man einmal aufsetzt. Es wächst mit jedem Problem, das man löst. Jeder Fehler, der zweimal auftritt, wird zur Rule. Jede Architekturentscheidung, die Kontext braucht, wird zum SSOT-Dokument.

Fazit

KI-Coding-Agenten sind Werkzeuge. Wie bei jedem Werkzeug hängt das Ergebnis davon ab, wie man es einsetzt. Die Prompts sind der offensichtliche Teil. Das Harness ist der unsichtbare. Und oft der entscheidende.