Agent Doc — Quarterly Maintenance

Quarterly Claude Code Audit

Alle 90 Tage: Drift-Check für .claude/-Config und Doku-Strände. Basierend auf Claude Code Best Practices „Configuration Maintenance“ — stale Skills, unbeschiedene ADRs und vergessene lint-Passes akkumulieren kognitive Schulden. On-demand ausführbar von beiden Devs; keine Cloud-Routine.

90
Tage Rhythmus
Skills + Agents + Hooks
60
Tage ADR-Grenze
Proposed → entschieden
30
Tage Lint-Grenze
solcom-docs-lint

Ausführung

Script aus dem Repo-Root heraus starten und Report in eine temporäre Datei schreiben:

Shell
./scripts/quarterly-claude-audit.sh > /tmp/claude-audit.md open /tmp/claude-audit.md

Das Script hat keine Abhängigkeiten außer git, grep, find, date und awk — alles macOS-Standard. Kein DDEV erforderlich, kein Netzwerkzugriff.

Drift-Klassen

Klasse Pfad Schwelle Was wird geprüft
Skills .claude/skills/ > 90d Letzter Git-Commit pro Skill-Verzeichnis. Skills ohne Änderung in 90 Tagen könnten obsolet oder nicht mehr getestet sein.
Agents .claude/agents/*.md > 90d Letzter Git-Commit pro Agent-Datei. System-Prompt-Alignment nach Claude-Code-Updates prüfen.
Hooks .claude/hooks/*.sh > 90d Letzter Git-Commit pro Hook-Script. Hooks müssen nach Harness-Updates valide bleiben.
Top-Level-Docs CLAUDE.md, AGENTS.md, CONTEXT.md anzeigen Letztes Commit-Datum aller drei Files — kein Schwellwert, nur Transparenz. Langen Stillstand manuell bewerten.
ADR proposed > 60d docs/adr/*.html > 60d ADRs mit solcom:status = proposed älter als 60 Tage. Unentschiedene ADRs blocken Architektur-Klarheit.
Docs-Lint-Periodik docs/LOG.html > 30d Letzter lint-pass-Eintrag in LOG.html. Wenn älter als 30 Tage: Skill solcom-docs-lint laufen lassen.
permissions.deny .claude/settings.json Sanity Prüft ob ein permissions.deny-Block vorhanden ist. Sanity-Check nach Settings-Änderungen.

Recommended Actions bei Drift

  • Stale Skills: Skill aufrufen und prüfen ob Trigger-Phrases noch zu Claude Code passen. Obsolete Skills archivieren (umbenennen zu *.ARCHIVED.md oder in .claude/skills/_archive/ verschieben). Aktive Skills mit neuem Commit aktualisieren.
  • Stale Agents: System-Prompt und Tool-Allowlist gegen aktuelle Claude-Code-Harness-Version prüfen. Bei Drift: gezieltes Update, Commit mit Begründung, LOG.html-Eintrag op=sync.
  • Stale Hooks: Hook manuell triggern und Output validieren. Fehlerhafte Hooks deaktivieren (settings.json Eintrag entfernen) bis der Fix committed ist.
  • Überfällige ADRs: ADR Decision Sprint einplanen — Skill solcom-adr-workflow. Jeder proposed ADR braucht entweder accepted, rejected oder Vertagungs-Kommentar mit Zieldatum.
  • Docs-Lint overdue: Claude Code Session starten, Skill solcom-docs-lint laufen lassen. Findings priorisieren (stale > orphan > broken-link > status-drift). Nach Cleanup: LOG.html-Eintrag op=lint-pass.
  • permissions.deny fehlt: Minimalen Deny-Block in .claude/settings.json ergeben — zumindest Produktions-Credential-Pfade und Deployment-Targets sperren.

Verantwortlichkeit

Rolle Aufgabe
Site Owner Führt das Script aus, bewertet Findings, entscheidet über ADR-Timing und Skill-Archivierung. Schreibt LOG.html-Eintrag nach jedem Audit-Lauf (op=sync, Strand agents).
Co-Maintainer Reviewt den generierten Report (/tmp/claude-audit.md), gibt Feedback zu Findings, kann selbst den Lint-Pass triggern wenn Site Owner nicht verfügbar.

DRI-Details (Strand-Ownership) in AGENTS.md, Section DRI / Ownership.

Termin-Pflege

Audit Fällig am Notiz
Initialer Audit (dieser Run) 2026-05-18 Baseline-Lauf, Script neu eingeführt.
Nächster Quarterly Audit 2026-08-16 In Kalender eintragen. Reminder in Jira als Sub-Task unter Sprint-Planung Q3 2026 optional.
Folge-Audit 2026-11-14 +90 Tage vom Q3-Termin.

Script selbst gibt am Ende das nächste fällige Datum aus (date -v+90d auf macOS).