teresa192/agent-readiness-audit

Bereitschaftsaudit für KI-Agenten (Readiness Audit)

Führe einen Audit des aktuellen Repositorys anhand der nachstehenden Checkliste durch und berichte über Lücken. Dies ist ein schreibgeschützter Audit: Ändere, erstelle oder lösche niemals Dateien im Repository.

Schritt 1: Den Stack erkunden

Bevor du etwas beurteilst, identifiziere:

• Sprachen, Frameworks, Paketmanager, Monorepo-Struktur
• Linter, Formatierer und Typechecker, die verwendet werden
• Test-Runner
• Hook-Manager (husky, lefthook, pre-commit, simple-git-hooks, einfache .git/hooks)
• CI-System und dessen Konfiguration
• Agenten-Anweisungsdateien (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions, etc.)
• Verzeichnisse mit Skills, Runbooks, Prompts oder Workflow-Dokumenten

Bewerte mit den Tools, die dieses Repository tatsächlich verwendet. Empfehle nicht, Tools auszutauschen, es sei denn, die aktuellen können die Aufgabe nicht erfüllen.

Budget

• Beginne mit Verzeichnisauflistungen, Konfigurationsdateien und Anweisungsdateien. Verwende grep, Zählungen und Dateiauflistungen anstatt Quelldateien vollständig zu lesen.
• Untersuche maximal 3 repräsentative Dateien pro Hauptpaket.
• Falls das Repository zu groß ist, um es vollständig zu erfassen, gib an, welche Teile nicht untersucht wurden.

Schritt 2: Jedes Checklisten-Element bewerten

Weise jedem Element einen Status zu:

• BESTANDEN (PASS): eindeutig vorhanden und funktionsfähig
• TEILWEISE (PARTIAL): vorhanden, aber unvollständig, veraltet, nicht durchgesetzt oder inkonsistent
• FEHLT (MISSING): du hast überprüft und es ist nicht vorhanden
• N/A (NICHT ANWENDBAR): trifft auf diesen Stack nicht zu (begründe warum)
• UNKLAR (UNCLEAR): du konntest es nicht überprüfen (erkläre, was dich blockiert hat, z. B. externes CI oder nicht untersuchte Teile des Repositorys)

Unterlege jeden Status mit Belegen: Dateipfade, Konfigurationsschlüssel oder kurze zitierte Auszüge (maximal 15 Wörter). Rate niemals: wenn du überprüft hast und nichts gefunden hast, markiere es als FEHLT; wenn du nicht überprüfen konntest, markiere es als UNKLAR.

Checkliste

1. Geteilte Agenten-Anweisungen
   • Einzelne, root-level Anweisungsdatei, die von allen Agenten und neuen Entwicklern gelesen wird
   • Deckt Codestil-Regeln ab (Export-Stil, Import-Struktur, Dateiorganisation, Anti-Patterns)
   • Erfordert die Validierung externer Daten an Vertrauensgrenzen
   • Gibt an, welche Tests sich lohnen
   • Definiert ein „Done“-Gate: Lint, Typecheck und relevante Tests müssen vor dem Commit bestanden werden
   • Ist aktuell und spezifisch. Überprüfe 3 bis 5 Regeln stichprobenartig am tatsächlichen Code und berichte, ob der Code sie befolgt.
2. Workflow-Skills im Repository
   • Wiederkehrende Workflows, dokumentiert als Schritt-für-Schritt-Skills oder Runbooks neben dem Code
   • Abdeckung: Commits, Erstellen/Stacken von PRs, Code-Review, PR durch CI bringen, Abhängigkeitsänderungen, Lokalisierung
   • Stack-spezifische Workflows abgedeckt (Datenebene, Router, Designsystem, Codegen, etc.)
   • Jeder Skill hat einen Auslöser, geordnete Schritte und eine Definition von „erledigt“
   • Skills sind die einzige Quelle der Wahrheit, nicht dupliziert oder widersprüchlich
3. Als Lint-Regeln durchgesetzte Konventionen
   • Dokumentierte Konventionen haben passende Lint-Regeln
   • Benutzerdefinierte Lint-Regeln oder Plugins decken projektspezifische Nutzung ab (Datenabruf, Styling, Tests, Übersetzungen)
   • Anti-Pattern-Regeln existieren für häufige Agentenfehler: verkettete oder unnötige Typbehauptungen, lose typisierte Parameter (unknown/any), bedingte Spreads von leeren Objekten, plus alle wiederkehrenden Low-Quality-Muster, die in diesem Code gefunden wurden
   • Regeln sind Fehler, keine Warnungen, ohne pauschale Deaktivierungen
4. Automatisierte Gates
   • Pre-Commit-Hook formatiert, lintet und typecheckt geänderten Code
   • Pre-Push-Hook lintet oder testet betroffene Pakete, einschließlich Abhängiger
   • CI führt dieselben Prüfungen erneut aus, sodass Hooks nicht umgangen werden können
   • Hooks sind einigermaßen schnell
   • Hooks sind eingerichtet: Hook-Konfiguration ist committed, ein Installationsschritt existiert (prepare-Skript, Setup-Dokument oder core.hooksPath), und die aufgerufenen Befehle existieren. Überprüfe durch Dateien lesen; führe niemals Hooks aus.
5. Überwachung und Struktur
   • Architekturentscheidungen dokumentiert
   • PR-Review erforderlich vor Merge (überprüfe Branch Protection oder CODEOWNERS, falls sichtbar)
   • Paket- und Modulgrenzen klar und durchgesetzt

Schritt 3: Undokumentierte Konventionen finden

Untersuche den Code auf Muster, die konsistent angewendet, aber nirgendwo niedergeschrieben sind, und auf Muster, die Agenten häufig falsch machen (lose Typisierung, unvalidierte externe Daten, inkonsistente Exporte, duplizierte Logik). Liste die 5 wichtigsten Kandidaten auf, die zur Anweisungsdatei hinzugefügt oder in Lint-Regeln umgewandelt werden sollten.

Schritt 4: Bericht

Erstelle:

1. Eine Zusammenfassungstabelle: Element, Status, einzeiliger Beleg
2. Einen Abschnitt „Lücken“: jedes TEILWEISE, FEHLT oder UNKLAR Element, was falsch ist und warum es für die Agentenzuverlässigkeit wichtig ist
3. Eine priorisierte Empfehlungsliste (höchste Hebelwirkung zuerst), jeweils mit einem konkreten nächsten Schritt und grobem Aufwand (klein/mittel/groß), formuliert in Bezug auf die vorhandenen Tools dieses Repositorys
4. Die 5 wichtigsten Kandidaten aus Schritt 3

Sei direkt. Füge kein Lob bei, um den Bericht aufzublähen. Wenn etwas in Ordnung ist, schreibe BESTANDEN und mach weiter.

Erstelle nach dem Bericht nichts, aber biete an, die fehlenden Teile zu skizzieren (Starter-Anweisungsdatei, Skill-Vorlagen, Lint-Regel-Gerüste), falls gewünscht.