ki-praxis/manuskript/kapitel-12-aufraeumen-und-konsistenz.md

12. Aufräumen und Konsistenz

Nach der Auth-Migration leben auth_v2 und old_auth nebeneinander — beide in der Suche, beide „gültig“. Der Agent wählt statistisch. Obsolete Dateien, widersprüchliche Rules, tote Agent Skills (SKILL.md) und alte Handoffs sind kein ästhetisches Problem. Sie sind Context-Gift. Was im Fenster und im Suchtreffer liegt, steuert den nächsten Diff.

These 9: Aufräumen und Konsistenz sind kritisch. Obsolete Dateien, Settings und Context-Reste verderben die Ergebnisse.

Freshness und Write-Back für Knowledge-Artefakte (Handoff, AGENTS.md, Agent Skills, optional KB): Kapitel 6.

{width=90%}

12.1 Warum Müll Agents härter trifft als Menschen

Menschen filtern mit Erfahrung: „Die old/-Datei ignorieren wir.“ Modelle gewichten oft, was im Fenster und im Suchtreffer liegt — und „old“-Code kann semantisch nah am Query liegen. Der Agent hat keinen Flurfunk, der sagt: „Das ist tot, seit der Migration.“ Das ist Context is King in der hässlichen Variante (Kap. 3).

Der Agent stellt gern wieder her, was du absichtlich gelöscht hast — weil es in History oder Docs noch lebt.

Vier Achsen reichen, um die meisten Konflikte zu erkennen:

1. Eine kanonische Anweisung pro Thema (Testkommando, Package-Manager)
2. Ein kanonisches Pattern pro Problemklasse (Error-Format, Auth-Middleware)
3. Aktueller HEAD als Wahrheit, nicht Chat-History
4. Namensraum-Klarheit (docs/archive/ statt lose old_* im Source-Tree)

Wo zwei Wahrheiten existieren, gewinnt oft die lautere — nicht die richtige.

12.2 Agent-Schrott

Nicht jeder Schrott ist gleich giftig. Für Agents zählen Artefakte, die als Anweisung oder zweite Wahrheit gelesen werden:

Kategorie	Beispiele	Risiko
Rule-Leichen	veraltete AGENTS.md-Absätze	Richtlinien-Konflikt
Skill-Leichen	Agent Skills für migrierte Stacks	Falsche Prozeduren
Handoff-Leichen	erledigte HANDOFF.md im Root	Falscher Session-Start
Doppelte Patterns	auth_v2 neben old_auth	Agent wählt statistisch

Zwei „kanonische“ Patterns nebeneinander sind der teure Fall.

Hygiene hat eine Reihenfolge, weil der Agent gewichtet, was als Anweisung oder als naher Suchtreffer im Fenster landet — nicht, was du intern als tot kennst. Zuerst das, was als Policy gelesen wird; zuletzt Kosmetik.

Priorität	Was	Warum zuerst
1	Instruction-Artefakte (AGENTS.md, SKILL.md, Root-Handoff)	werden als Richtlinie ausgeführt
2	Zweite Wahrheiten im Source-Tree (old_auth neben auth_v2)	Suche trifft beide; der Agent wählt statistisch
3	Suchpfad (Archive, Fixtures ohne Ignore)	Token- und Treffer-Rauschen, oft ohne Anweisungsanspruch
4	Formatter, Kommentare, tote Tests ohne Owner	billig sichtbar, selten der nächste falsche Diff

Wer mit Import-Sortierung beginnt, lässt die lautere Lüge in AGENTS.md stehen. Die trifft den nächsten Feature-Agent zuerst.

Was der Agent nicht sehen soll, muss nicht unbedingt weg: Build, Vendor, Archive. Ignore-Files der Harness (z. B. .cursorignore und Analoga) begrenzen Suche und Index des Harness — eine Zugriffsgrenze bestimmter Surfaces, keine Sandbox (Kap. 5). Do this: Ignore pflegen wie Production-Config. Avoid that: große Fixtures ohne Ignore.

12.3 Hygiene-Rituale

Aufräumen skaliert nicht als Big-Bang-Jahr. Es skaliert als Ritual.

Session-Ende

Erledigte Handoffs aus dem Default-Suchpfad; keine Temp-Commits. Compact und Handoff-Mechanik: Kap. 4. Fünf Minuten am Ende sparen der nächsten Session den falschen Start.

Wöchentlicher Repo-Sweep (15–30 min)

• AGENTS.md gegen reale Commands (Test, Package-Manager); Verbotsliste und Beispiele noch wahr?
• Skills-Liste: noch verwendet, Owner klar? Tote Prozeduren mergen oder löschen
• Erledigte Handoffs archivieren — außerhalb der Default-Suche, wenn Compliance Archive verlangt
• Doppelte Patterns (old_, deprecated ohne Owner)

Widerspruch stehen lassen ist teurer als die 5-Minuten-Reparatur. Eine veraltete Regel ist aktive Desinformation.

Nach großen Migrationen

Alte Pfade entfernen oder hart umleiten. Docs, AGENTS.md und Skills am selben Tag mitziehen. Ein „Migration complete“-Handoff, dann alte Handoffs weg. Migration ohne Rules-Update ist eine Einladung, das Alte wiederzubeleben.

Nach Agent-PR-Serien

• Sind Temp-Skripte aus der Session committed worden?
• Neue Docs widersprechen alten?
• Wurden „quick hacks“ mit Owner/Issue markiert oder entfernt?
• Hat der Agent eine zweite Utility parallel zu einer bestehenden erzeugt?

Wenn ja: Hygiene-Slice einplanen, bevor der nächste Feature-Agent drauf aufbaut.

Nutze ergänzend die tägliche Agent-Checkliste (im Buch-Repo unter checklists/taegliche-agent-checkliste.md) und die Anti-Pattern-Vermeidung (Anhang A · checklists/anti-pattern-vermeidung.md).

12.4 Aufräumen mit dem Agent — vorsichtig

Agents sind gut im Finden von Kandidaten:

Finde potentiell obsolete Dateien/Rules (old, bak, duplicate utils).
Ändere noch nichts. Liste mit Begründung und Risiko.

Löschen und große Moves brauchen expliziten Auftrag, Surgical Changes und Tests danach — keine spekulativen Massen-Deletes. Sonst wird „Aufräumen“ zum größten Diff des Quartals und zum klassischen Verstoß gegen Surgical Changes (Kap. 13).

Durchgerechnet — Auth-Migration, sechs Wochen her. Explore (noch keine Deletes) findet: apps/api/src/auth_v2/** und apps/api/src/old_auth/**; in AGENTS.md steht noch „Auth-Tests: npm test unter old_auth“; Skill migrate-auth-v1/SKILL.md; Root-HANDOFF.md mit Status „Migration in progress“.

Dann ein Hygiene-Slice, nicht das Epic:

## Ziel
Eine Auth-Wahrheit unter `auth_v2`. `old_auth` liegt außerhalb der Default-Suche.

## Nebenbedingungen
- Bestehende Auth-Tests bleiben grün.
- Ignore-Grenze wie Production-Config pflegen.

## Ausschlüsse
- Kein Formatter-Lauf, kein Rename in `packages/legacy/**`.
- Keine Massen-Deletes ohne die Kandidatenliste aus Explore.

## DoD
- [ ] `pnpm --filter auth test` exit 0
- [ ] `git diff --name-only` nur: `AGENTS.md`, Skill-Pfad, Handoff-Archivierung, Move nach `docs/archive/`, Ignore-Zeile

Ablauf: Handoff archivieren, Skill löschen, den einen AGENTS.md-Absatz ersetzen, old_auth nach docs/archive/ (Ignore), Tests. Der Agent schreibt die Kandidatenliste; Löschen erst nach Freigabe. Ohne diese Reihenfolge bleibt npm test in old_auth die lautere Regel — und der nächste Slice restauriert den toten Pfad, weil History und Docs ihn noch füttern.

Was passiert, wenn du eine Stufe überspringst: Nur old_auth löschen, AGENTS.md stehen lassen → der Agent legt old_auth neu an, „weil die Tests so dokumentiert sind“. Nur Ignore setzen, Handoff im Root lassen → die nächste Session startet mit „Migration in progress“ und sucht den toten Pfad. Nur den Skill löschen → die zweite Wahrheit im Tree bleibt der nähere Suchtreffer. Deshalb ist die Tabelle in 12.2 keine Ästhetik-Rangfolge, sondern die Reihenfolge, in der der Loop Anweisungen ausführt.

12.5 „Broken Windows“ und Agent-Verhalten

Kleine Unordnung skaliert, weil der Loop auf lokale Plausibilität optimiert — nicht auf deine Intentionsgeschichte. Die vier Symptome sind Agent-Verhalten, keine Ästhetik:

Symptom	Was der Agent tut	Gegenmaßnahme
Driftende AGENTS.md	Folgt der lauteren, alten Regel (npm test vs. CI pnpm test); schreibt dazu, statt zu löschen	Verify-Commands gegen CI; Review „weniger Text“; widersprüchliche Absätze löschen
Veraltete Skills	Lädt die Prozedur des migrierten Stacks — autoritative Lüge	Owner; am Tag der Migration mergen oder löschen. Discovery-Tax: Kap. 16.8
Unreviewte Diffs	utils2 neben utils.ts → nächster Agent baut utils3; Accept-and-Forget zementiert die zweite Wahrheit	Mensch liest den Diff (checklists/review-agent-diff.md); Hygiene-Slice vor dem nächsten Feature-Agent
Context-Bloat	Ignore fehlt, Archive im Suchpfad, Root-Handoff, Session-Müll im Fenster	Ignore-Grenze (Kap. 5); Archive raus; Session/Compact (Kap. 4)

{width=90%}

Hygiene ist kein Ersatz für Feature-DoD (These 4), sondern die Repo-Voraussetzung — analog zu flaky tests (Kap. 10): stale Rules und doppelte Utils fälschen die Source of Truth, auf der das Orakel läuft.

Die Mechanik ist dieselbe wie bei Context is King (Kap. 3): was im Fenster und im Treffer liegt, steuert den nächsten Diff. Liu et al. (TACL 2024) zeigen, dass Position im Context das Gewicht verschiebt; hier verschiebt Zugehörigkeit zur Suche das Gewicht. Ein old_*-Modul, das semantisch nah am Query liegt, gewinnt gegen die kanonische Datei, die du „natürlich“ meintest. Deshalb ist Ignore eine Zugriffsgrenze und AGENTS.md eine Anweisung — zwei Hebel, ein Ziel: eine Wahrheit.

---

Key Takeaways

• Veraltete Rules und Leichen sind Context-Gift, keine Ästhetikfrage.
• Eine Wahrheit in AGENTS.md / Skills / Ignore schlägt Archive.
• Hygiene ist Ritual (Session-Ende, Sweep, nach Agent-PRs) — kein Big-Bang-Jahr.
• Broken Windows am Agent-Verhalten erkennen: driftende AGENTS.md, tote Skills, unreviewte Diffs, Context-Bloat.

Praktische nächste Schritte

1. 20-Minuten-Sweep: doppelte Patterns, erledigte Handoffs, tote Skills.
2. AGENTS.md Verify-Commands gegen CI abgleichen; widersprüchliche Absätze löschen.
3. Ignore-Files um Build/Archive ergänzen (Kap. 5).
4. Weiter: Kapitel 13; bei chaotischen Repos zuerst Kapitel 21.