ki-praxis/manuskript/kapitel-21-low-maturity-legacy-greenfield.md

21. Low-Maturity, Legacy & Greenfield – Agents in unreifen und chaotischen Codebases

Ergänzung nach dem Kernabschluss (Kap. 20): Team-Reife ohne Repo-Orakel bleibt Theater — hier der Repo-Hebel.

Das Ticket ist klar, der Feature-Druck auch. Das Repo nicht: keine brauchbaren Tests am Touchpoint, zwei READMEs die sich widersprechen, utils.ts neben utils2.ts, und in AGENTS.md steht noch npm test, während CI längst pnpm fährt. Der Agent startet trotzdem — und multipliziert in einer Session, was Menschen in Monaten angehäuft haben.

Dieses Kapitel ist für genau diese Realität. Die Kapitel davor beschreiben, wie Coding-Agents funktionieren, wenn Context eng, DoD prüfbar und das Repo halbwegs konsistent ist. Hier geht es um das Low-Maturity-Regime: wenig oder keine Tests, widersprüchliche Docs, Spaghetti, fehlende Struktur — und um Greenfield, das nach zwei Wochen genauso aussieht, wenn man die Disziplin „später“ plant.

Leitsatz: Agents multiplizieren deine Repo-Wahrheit. Ohne Orakel und ohne Hygiene (These 9, Kap. 12) ist Autonomie nur schnellerer Drift. Das ändert nicht die Thesen — es verschärft die Reihenfolge, in der du sie anwendest (Kanon Kap. 10).

Was hier nicht steht: ein Freifahrtschein, DoD und Review auszusetzen. Was hier steht: wie man mit Agents arbeitet, bevor das Repo die Ideale aus Kap. 8, 10 und 12 erfüllt — und wie man verhindert, dass Greenfield sofort Legacy wird.

---

21.1 Diagnose: Wann bist du im Low-Maturity-Regime?

Low-Maturity ist kein moralisches Urteil übers Team. Es ist ein Arbeitsregime: die Voraussetzungen für ehrliche Agent-Autonomie fehlen am Touchpoint — oder im ganzen Repo. Typisches Bild: der Agent „fixt“ den Bug, indem er eine zweite Implementierung neben utils2.ts legt — und AGENTS.md preist noch npm test an, während CI pnpm fährt.

Symptome (Checkliste)

Zähl, was zutrifft. Nicht alles muss marode sein; ein hartes Symptom oder ≥3 beliebige reichen oft für einen Regimewechsel. Die Tabelle ist Diagnose, kein Shame-Board.

Symptom	Härte	Typisches Bild	Agent-Folge
Keine oder flaky Tests am Touchpoint	hart	„Wir testen manuell“ / rot-grün-rot	Pseudo-Done, Loop ohne Messlatte
Keine kanonischen Verify-Commands	hart	Jeder erfindet npm test neu	Lokal grün, Pipeline rot
Widersprüchliche Docs/Rules	hart	README ≠ Code; AGENTS.md ≠ CI	Falsche Source of Truth
Broken-Windows-Artefakte	leicht	utils2.ts, old_, .bak, copy_of_	Zweite Implementierung statt Fix
Tote oder doppelte Patterns	leicht	Zwei Auth-Middleware „gültig“	Statistische Wahl, nicht deine Intent
Chaos-Monorepo / Wildwuchs	leicht–hart	Keine Boundaries, alles greift alles	Explore-Dumps, Scope-Explosion
Handoff-/Rule-Leichen	leicht	Erledigtes HANDOFF.md im Root	Falscher Session-Start
Kein Session-/Compact-Ritual	leicht	Eine Session für alles	Context Rot, Dumb Zone

Ampel: Zwei leichte Symptome → enger schneiden und beobachten. Ein hartes Symptom (kein Orakel oder widersprüchliche Rules am Touchpoint) oder ≥3 beliebige → nicht härter prompten. Regime wechseln: Slice 0, Hygiene, ehrliche Autonomie-Stufe (unten).

Team-Reife vs. Repo-Maturity

Kapitel 20 beschreibt Team-Reife (Ad-hoc → lokal produktiv → Team-Standard). Parallel dazu gibt es Repo-Maturity: Orakel-Qualität, Konsistenz der Rules, Ignore-Grenzen, eine Wahrheit pro Pattern.

Ihr könnt prozessreif und repo-unreif sein: tolle Task-Templates, aber null Tests am Legacy-Modul. Oder umgekehrt: grüne Suite, aber jeder promptet aus dem Bauch. Agents brauchen beides. Dieses Kapitel priorisiert den Repo-Hebel, weil er die DoD und den Context vergiftet, noch bevor der Prompt schlau wird.

Die Reifegrad-Leiter bleibt Kap. 20.2 (Assessment 20.3 / Anhang A.8). Hier sitzt der Repo-Hebel: Orakel am Touchpoint, eine Wahrheit, Slice 0, 30-Min-Hygiene. Ohne ihn bleibt Stufe 2 Theater.

Die Reihenfolge unter Feature-Druck:

1) Source of Truth am Touchpoint (Hygiene / eine Wahrheit)
2) Orakel schaffen oder ehrlich schwächen (Slice 0)
3) Feature als vertikaler Slice mit prüfbarer DoD
4) Write-Back (Docs/Rules) als eigener kleiner Schritt

Situation	Zuerst	Agent-Autonomie
Kein Orakel am Touchpoint	Slice 0 (Test/Repro)	max. L1, bis Orakel steht
Broken Windows am Touchpoint	30-Min- oder 2-Std-Hygiene	danach L2, wenn Orakel stabil
Flaky Suite in der DoD	stabilisieren oder aus Agent-DoD nehmen	kein Fake-L2
Docs widersprechen Code	HEAD + Test; Docs markieren	max. L1 (Explore zuerst)
Greenfield Tag 1	AGENTS.md + Verify + Handoff-Ritual	L2 auf schmalen Slices
Klare Suite, enger Slice, saubere Rules	Feature-Slice	L2 (ggf. L3 mit CI)
Secrets, Prod, destruktive Unklarheit	Mensch + Richtlinie (Kap. 18)	kein „Agent, versuch mal“

Immer mit ehrlicher Stufe arbeiten (Autonomie-Leiter Kap. 10.12): L0 Assist (Mensch steuert jeden Schritt); L1 Draft (Agent schreibt, Mensch prüft); L2 nur mit agent-ermittelbarer DoD. Erst aufräumen oder Slice 0, wenn keine Source of Truth erkennbar ist, jeder Diff eine Parallel-Implementierung erzeugen würde, Verify lügt oder eine Serie von Agent-PRs denselben Haufen multiplizieren würde.

---

21.2 Slice-0-Strategie: Test-/Repro-Orakel aufbauen

Kapitel 10 macht These 4 zur Regel; Kapitel 8 nennt den Hebel Slice 0. Im Low-Maturity-Regime ist Slice 0 oft der wertvollste Slice — nicht ein Aufschub des Features.

Warum ohne Orakel keine Autonomie

Der Loop ändern → prüfen → nachbessern braucht etwas, das ohne Geschmacksfrage grün oder rot sagt. Fehlt das, entartet der Loop zu:

write → „fertig“ → Mensch: „noch nicht“ → write → …

Das ist Ping-Pong mit Token-Kosten. Ehrlichkeit spart peinliche Demos: Agents ohne Orakel sind Textgeneratoren mit Shell-Zugang. Nutze sie so — Draft, Vorschlag, Explore — und nenne es nicht Autonomie.

Konkretes Vorgehen: kleinster Repro zuerst

1. Touchpoint benennen — eine Funktion, ein Endpoint, ein Bug-Pfad. Nicht „Billing“.
2. Repro erzeugen — reproduzierbarer Fail (Test, Script, HTTP-Call mit Fixture). Rot ist hier Erfolg.
3. DoD für Slice 0 — nur das Orakel: Repro war rot, ist grün oder der Test existiert und ist rot und committed als Vertrag für Slice 1.
4. Erst dann Feature-Slice — Verhalten gegen dieses Orakel.

Beispiel-Prompt (Slice 0):

## Ziel
Repro + Test für: Login sperrt nach 5 Fehlversuchen (Ist: unklar/kaputt).

## Ausschlüsse
- Kein UI-Refactor, keine neue Auth-Library

## DoD
- [ ] Test `auth/lockout` existiert; ohne Fix rot, mit Fix grün
- [ ] `git diff --name-only` nur unter `…/auth/**` und Testdateien
- [ ] Stop nach 3 Fix-Versuchen ohne Fortschritt → Handoff

Vollständige Vorlage mit allen Feldern: A.3.

Walking Skeleton (Kap. 8): manchmal ist Slice 0 der dünnste Pfad, der echt läuft — Request → Domain → Persistenz → Assert. Dann ist das Orakel der Slice, nicht ein Anhängsel.

Schwache Orakel (Übergang, nicht Ziel)

Nicht jedes Modul bekommt morgen eine vollständige Suite. Stärke und typische Autonomie-Stufe — grob von stark nach schwach, mit Schicht-Hinweisen:

Orakel	Stärke	Autonomie (Kap. 10.12)
Gezielter Unit/Integrationstest, stabil	stark	L2 Local Loop möglich
Characterization / Golden-Suite (Legacy)	stark, wenn stabil	oft genau Slice 0
Mutation (scoped, CI/Nightly)	sehr stark	nicht Tight-Loop; Test-Härte nach Slice 0
Diff-Coverage / touched lines	mittel–stark	eher Pre-Merge; gegen ungetestete Agent-Pfade
Typecheck / Compile exit 0	mittel	L2 nur für typbezogene Änderungen
Smoke-Script / golden file	mittel, wenn deterministisch	L2 mit enger Scope-DoD
Lint exit 0	schwach–mittel	Ergänzung, selten allein
Manuelle Checkliste	schwach	L1 Draft — Mensch prüft

Do this: Schwache Orakel explizit als solche im Task und in AGENTS.md führen.
Avoid that: Lint grün als „Feature done“ verkaufen.

Diff-Coverage und Mutation sind Reife-Investments nach Slice 0 — nicht Einstiegszwang und nicht Tight-Loop-Default. Orakel-Klassen und Verify-Schichten im Überblick: Kapitel 10.6.

Kombiniert immer:

Agent-DoD (automatisch, so stark wie möglich)
+ Human-DoD (Review / manuelle Checks, ehrlich)

Stop-Regeln, solange das Orakel schwach ist

• Max. 3 gezielte Fix-Versuche pro Fehlerklasse, dann stoppen.
• Kein 10×-Retry bei Flaky — Flaky erst stabilisieren oder aus der Agent-DoD nehmen (Kap. 10.13).
• Keine neuen Dependencies und keine Public-API-Erweiterung ohne Rückfrage.
• Bei „kein DoD-Fortschritt“: Ursachenhypothesen listen, Handoff aktualisieren, eskalieren.

Ohne Stop-Regel füllt der Agent den Context mit gescheiterten Patches — Context Rot mit guter Absicht (Kap. 3–4).

Do this	Avoid that
Slice 0 = eigenes Ticket mit eigener DoD	„Test mitmachen, wenn Zeit bleibt“ im Feature-Prompt
Orakel-Stärke an Autonomie-Stufe koppeln	L3/PR-Loop ohne stabile Checks
Schwache Orakel + Human-Gate benennen	Autonomie vortäuschen
Stop & Handoff bei Stillstand	Noch ein Versuch „weil das Modell fast…“

Slice-0 mit Plan-Mode

Zwei parallele Subs — einer „schreibt Tests“, einer „fix Billing“ — in einem Repo ohne Orakel: das ist These-6-Verstoß plus Spawn-Theater, nicht Tempo.

Slice 0 bleibt ein vertikaler Slice mit eigener DoD (Schritte oben). Vor dem ersten Write: Plan-Freigabe über Plan-Mode / Ask-Mode / Plan-Turn (mehrere Harnesses, siehe Kap. 11). Freigeben: Touchpoint, Repro, Ausschlüsse, Verify-Command. Parallel höchstens ein Explore-Sub (read-only) für die Karte; den Orakel-Diff schreibt einer.

Ohne Freigabe zementiert der Test das geratene Verhalten. Freigabe ist Alignment, kein Orakel (Kap. 11). Parallele Writer ohne Orakel multiplizieren Drift — erst Hygiene (21.3), dann Multi-Agent-Readiness (Kap. 22).

---

21.3 Hygiene-First bei Broken-Windows-Repos

These 9: Aufräumen und Konsistenz sind kritisch. Obsolete Dateien und widersprüchliche Rules sind Fehlinformation für den Agent — nicht nur Unordnung.

Kapitel 12 ist der Kanon. Hier zählt die Priorität unter Feature-Druck: Müll am Touchpoint multipliziert sich mit jeder Agent-Session. Menschen filtern mit Flurfunk („die old/-Datei ignorieren wir“). Modelle gewichten, was im Fenster und im Suchtreffer liegt.

Kleine Unordnung skaliert: existiert utils2.ts, baut der Agent gern utils3. Existieren zwei „kanonische“ Patterns, wählt er statistisch — nicht moralisch.

30-Minuten-Hygiene (vor dem nächsten Feature-Agent)

Reicht oft, um den schlimmsten Context-Gift am Touchpoint zu kappen:

• Ignore-Grenzen: Build, node_modules, Coverage, große Fixtures, echte Archive (Harness-Ignore, z. B. .cursorignore und Analoga)
• AGENTS.md / Skills: ein Testcommand, ein Package-Manager — Widerspruch löschen, nicht kommentieren
• Suche nach old_, .bak, copy_of_, deprecated im Pfad des Slices
• Erledigte Handoffs aus dem Root: archivieren oder löschen
• Temp-Dateien aus der letzten Session: nicht committen, nicht liegen lassen

2-Stunden-Hygiene (wenn der Touchpoint systematisch giftig ist)

• Kanonische Verify-Commands in AGENTS.md und CI angleichen (copy-paste getestet)
• Eine Wahrheit pro Problemklasse am Modul (Error-Format, Auth-Hook, Logging)
• Archive nach docs/archive/… (oder ähnlich) außerhalb Default-Suche + Ignore
• Tote Agent Skills (SKILL.md für migrierte Stacks) entfernen oder hart deprecaten
• Doppelte Utilities: Owner entscheiden — mergen, löschen oder eine als kanonisch markieren

Das ist kein Big-Bang-Jahr. Es ist die DoD des Repos für Agent-Arbeit am aktuellen Slice. Beispiel: Nach 30 Minuten Ignore + AGENTS.md-Command-Angleich und dem Löschen von billing/utils2.old.ts produziert der nächste Agent-Slice plötzlich Diffs im kanonischen Modul — nicht eine dritte Utility-Variante.

Mit Agent suchen — mit Auftrag und Test löschen

Agents sind gut im Finden von Kandidaten, schlecht im spekulativen Massen-Delete:

Finde potentiell obsolete Dateien/Rules am Pfad packages/billing/**
(old, bak, duplicate utils, widersprüchliche Docs).
Ändere noch nichts. Liste mit Begründung, Risiko, empfohlenem Next Step.

Löschen und große Moves: expliziter Auftrag, Surgical Changes, danach Verify. Sonst wird „Aufräumen“ zum größten Diff des Quartals und zum klassischen Fokus-Verstoß (Kap. 13).

Wann Hygiene den Feature-Schnitt blockiert

Hygiene vor dem Feature-Agent, wenn:

• am Touchpoint keine Source of Truth erkennbar ist (zwei Patterns, beide „gültig“),
• Verify-Commands lügen (Docs/Rules ≠ CI),
• der geplante Diff logisch auf Leichen-Code aufbauen würde.

Hygiene parallel / danach, wenn:

• der Slice einen klaren, isolierten Happy Path hat,
• Orakel und Scope eng sind,
• der Schrott außerhalb der git diff-Grenze liegt und per Ignore/Ausschluss rausgehalten wird.

Do this	Avoid that
30-Min-Sweep am Touchpoint vor Serie von Agent-PRs	Feature auf utils2 + utils3 stapeln
Widersprüche löschen	„Beide Varianten dokumentieren“ ohne Kanon
Agent: nur Finden, bis Auftrag zum Löschen	Massen-Delete ohne DoD
Ignore wie Production-Config pflegen	2-GB-data/ im Default-Grep
HEAD + Test gewinnen; Docs als VERDÄCHTIG markieren	Stille Doc-Wahrheit neben Code-Wahrheit
Pfad- und Ausschluss-DoD trotz Chaos-Repo	„Mach es richtig“ ohne Grenze

Widersprüchliche Docs sind schlimmer als keine: sie sind aktive Desinformation. Sag dem Agent das explizit (HEAD gewinnt; verdächtige Docs nicht als Kontextquelle). Sonst „stellt er die Spec wieder her“, die du 2022 beerdigt hast. Den Scope erzwingst du im Task, nicht im Wunschdenken: Ausschlüsse, git diff --name-only nur unter erlaubten Globs, ein Outcome pro Session. Sub-Agents helfen nur mit Hand-back; echte Multi-Agent-Orchestrierung (Kap. 22) erst nach Orakel und Hygiene — und nur nach Plan-Freigabe vor dem Parallel-Spawn.

---

21.4 Greenfield-Start: minimale AGENTS.md + Handoff von Tag 1

Greenfield fühlt sich an wie Freifahrt: keine Legacy, keine flaky Suite, keine alten Rules. Genau deshalb entsteht Legacy oft in Woche zwei — der Agent liefert Tempo, niemand schreibt Verify, Handoffs und eine Wahrheit pro Pattern mit.

Regel: Die ersten Stunden zählen mehr als der spätere „wenn wir Zeit haben“-Refactor.

Minimal-Setup (erste Session / erster Nachmittag)

1. AGENTS.md — kurz, wahr, löschbar-erweiterbar. Mission, Karpathy-Skills, Verify-Defaults, Workflow Explore→Plan→Execute→Verify→Commit, Git-/Secret-Verbote. Vorlage: Anhang A · templates/agents-md-beispiel.md.
2. Ein Verify-Command, der wirklich läuft — auch wenn die Suite nur smoke oder tsc --noEmit ist. Lügen in AGENTS.md sind teurer als ehrlich schwache Orakel.
3. Task-Prompt mit Ziel + Ausschlüsse + DoD — Anhang A · templates/task-prompt-template.md.
4. Handoff ab Slice 1 — nicht erst bei Urlaubsübergabe. Anhang A · templates/handoff-template.md.
5. Session-Start-Ritual — Anhang A · checklists/session-start-checkliste.md.
6. Ignore für Build/Temp/Dependencies, bevor der erste große Explore-Dump kommt.

Mehr braucht Tag 1 nicht. Architecture Decision Records und eine vollständige Skill-Bibliothek können warten. Eine kanonische Test-Einstiegslinie und ein Handoff nach dem ersten Slice nicht.

Wenn Wahlfreiheit (Greenfield ohne Org-Zwang): strict types früh, eine echte Modulgrenze im Code, Verify wächst mit dem Slice. Form oft: klares Package-Layout / modularer Monolith, bei Multi-Package ein Monorepo — siehe Kap. 9.6. Orakel-Fläche bewusst ausbauen, nicht „Tests später“ (Kap. 10).

Was in AGENTS.md von Anfang an rein muss

Die Defaults — DoD, Verify-Zeilen, Workflow, Karpathy-Skills — stehen als kopierbarer Block in Anhang A.4 und templates/agents-md-beispiel.md. Ersetze die Verify-Zeilen durch Commands, die heute wirklich laufen.

Was nicht rein muss: Roman-Länge, Wunsch-Stack von übermorgen, drei widersprüchliche „bevorzugte“ Package-Manager.

Handoff-Disziplin ab dem ersten Slice

Greenfield-Sessions sind oft euphorisch und lang — genau dann zählt Session-Disziplin (Kap. 4). Nach Slice 1:

• Handoff schreiben (Ziel, DoD-Stand, nächster Schritt, Nicht-Anfassen),
• neue Session oder bewusst Compact mit Erhaltungs-Hint,
• nicht „der Chat weiß das schon“.

Der Chat vergisst. Das Repo und das Handoff nicht — wenn du sie pflegst.

Greenfield → Legacy in 14 Tagen (Avoid)

Vermeiden	Stattdessen
DoD nur Prosa („clean“, „solid“)	Command + Scope-Check
Zweite Utility „nur kurz“	Bestehende erweitern oder Slice „extrahieren“
Docs, die den Code von gestern beschreiben	Docs mit Slice mitziehen oder als verdächtig markieren
Eine Session für Epic 1–4	Slice, Handoff, Reset
AGENTS.md „später“	Skeleton an Tag 1, lügenfreie Verify-Zeile

These 6 gilt im Greenfield genauso: vertikale Slices und Komplexitätsbudget. Ohne Legacy-Schmerzen fehlt nur der äußere Zwang — nicht die Physik von Context und Review.

---

Key Takeaways

• Low-Maturity ist ein Arbeitsregime (Orakel + Hygiene fehlen) — Thesen strenger priorisieren, nicht aussetzen.
• Ohne agent-prüfbare DoD keine ehrliche Autonomie; Slice 0 ist oft der höchste Hebel — Plan-Freigabe vor dem Orakel-Diff, keine parallelen Writer.
• 30-Minuten-Hygiene am Touchpoint schlägt den nächsten Clever-Prompt.
• Greenfield braucht Tag-1-Disziplin — sonst ist Woche 2 Legacy.

Praktische nächste Schritte

1. Symptom-Checkliste (21.1) gegen das aktuelle Agent-Ticket; bei Treffer Regime markieren.
2. Slice 0 (Repro/Test oder ehrlich schwaches Orakel) mit Plan-Freigabe vor dem Feature-Diff.
3. 30-Minuten-Sweep am Touchpoint; Greenfield: AGENTS.md + Verify heute aus Anhang A.
4. Weiter bei Bedarf: Kap. 10, 12.

---

Reifegrad und Ausblick: Kapitel 20 · Multi-Agent erst nach Orakel/Hygiene: Kapitel 22.
Kern-Templates: Anhang A · Begleitmaterial: Begleit-Service.