Was macht agent-doc-disziplin?
Nutzen Sie dieses Skill, um beim Erstellen oder Bearbeiten jedes Dokuments, das ein Agent zum Handeln konsumiert, eine Schreibdisziplin anzuwenden: die fünf Oberflächen (CLAUDE.md, CONTEXT.md, docs/standards/, design-system/, .omc/skills/), Spezifikationen, Tickets und Skill-Dateien. Der Test, den ein Dokument bestehen muss: Eine frische Agentensitzung kann durch alleiniges Lesen darauf handeln.
Verpflichtend, wenn: Trockendock Oberflächensaaten generiert, der C5-Sedimentdurchlauf des Launches eine Lektion in einen Slot schreibt. Optional für jede andere Bearbeitung – aber jede Bearbeitung eines agentenorientierten Dokuments sollte diese Regeln überstehen.
Wann nicht anwenden
Nur für Menschen geschriebene Dokumente: narrative docs/business/-Texte, ADR-Entscheidungsgeschichten, READMEs zur menschlichen Einarbeitung. Sie dürfen die Regeln trotzdem befolgen, wo es nichts kostet, sind aber nicht an diese Disziplin gebunden.
Die Disziplin
Schreiben Sie für einen Leser ohne Chatverlauf. Das Dokument ist selbstbeschreibend: Nichts stützt sich auf „wie besprochen“, eine frühere Sitzung oder Wissen, das in jemandes Kopf lebt. Test: Eine brandneue Agentensitzung kann durch alleiniges Lesen auf das Dokument handeln.
Jede Regel prüfbar und mit einem Warum. Kein „halten Sie es sauber“ – schreiben Sie die beobachtbare Bedingung und den Grund. Test: Ein Agent kann allein aus dem Text bestehen/nicht bestehen entscheiden, und das Warum steht neben der Regel.
Eine Bedeutung, ein Zuhause. Jede Regel oder Definition hat einen einzigen autoritativen Ort; Duplikation ist Drift, die nur darauf wartet, zu passieren. Test: Das Ändern eines Verhaltens ist eine Ein-Ort-Bearbeitung.
Wiederholen Sie nie, was die Umgebung preisgibt. Package-Skripte, Verzeichnislayouts, --help-Ausgaben sind Nachschlagewerke, keine Dokumente – eine kopierte Nachschlage wird altbacken. Dokumentieren Sie nur, was nicht durch Nachschlagen gefunden werden kann: die ungeschriebene Konvention, der Grund hinter einer Wahl, die Fallgrube. Test: Jede Zeile besteht die Frage „Kann das woanders nachgeschlagen werden?“.
Schritte zuerst, Referenz hinten, seltenes Material hinter einem Verweis. Was zu tun ist, in der Reihenfolge, ganz oben; auf Abruf konsultierbare Regeln darunter; seltenes Material hinter einem Verweis, dessen Formulierung die Zweige benennt, die das Aufrufen auslösen sollten. Test: Die nächste Aktion ist innerhalb des ersten Bildschirms auffindbar.
Jeder Schritt endet mit einem Erledigungskriterium. Erledigt muss von nicht erledigt unterscheidbar sein – eine vage Grenze lädt zu vorzeitigem Abschluss ein. Test: Für jeden Schritt hat „Woher weiß ich, dass das fertig ist?“ eine Antwort im Text.
Fordern Sie das Positive. Geben Sie das Zielverhalten an; ein Verbot ist harten Leitplanken vorbehalten und wird stets mit dem positiven Ziel gepaart. Test: Jedes Verbot im Dokument benennt die stattdessen zu tuende Sache.
Entfernen Sie Seepocken beim Schreiben. Wenn das Dokument veraltetes oder redundantes Material enthält, entfernen Sie es in derselben Bearbeitung; wenn nicht, fügen Sie nur das erforderliche Material hinzu und erfinden Sie keine Löschungen. Ein Satz, den das Modell standardmäßig bereits befolgt, kostet Ladezeit für nichts – löschen Sie den ganzen Satz. Test: Jede nochmals gelesene Zeile verdient ihren Platz gegenüber „Ändert dies das Verhalten gegenüber dem Standard?“, und jedes während der Bearbeitung gefundene veraltete oder redundante Material ist entfernt.
Überprüfung
Bevor Sie eine Dokumentänderung als abgeschlossen melden, bestätigen Sie:
- eine frische Sitzung könnte darauf handeln, ohne einen Menschen etwas zu fragen
- jede Regel ist prüfbar und nennt ihr Warum; keine Regel wiederholt ein Nachschlagewerk
- Bedeutungen leben an einem Ort; Verweise nennen ihre Auslösezweige
- während der Bearbeitung gefundenes veraltetes oder redundantes Material wurde entfernt, während gültiger, nicht zusammenhängender Inhalt erhalten blieb