Selbsterhaltendes Dokumentationssystem unter Verwendung von abgegrenzten Blöcken für Null-Drift

Ein Entwickler auf r/ClaudeAI teilte eine Lösung zur Pflege genauer Dokumentation in Multi-Projekt-Arbeitsbereichen, in denen KI-Codierungsagenten wie Claude Code den Kontext zwischen Sitzungen vergessen. Das System behandelt Probleme mit 8 Projekten, 20 Lambda-Funktionen, 42 API-Schlüsseln, 12 API-Endpunkten und 19 Umgebungsvariablen, bei denen der Agent Funktionsnamen erraten, falsche Dateien bearbeiten und den Kontext verlieren würde.

Das Zaun-System

Anstatt Claude zu bitten, die Dokumentation nach der Implementierung zu aktualisieren, erstellte der Entwickler ein 740-zeiliges Bash-Skript, das strukturierte Daten direkt aus Quelldateien extrahiert und sie über eingefasste HTML-Kommentarblöcke in CLAUDE.md einfügt. Jede CLAUDE.md hat Zäune, die automatisch generierte Abschnitte markieren:

## Serverless Functions <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Funktion | Route | Speicher | Timeout |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 Zeilen aus CDK-Konfiguration extrahiert...
<!-- /auto:lambdas -->

## Architektur <-- handgeschrieben, nie vom Skript berührt

Wie es funktioniert

Das Skript:

• Analysiert tatsächliche Quelldateien (CDK TypeScript, FastAPI Python, package.json usw.)
• Extrahiert strukturierte Daten (Funktionsnamen, Routen, Umgebungsvariablen, Abhängigkeitsversionen)
• Ersetzt alles zwischen den Zäunen
• Aktualisiert das Generierungsdatum, um Aktualität anzuzeigen
• Validiert: prüft, dass jeder Lambda-Name eine passende Handler-Datei hat, jede Umgebungsvariable in .env existiert

Handgeschriebene Abschnitte (Architekturbeschreibungen, Fallstricke, Geschäftslogik-Kontext) befinden sich außerhalb der Zäune und werden nie berührt.

Automatisch generierter Inhalt

• Zitierwerkzeug (20 Lambdas): Lambda-Bestand, CDK-Stacks, Umgebungsvariablen, Testanzahlen, Abhängigkeiten aus CDK TypeScript und package.json
• Verkaufsdashboard (12 Endpunkte): API-Routen, Themenliste, Abhängigkeiten aus FastAPI-Dekoratoren, TypeScript-Typen und requirements.txt
• Datenanalyse (42 Benutzer): Benutzerdaten, Abhängigkeiten aus Python-Anmeldedatei und requirements.txt
• 5 weitere Projekte: Abhängigkeitsversionen aus package.json/requirements.txt

System für Veraltungswarnungen

Ein Dokumentensynchronisations-Hook (wird nach jeder Codebearbeitung ausgelöst) prüft das Generierungsdatum an jedem Zaun. Wenn ein Abschnitt älter als 7 Tage ist:

Warnung: 3 automatisch generierte Abschnitte in agent-quoting-tool/CLAUDE.md sind veraltet (ältester: 2026-03-19).
Ausführen: ./scripts/generate-inventory.sh quoting

Dies ist nicht blockierend – warnt, aber hindert Sie nie an der Arbeit. Die Veraltungsprüfung läuft parallel zu bestehenden Hooks mit demselben 10-Minuten-Drosselungsfenster, ohne zusätzlichen Aufwand.

Implementierungsdetails

Das Setup verwendet reines Bash mit grep/sed/awk/jq, keine Abhängigkeiten. Befehle:

scripts/generate-inventory.sh all # Alles aktualisieren
scripts/generate-inventory.sh quoting # Nur ein Projekt

Das Skript sichert jede CLAUDE.md zuerst (eine Sicherung pro Tag, pro Projekt). Der Entwickler merkt an, keine ASTs aus Bash zu analysieren – ihr TypeScript-Parser ist eine zeilenweise grep/sed-Schleife, die für kontrollierte Dateien funktioniert, aber für beliebiges TypeScript fragil wäre.

Wichtige Erkenntnisse

Die Zäune ermöglichen, dass automatisch generierter und handgeschriebener Inhalt in derselben Datei koexistieren. Claude liest die gesamte CLAUDE.md zu Sitzungsbeginn und erhält beides: genaue extrahierte Daten UND menschlichen Kontext, den es nicht aus Code ableiten kann. Der Entwickler empfiehlt, mit den wertvollsten Extraktionen zu beginnen (Lambda-Bestände und Umgebungsvariablen-Tabellen, die Fehler verursachen, wenn sie abweichen) und merkt an, dass die Veraltungswarnung wertvoller ist als automatisches Ausführen.

Das gesamte System dauerte etwa 3 Stunden zum Erstellen (Design, Implementierung, Testen, erster Lauf).