KI AGENTS.md erstellen / überprüfen
Zwei Modi: Erstellen einer neuen AGENTS.md oder Überprüfen einer vorhandenen anhand forschungsgestützter Qualitätsstandards.
Moduserkennung
- Benutzer gibt eine vorhandene AGENTS.md an oder verweist auf eine → Prüfmodus
- Benutzer bittet um Erstellung/Gerüst/Generierung → Erstellungsmodus
- Unklar → Frage:
(e)rstelle neue AGENTS.md oder (ü)berprüfe bestehende?
Erstellungsmodus
Schritt 1: Standortabfrage
Wo soll die AGENTS.md platziert werden?
(r)oot — Repo-weite Basis
(p)fad — bestimmtes Verzeichnis (Pfad angeben)
Für Monorepos: Root + paketweise Dateien vorschlagen. Die nächstgelegene AGENTS.md gewinnt.
Falls eine AGENTS.md bereits am Zielpfad existiert → frage: Datei existiert. (ü)berprüfe bestehende / (ü)berschreibe / (B)eenden?
Schritt 2: Expertenanalyse
Vor dem Schreiben muss für DIESES Projekt ermittelt werden:
- Was ist nicht ermittelbar? Was lässt sich nicht aus package.json, Konfigurationen oder der Verzeichnisstruktur ableiten?
- Was ist gefährlich? Welche Befehle oder Muster verursachen stille Fehler?
- Was ist mehrdeutig? Wo gibt es zwei gültige Ansätze und der Agent würde den falschen wählen?
- Was ist nicht standardmäßig? Welche Konventionen weichen von den Framework-Standards ab?
Wenn alle Antworten "nichts" sind — das Projekt benötigt möglicherweise keine AGENTS.md. Das sollte man mitteilen.
Für Repos ohne package.json oder Build-Konfigurationen (nur Dokumentation, Daten-Repos, einfache Skripte): Konzentration nur auf Mission + Bewertungsgrenzen — die Abschnitte zu Toolchain und Abschluss sind nicht anwendbar.
Schritt 3: In Prioritätsreihenfolge schreiben
Abschnitte NUR hinzufügen, wenn sie den "Nicht ermittelbar"-Test bestehen, in dieser Reihenfolge:
- Mission (2–4 Sätze) — Projektzweck + Kernbeschränkung, die der Agent nicht ableiten kann
- Toolchain-Registrierung — Befehle als Tabelle, NICHT was Tools erzwingen
- Bewertungsgrenzen — Stufen NIEMALS / FRAG / IMMER
- Abschlussdefinition — "Erledigt" = spezifische Exit-Codes
- Eskalationsregeln — was tun, wenn blockiert
- Aufgabenorientierte Abschnitte — "Beim Schreiben… / Beim Überprüfen… / Beim Veröffentlichen…"
Schritt 4: Validieren
- Gesamt ≤ 150 Zeilen (optimal: 60–100)
- Jeder Abschnitt ≤ 50 Zeilen
- Jede Anweisung beantwortet: "Welcher Befehl beweist, dass dies erledigt wurde?"
- Jedes "nicht" ist mit einem "tue" gepaart
- Keine Linter-Regeln wiederholt (Toolchain zuerst)
- Keine Prosa-Absätze ohne Befehle
VERPFLICHTEND — LIES references/knowledge-base.md für forschungsgestützte Muster und Belege.
VERPFLICHTEND — LIES references/template.md für die Startstruktur.
Lade references/example.md NUR, wenn der Benutzer fragt, wie eine fertige AGENTS.md aussieht, oder wenn das Repo ein JS/TS-Monorepo ist (es ist ein Turborepo + pnpm-Arbeitsbeispiel) — überspringe es andernfalls.
Lade NICHT references/knowledge-base.md im Prüfmodus, wenn die Ziel-AGENTS.md < 20 Zeilen ist — die Körper-Checkliste und die Antimuster-Liste reichen für trivial kurze Dateien aus.
Prüfmodus
Bewerte die bereitgestellte AGENTS.md anhand forschungsgestützter Qualitätskriterien.
Bewertungsdimensionen
| Dimension | Gewicht | Was zu prüfen ist |
|---|---|---|
| Signaldichte | 25% | % der Zeilen, die nicht ermittelbares Expertenwissen vs. generisch/redundant sind |
| Befehlsorientierung | 20% | Jede Anweisung hat einen überprüfbaren Befehl oder Exit-Code |
| Abschlussdefinition | 15% | Explizite "Erledigt"-Kriterien mit spezifischen Prüfungen |
| Grenzsystem | 15% | Stufen NIEMALS/FRAG/IMMER vorhanden und spezifisch |
| Längendisziplin | 10% | ≤150 gesamt, ≤50 pro Abschnitt, keine Aufblähung |
| Antimuster-Abwesenheit | 15% | Frei von erwiesenermaßen fehlschlagenden Mustern |
Bewertungsrichtlinien
- Bewerte streng bei der Signaldichte für ausgereifte Repos mit etablierten Toolchains — der meiste Inhalt ist wahrscheinlich redundant
- Bewerte nachsichtig bei Abschluss/Grenzen für Neuland-Projekte — sie haben möglicherweise noch keine CI-Gates
- Bewerte streng bei der Länge für Monorepo-Root-Dateien — diese werden in jeder Sitzung über alle Pakete hinweg geladen
- Wenn die Gesamtpunktzahl < 40: Neuschreibung anstelle von inkrementellen Korrekturen empfehlen
Antimuster-Checkliste
Markiere jedes dieser Muster (empirisch nachgewiesen, die Agentenleistung zu verschlechtern):
- Prosa-Absätze ohne Befehle
- Mehrdeutige Anweisungen ("vorsichtig sein", "wo möglich")
- Widersprüchliche Prioritäten ohne explizite Ordnung
- Stilregeln, die bereits durch die Linter-Konfiguration erzwungen werden
- Architekturüberblicke (führt zu übermäßiger Erkundung)
- 15+ Warnungen ohne gepaarte Alternativen
- LLM-generierte Boilerplate aus
/init-Befehlen - Wiederholung dessen, was die Toolchain erzwingt
- Pink-Elefant-Verstöße (lange "nicht"-Listen, die verbotene Konzepte aktiv halten)
Ausgabeformat
## AGENTS.md-Prüfung: <Dateiname oder Pfad>
**Punktzahl**: X/100
**Urteil**: [Produktionsbereit / Verbesserung erforderlich / Neuschreibung empfohlen]
### Stärken
- ...
### Probleme (nach Schweregrad)
1. [KRITISCH] ...
2. [HOCH] ...
3. [NIEDRIG] ...
### Vorschläge zur Neuschreibung
1. ...
2. ...
Anwenden
Die Prüfung ist nicht das Ergebnis — eine bessere AGENTS.md ist das. Nach der Präsentation anbieten:
Anwenden? (a)lle / (n)ach Nummer auswählen / (k)eine
Bei (a) oder (n): die Datei direkt bearbeiten, einen nummerierten Punkt nach dem anderen, dann die Bewertungsdimensionen erneut durchlaufen und die neue Punktzahl neben der alten melden. Jede Zeile, die die Prüfung nicht bemängelt hat, bleibt wortwörtlich erhalten — eine Prüfung ist kein Neuschreibungsbefehl, und das stille "Verbessern" nicht bemängelter Prosa zerstört die Stimme und Absicht des Autors.
Das Angebot überspringen, wenn der Benutzer den Inhalt inline statt als Pfad bereitgestellt hat oder die Datei nicht beschreibbar ist. Dies mitteilen, anstatt Verbesserungen als angewendet zu melden.
VERPFLICHTEND — LIES references/knowledge-base.md für die Forschungsevidenz hinter jedem Kriterium.
NIEMALS
- NIEMALS Inhalt einfügen, den der Agent aus der Repo-Struktur ermitteln kann — package.json-Skripte, Verzeichnislayout und Konfigurationsdateien sind selbstdokumentierend; deren Wiederholung verschwendet Tokens und verursacht Wartungsdrift. STATTDESSEN: auf die Datei verweisen (
siehe biome.json) und weitermachen. - NIEMALS Linter/Formatter-Regeln wiederholen — das Tool IST die Einschränkung; Duplikation erzeugt Veraltung und unnötige Anforderungen schaden aktiv der Agentenleistung. STATTDESSEN: nur den Ausführungsbefehl auflisten (
Lint: \pnpm lint``). - NIEMALS ein "nicht" ohne gepaartes "tue" schreiben — Dokumentation nur mit Warnungen verursacht übermäßige Erkundung; 15+ "nicht" ohne Alternativen macht Agenten konservativ und weniger produktiv. STATTDESSEN: jedes Verbot mit der korrekten Alternative paaren.
- NIEMALS 150 Zeilen überschreiten — jenseits dieser Schwelle kehren sich die Gewinne um und die Datei schadet aktiv der Qualität. STATTDESSEN: Details in referenzierte Dateien auslagern oder löschen.
- NIEMALS LLM-generierte Inhalte als endgültig verwenden —
/init-Ausgabe ist ein Inventar dessen, was der Agent bereits weiß; es reduziert die Leistung und erhöht die Kosten. STATTDESSEN: als Entwurfsinventar behandeln, dann alles entfernen, was die Toolchain bereits erzwingt. - NIEMALS Prosa-Absätze schreiben — Agenten überspringen sie; verwende Befehle, Tabellen und Aufzählungspunkte mit überprüfbaren Ergebnissen. STATTDESSEN: in Befehl + Exit-Code + einzeilige Beschreibung umwandeln.