gener8v/gener8v.claude-skills.engineering

Dokumentation synchron halten

Code und seine Dokumente ändern sich gemeinsam, im selben Commit. Ein falsches Dokument ist schlimmer als gar keines.

Drei Arten, wie Dokumente falsch werden

• Veraltet. Das Dokument beschreibt noch das alte Verhalten, den alten Namen oder Befehl.
• Fehlend. Neues Verhalten, ein neuer Befehl oder eine neue Einstellung hat keine Dokumentation.
• Dupliziert. Dieselbe Tatsache steht an zwei Stellen. Später wird eine Kopie geändert, die andere nicht.

Schritte

1. Sieh, was sich geändert hat.

   git diff --cached --stat
   git diff --stat
   

2. Finde die eigenen Regeln des Repositorys. Lese CLAUDE.md, CONTRIBUTING.md und docs/README.md. Wenn sie sagen, welches Dokument welches Thema besitzt, folge ihnen. Sie haben Vorrang vor Schritt 3.
3. Ordne jede Änderung ihrem Besitzer zu. Verwende resources/doc-routing.md. Eine Tatsache hat ein Zuhause. Andere Dokumente verlinken darauf.
4. Finde veraltete Referenzen. Für jeden Namen, den du umbenannt oder entfernt hast (eine Funktion, ein Flag, ein Endpunkt, eine Einstellung, ein Dateipfad, ein Befehl):

   git grep -n '<alter Name>'
   

   Korrigiere jeden Treffer in einem Dokument. Führe den grep erneut aus. Die Nachbedingung ist: keine Treffer, oder nur Treffer, die bleiben müssen (z. B. ein CHANGELOG-Eintrag über die Umbenennung).
5. Bearbeite. Ändere nur das, was die Code-Änderung falsch oder unvollständig macht. Schreibe keine unzusammenhängenden Abschnitte um. Für klare Formulierungen verwende den Skill simple-english, falls installiert.
6. Commite gemeinsam. Stage die Dokumentänderungen zusammen mit dem Code. Lege sie nicht in einen späteren PR.
7. Berichte. Liste die Dokumente auf, die du geändert hast. Wenn keines geändert werden musste, sag es in einer Zeile und gib den Grund an. Zum Beispiel: „Keine Docs: internes Refactoring, keine Änderung an Verhalten, Befehlen oder Einstellungen.“

Wenn der Besitzer nicht klar ist

Frage den Benutzer. Erstelle kein neues Dokument, um der Frage auszuweichen.

Ein nützlicher Test: Ist es eine Tatsache über den aktuellen Zustand (eine Einstellung, eine Version, ein Status)? Dann gehört sie in das Referenz- oder Statusdokument. Ist es eine Prozedur (Schritte, die jemand befolgt)? Dann gehört sie in den Leitfaden, das Runbook oder den Skill, dem diese Prozedur gehört.

Spezifikationen haben Vorrang

Wenn das Repository eine SPEC.md (siehe engineering:spec-writing) oder gener8v-Spezifikationen unter .gener8v/specifications/ hat, definieren diese das beabsichtigte Verhalten.

• Wenn deine Änderung das tut, was die Spezifikation sagt, muss die Spezifikation nicht bearbeitet werden.
• Wenn deine Änderung der Spezifikation widerspricht, halte an. Informiere den Benutzer. Ändere zuerst die Spezifikation über ihren Besitzer: engineering:spec-writing für SPEC.md, gener8v:specification für Pipeline-Spezifikationen. Bearbeite die Spezifikation nicht stillschweigend, um sie an den Code anzupassen.

Pipeline-Dokumente

Bearbeite keine Dateien unter .gener8v/ von Hand. Die gener8v-Pipeline-Skills schreiben und aktualisieren sie.

Verwandte Skills

• engineering:documentation-bootstrap: wenn ein ganzes Dokument fehlt, nicht nur ein Absatz.
• engineering:github-pr-merge: führt diese Prüfung vor einem PR durch.
• engineering:github-release: liest den Unreleased-Abschnitt des CHANGELOGs, den dieser Skill aktuell hält.