Dokumentation-Bootstrap
Dies ist eine gelegentliche Sammelaufgabe. Für nachfolgende Änderungen verwenden Sie engineering:documentation-sync.
1. Bestandsaufnahme
Listen Sie die vorhandenen Dokumente auf und kennzeichnen Sie jedes als vorhanden, dünn (vorhanden, aber größtenteils leer oder veraltet) oder fehlend. Prüfen Sie mindestens:
README.md, CONTRIBUTING.md, CHANGELOG.md, ARCHITECTURE.md oder docs/architecture/, Entscheidungsprotokolle, CLAUDE.md, SECURITY.md, LICENSE, die API-Referenz, die Konfigurationsreferenz, Runbooks.
git ls-files '*.md' | grep -v node_modules
2. Lassen Sie den Benutzer wählen
Zeigen Sie das Menü aus resources/doc-catalog.md. Kennzeichnen Sie jeden Typ als vorhanden, dünn oder fehlend. Markieren Sie die Typen, die Sie für diese Art von Projekt empfehlen.
- Vorhandene Dokumente werden nicht neu geschrieben. Der Benutzer kann für ein dünnes Dokument „überarbeiten“ wählen.
- Der Benutzer wählt aus. Schreiben Sie keinen Typ, den der Benutzer nicht ausgewählt hat.
3. Erstellen des Faktenblatts
Bevor jemand schreibt, sammeln Sie die Fakten, die von mehr als einem Dokument verwendet werden. Entnehmen Sie sie dem Code und Git, nicht dem Gedächtnis. Schreiben Sie sie in eine temporäre Datei.
| Fakt | Quelle |
|---|---|
| Projektname und Zweck in einem Satz | README, Manifest, der Benutzer |
| Aktuelle Version | Manifest, letzter Tag (git describe --tags --abbrev=0) |
| Sprachen, Frameworks und deren Versionen | Manifeste und Lock-Dateien |
| Install-, Test-, Lint-, Build- und Run-Befehle | engineering:development-commands |
| Komponenten und deren Namen | Verzeichnisstruktur, Einstiegspunkte, Docker-Compose-Dateien |
| Umgebungsvariablen und Einstellungen | .env.example und der Code, der Einstellungen liest (Suche nach process.env, os.environ, getenv) |
| Wichtige Daten | Erster Commit (git log --reverse), die Tags |
| Was heute funktioniert, was nicht | Der Benutzer, offene Issues |
Wenn zwei Quellen sich widersprechen, fragen Sie den Benutzer. Wählen Sie nicht stillschweigend eine aus. Jeder Autor verwendet nur das Faktenblatt und den Code.
4. Schreiben
- Drei Dokumente oder weniger: Schreiben Sie sie selbst nacheinander.
- Mehr als drei: Starten Sie einen Unter-Agenten für jedes Dokument oder jede kleine Gruppe, höchstens vier gleichzeitig. Geben Sie jedem Unter-Agenten:
- die genaue Datei oder Dateien, die ihm gehören, sowie die Regel, dass er keine andere Datei ändern darf;
- das Faktenblatt;
- die Abschnittsgliederung für seinen Typ aus
resources/doc-catalog.md; - die Anweisung, in Simplified Technical English zu schreiben (sofern das
simple-english-Skill installiert ist); - die Anweisung, Fakten zu melden, die er benötigt und nicht gefunden hat, anstatt sie zu erfinden.
Erfinden Sie keine Geschichte, Zahlen, Benutzer oder Funktionen. Schreiben Sie „TBD“ und listen Sie es für den Benutzer auf.
5. Prüfung des Satzes
Folgen Sie resources/consistency-check.md. Beheben Sie jedes Problem, bevor Sie fortfahren.
6. Commit
Legen Sie die Dokumente auf einen Branch (engineering:git-branching) und öffnen Sie einen PR (engineering:github-pr-merge). Listen Sie im PR-Body jedes neue Dokument und jedes „TBD“ auf, das eine Antwort vom Benutzer benötigt.
Verwandte Skills
engineering:documentation-sync: hält diese Dokumente danach korrekt.gener8v:brownfield: bindet eine bestehende Codebasis in die gener8v-Pipeline ein. Es schreibt.gener8v/-Kontext, nicht diese Projektdokumente.