jimweller/documenter-plugin

Dokumentationserstellung

Erstelle Markdown-Inhalte basierend auf dem aktuellen Gesprächskontext und Ordnerinhalten.

README ist die aktuelle Zustandsspezifikation für einen menschlichen Benutzer, kein Changelog, kein Entscheidungsprotokoll, kein historischer Datensatz. Gib niemals historische Informationen oder getroffene Entscheidungen wieder, sondern nur die Spezifikation, wie sie zum Zeitpunkt der Erstellung der README besteht.

Gültigkeitsbereich

Finde alle README.md-Dateien im Projekt und aktualisiere jede. Die Ordnerinhalte befinden sich auf der Ebene der README und darunter (Geschwister- und Unterordner), niemals darüber (Elternordner). Achte auf Unterordnerebenen, Gültigkeitsbereiche und abgegrenzte Kontexte. Vermische keine Konzepte zwischen Dokumenten auf verschiedenen Ebenen. Jede README deckt ihre eigene Verzeichnisebene und darunter ab, niemals Belange der Elternordnung.

Wenn der Benutzer spezifische Anleitungen oder Schwerpunkte gegeben hat, wende diesen Kontext bei der Entscheidung an, was in der Dokumentation hervorgehoben werden soll.

Kontext sammeln

Führe niemals git direkt aus. Das Basisskript, das mit diesem Plugin ausgeliefert wird, deckt alles ab, was dieses Skill von Git benötigt. Führe jeden Befehl vom Repository-Root aus und schreibe den vollständigen Pfad des Skripts jedes Mal, da Shell-Variablen nicht zwischen Befehlen bestehen bleiben.

Beginne mit dem Plan. Er findet jede README, fügt eine Root-README hinzu, wenn keine vorhanden ist, ermittelt die Basislinie jeder README, listet auf, was sich seitdem geändert hat, und sagt, was mit jeder README zu tun ist. Wenn die Anleitung des Benutzers Verzeichnisse benennt, auf die man sich konzentrieren soll, übergib sie nach readme. Andernfalls übergib nichts.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan readme [<focus-dir>...]

Der Plan gibt einen Block pro Aktion aus.

• ## update gibt eine Basislinie, einen Gültigkeitsbereich und die README an, gefolgt von den Commits, der Diff-Statistik und dem Status seit dieser Basislinie. Bringe die README auf den neuesten Stand. Eine README, die von den Änderungen nicht betroffen ist, behält ihren Inhalt.
• ## new listet READMEs auf, die aus dem aktuellen Code geschrieben werden müssen. Sie brauchen keine Historie.
• ## unchanged und ## outside the focus listen READMEs auf, die genau so belassen werden sollen, wie sie sind.

head none bedeutet, dass das Repository keine Commits hat. Jede README ist neu.

Zähle bei einem Update-Block die Dateien in seiner Statistik. Bei mehr als 20 überspringe den vollständigen Diff und lies die geänderten Dateien direkt. Bei 20 oder weniger lies den Diff. Nicht versionierte Dateien, markiert mit ??, erscheinen in keinem Diff, also lies sie direkt, egal wie viele. Der Gültigkeitsbereich kann der Blockbereich oder eine einzelne Datei sein, da es sich um eine git-Pfadspezifikation handelt.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

Dann für jede zu aktualisierende oder zu schreibende README, eingegrenzt auf ihr Verzeichnis:

1. Lese die aktuelle README (falls vorhanden)

2. Erkunde die Codebasis auf dieser Verzeichnisebene und darunter

3. Durchsuche den Gesprächsverlauf nach relevanten Entscheidungen, Änderungen oder gewonnenen Erkenntnissen

4. Nutze die Änderungen und den Gesprächskontext, um zu identifizieren, welche Abschnitte aktualisiert werden müssen. Überprüfe Code gegen Dokumentation und Dokumentation gegen Code. Wenn der Code eine Funktion, ein Flag oder ein Modul verwirft, durchsuche jede README mit grep nach ihrem Namen, lies dann jeden Treffer und die Übersicht jeder README erneut, um eine Klartext-Beschreibung derselben Sache zu finden.

   grep -rn '<gelöschter Name>' <verz>/README.md
   

Füge die Markierungszeile niemals in Text ein, den du schreibst oder bearbeitest. finish fügt sie nach dem Schreiben hinzu. Wenn du eine README bearbeitest, die bereits mit einer solchen endet, lasse diese Zeile unverändert.

Wenn sich nichts geändert hat, was ein README-Update rechtfertigt, sage das und fahre fort. finish wird trotzdem angewendet.

README.md-Gliederung

Reihenfolge und Inhalt der Abschnitte für eine README.md. Jeder Abschnitt wird aus dem Zielprojekt gefüllt. Lasse einen Abschnitt weg, zu dem das Projekt nichts beiträgt.

• # Titel und eine Übersicht von nicht mehr als fünf Sätzen
• Optionales Bild oder Video
• ## Architektur - Komponenten als Aufzählungsliste, jede mit ihrem Zweck
• ## Voraussetzungen - Konten, Schlüssel, Anmeldeinformationen, Werkzeuge, Laufzeiten, CLIs, jeweils mit Grund, warum sie benötigt werden
• ## Projektstruktur - nur Ordner, keine Dateien, jeder mit einer einzeiligen Zweckbeschreibung
• ## Installation - die Befehle zur Installation
• ## Verwendung - die Befehle zur Ausführung
• ## Tests - weggelassen, wenn das Projekt keine Tests hat

Ziel unter 500 Zeilen. Teile eine längere README auf, indem du Details in eine verschachtelte README neben dem Code verschiebst, den sie beschreibt.

Form

# Titel

Kurze Übersicht. Nicht mehr als fünf Sätze.

<!-- OPTIONALES BILD ODER VIDEO ZUR HERVORHEBUNG -->
<img src="demo.png" alt="Demo" width="800"/>

## Architektur

Komponenten auf hoher Ebene und Zweck

- Komponente - Zweck
- Komponente - Zweck

## Voraussetzungen

- Voraussetzung - Beschreibung und Grund (Konten, Schlüssel, Anmeldeinformationen, Werkzeuge, Laufzeiten, CLIs)

## Projektstruktur

Zeige die Ordnerstruktur. Keine Dateien enthalten.

```text
project/
├── src/
│   ├── component-a/     # Zweck - siehe src/component-a/README.md
│   └── component-b/     # Zweck - siehe src/component-b/README.md
├── scripts/             # Zweck
└── tests/               # Zweck
```

## Installation

```bash
# wie das Projekt installiert wird
<installationsbefehl>
```

## Verwendung

```bash
# wie das Projekt ausgeführt wird
<ausführungsbefehl>
```

## Tests

```bash
# wie die Tests ausgeführt werden
<testbefehl>
```

Abschluss

Führe finish jedes Mal aus, auch wenn nichts geschrieben wurde. plan hinterlässt eine Plan-Datei und nur finish entfernt sie, sodass ein Lauf, der finish auslässt, einen Zustand hinterlässt, über den der nächste Lauf stolpert.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish readme

Es stempelt jede README, die der Plan als neu oder zu aktualisieren markiert hat, und jede seit dem Plan erstellte README mit dem HEAD, den der Plan überprüft hat. Der Stempel ist eine Markierungszeile am Ende der README, ein HTML-Kommentar, der diesen Commit benennt. finish lässt unveränderte READMEs und READMEs außerhalb des Fokus unberührt und stempelt nichts, wenn das Repository keine Commits hat. Exit-Code 4 bedeutet, dass eine geplante README fehlt. Schreibe sie und führe finish erneut aus.

• Rufe stamp niemals direkt auf und schreibe oder bearbeite die Markierungszeile niemals von Hand. finish schreibt sie.
• Der Marker sind Metadaten. Die Regel gegen das Aufzeichnen von Verlauf gilt nicht für ihn.