Kontext-Audit
Repositories, die diese Konvention übernehmen, behalten einen kleinen Satz persistenter Dateien, damit Agenten nicht in jeder Sitzung dasselbe neu ableiten: die Konventionen des Projekts (AGENTS.md), was bereits entschieden wurde und warum (memory.md) und eine grobe Übersicht über die Codebasis (.agent/graph.md). Dieser Skill überprüft, ob diese Dateien existieren und aktuell sind, bevor du dich auf sie verlässt oder bevor du zurückfällst auf das manuelle Scannen des Repos.
Auslösephrasen
Sitzungsstart / Vertrauenscheck
- „Bring mich auf den neuesten Stand zu diesem Repo“
- „Was weißt du über dieses Projekt?“
- „Sollte ich AGENTS.md / memory.md vertrauen?“
- „Sind die Kontextdateien aktuell?“
- „Kontext prüfen“ / „Kontext-Audit“
Veraltung
- „Ist AGENTS.md veraltet?“ / „Ist memory.md veraltet?“
- „Wie viele Commits seit der letzten Synchronisation?“
- „Sind meine Agentendateien aktuell?“
- „Prüfen, ob Kontext veraltet ist“
Token-Kosten
- „Wie viel sparen die Kontextdateien ein?“
- „Token-Ersparnis“ / „Kontextkosten“
- „Token-Ersparnis benchmarken“
- „Basislinie vs. kuratierte Tokens“
Einrichtung / Onboarding
- „AGENTS.md einrichten“ / „Kontext initialisieren“
- „ctx-audit installieren“ / „Kontext-Hook einrichten“
- „KI-Kontext einrichten“ / „Ist dieses Projekt KI-bereit?“
CI / Automatisierung
- „ctx-audit zu CI hinzufügen“
- „Pre-Push-Hook hinzufügen“
- „Kontextaktualität in CI erzwingen“
Architektur
- „Habe ich eine Architekturübersicht?“
- „graph.md generieren“ / „Graphify ausführen“
So wird es ausgeführt
Die empfohlene Methode, ctx-audit auszuführen:
npx ctx-audit
Alternativ, wenn als Skill installiert:
node <Pfad-zu-diesem-Skill-Ordner>/../scripts/audit.mjs
Flags:
--json– maschinenlesbare Ausgabe (verwende dies, wenn du programmatisch auf das Ergebnis reagieren möchtest).--strict– Exit-Code 1, wenn etwas fehlt oder veraltet ist.--ci– Alias für--strict --json.--help– Verwendung anzeigen und beenden.
Unterbefehle
# AGENTS.md + memory.md einrichten (interaktiv – schreibt Dateien direkt ins Repo-Root)
npx ctx-audit init
# Ein-Befehl-Installation: kopiert Skill nach ~/.claude/skills/, registriert in CLAUDE.md
npx ctx-audit install
# Git-Hook: führt --strict-Audit bei jedem Push aus
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall
# Projekt-CLAUDE.md: fügt Anweisungsblock für Agenten hinzu
npx ctx-audit claude install
npx ctx-audit claude uninstall
# Token-Ersparnisbericht (fokussiertes, teilbares Format)
npx ctx-audit benchmark
Agenten-Entscheidungstabelle
| Status | Bedeutung | Aktion |
|---|---|---|
| FRESH | Weniger als die Hälfte des Veraltungsschwellenwerts an Commits seit letztem Sync | Vertraue der Datei – lies sie anstatt rohen Quellcode zu scannen |
| STALE? | Nähert sich dem Schwellenwert (möglicherweise veraltet) | Leichte Vorsicht – überprüfe kritische Behauptungen stichprobenartig, bevor du dich darauf verlässt |
| STALE! | Schwellenwert überschritten, zählt als Fehler | Behandle Behauptungen als unbestätigt; überprüfe stichprobenartig gegen den tatsächlichen Code; aktualisiere nach der Sitzung |
| STALE | Deutlich zurück, zählt als Fehler | Wie bei STALE!, aber dringlicher; sofort nach der Sitzung aktualisieren |
| MISSING (erforderlich) | Datei existiert nicht | Führe npx ctx-audit init aus; fahre nicht fort, als ob die Konvention eingerichtet wäre |
| absent (optional) | Optionale Datei nicht vorhanden | Akzeptabel; erwäge, /graphify auszuführen, um graph.md zu generieren |
| over budget | Token-Anzahl überschreitet maxTokens | Datei ist aufgebläht – kürze sie; sie zu lesen könnte mehr kosten, als es spart |
| dead reference | Backtick-Pfad oder dir/file.ext in Datei existiert nicht auf der Festplatte | Aktualisiere die Referenz; die Datei dokumentiert veraltete Struktur |
| SHA bumped | last_synced_commit aktualisiert, aber Inhalt unverändert | Überprüfe, ob die Datei tatsächlich aktuelle Änderungen widerspiegelt; könnte ein mechanischer Bump sein |
Ergebnisse interpretieren
- MISSING (erforderliche Datei): Fahre nicht fort, als ob die Konvention eingerichtet wäre.
Biete an, eine Startdatei zu erstellen (führe
npx ctx-audit initaus), anstatt ohne eine zu arbeiten oder stillschweigend den alten „Alles manuell erkunden“-Ansatz zu verfolgen. - FRESH: Die Datei ist aktuell. Lies sie anstatt rohen Quellcode zu scannen.
- STALE? (möglicherweise veraltet): Nähert sich dem Schwellenwert. Überprüfe kritische Behauptungen stichprobenartig.
- STALE! (wahrscheinlich veraltet): Behandle ihre Behauptungen als unbestätigt. Überprüfe tragende Behauptungen stichprobenartig gegen den tatsächlichen Code, und aktualisiere nach deiner Sitzung die Datei und ihren
last_synced_commit. - STALE: Deutlich zurück. Gleiche Behandlung wie STALE!, aber dringlicher.
- Token-Zahlen sind eine Heuristik von ~3,5 Zeichen/Token – richtungsweisend nützlich, nicht exakt. Wenn eine Datei als „over budget“ markiert ist, ist sie so aufgebläht, dass das Lesen bereits das kostet, was es sparen sollte; schlage Kürzung vor.
- Dead Reference-Warnungen: Pfade, die in Kontextdateien erwähnt werden, aber nicht mehr auf der Festplatte existieren. Zeigt an, dass die Datei eine veraltete Struktur referenziert.
Praxisbeispiele
Basis-Audit zu Sitzungsbeginn:
npx ctx-audit
CI-Gate (Build fehlschlagen lassen, wenn Kontext veraltet ist):
# .github/workflows/ctx-audit.yml
- name: Kontextaktualität prüfen
run: npx ctx-audit --strict
JSON-Ausgabe für programmatische Nutzung:
npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'
Ein-Befehl-Onboarding:
npx ctx-audit install # kopiert Skill, registriert in CLAUDE.md
npx ctx-audit hook install # fügt Pre-Push-Schutz hinzu
npx ctx-audit claude install # fügt Hinweis zur Projekt-CLAUDE.md hinzu
npx ctx-audit init # erstellt AGENTS.md + memory.md
Nur Veraltung eines bestimmten Subsystems prüfen (via Frontmatter):
---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---
Nur Commits, die src/auth/ oder src/api/ betreffen, zählen für diese Datei zur Veraltung.
Token-Ersparnis benchmarken:
npx ctx-audit benchmark
Konfiguration
Lege .ctx-audit.json im Repo-Root ab, um das Verhalten anzupassen:
{
"files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
"sourceDirs": ["src", "packages/core"],
"staleThreshold": 10,
"baselineFileCap": 300
}
Frontmatter
Jede Kontextdatei sollte mit Frontmatter beginnen:
---
last_synced_commit: <git sha>
watches: src/auth/**, src/api/**
---
Das Feld watches (optional) schränkt die Veraltungsprüfung auf Commits ein, die diese Pfade betreffen, anstatt alle Quellverzeichnisse.
Wenn erforderliche Dateien fehlen – erstelle sie
Führe npx ctx-audit init aus, um Vorlagen zu generieren. In einem TTY schreibt es Dateien direkt in das Repo-Root; bei Weiterleitung gibt es auf stdout aus. Das Legacy-Flag --init wird weiterhin als abwärtskompatibler Alias unterstützt.
AGENTS.md – stabile Projektkonventionen: Build-/Test-/Lint-Befehle, Dateistrukturregeln, Dinge, die der Agent niemals tun darf. Sollte sich selten ändern.
memory.md – ein laufendes Entscheidungsprotokoll, keine Neuformulierung des aktuellen Codes. Jeder Eintrag: Was wurde versucht, was wurde entschieden, warum und was unter geänderten Umständen neu überdacht werden sollte. Anhängen, keine Geschichte umschreiben.
.agent/graph.md (optional, aber empfohlen, sobald das Repo wächst) – ein Absatz pro Hauptmodul, der seine Verantwortung und seine Kommunikationspartner beschreibt. Keine Dateiinhalte, kein erschöpfender Baum – nur so viel, dass ein Agent navigieren kann, ohne alles noch einmal zu lesen. Tipp: Führe /graphify aus, um dies automatisch aus der Codebasis zu generieren, anstatt es von Hand zu schreiben.
Nachdem du eine dieser Dateien erstellt oder aktualisiert hast, aktualisiere ihren last_synced_commit auf den aktuellen HEAD, damit das nächste Audit sie nicht sofort als veraltet markiert.