jimweller/documenter-plugin

Projektdokumentation aktualisieren

Zwei Verantwortlichkeiten:

1. CLAUDE.md — präziser Projektüberblick (immer geladen)
2. .llmdocs/ — detaillierte konzeptbezogene Dokumente (bei Bedarf geladen). Alle Dateien hier sind dauerhafte Designdokumente.

---

1. CLAUDE.md — Die Karte

Geltungsbereich

Finde alle CLAUDE.md- und .llmdocs/-Verzeichnisse im Projekt und aktualisiere jedes. Achte auf Unterordnerebenen, Geltungsbereiche und begrenzte Kontexte. Vermische keine Konzepte zwischen Dokumenten auf verschiedenen Ebenen. Jede CLAUDE.md und jedes .llmdocs/ deckt seine eigene Verzeichnisebene und darunter liegende Ebenen ab, niemals übergeordnete Belange.

Wenn der Benutzer spezifische Hinweise oder Schwerpunkte gegeben hat, wende diesen Kontext an, um zu entscheiden, welche Dokumente aktualisiert und worauf der Schwerpunkt gelegt werden soll.

Kontext sammeln

Führe git niemals 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-Stamm aus aus und schreibe jedes Mal den vollständigen Pfad des Skripts, da Shell-Variablen nicht zwischen Befehlen bestehen bleiben.

Beginne mit dem Plan. Er findet jede CLAUDE.md und ihr .llmdocs/, einschließlich erforderlicher Dateien, die noch nicht existieren, ermittelt die Ausgangsbasis jedes Dokuments, listet auf, was sich seitdem geändert hat, und gibt an, was mit jedem Dokument zu tun ist. Wenn die Anleitung des Benutzers Verzeichnisse nennt, auf die man sich konzentrieren soll, übergib sie nach llmdocs. Ansonsten übergib nichts.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<fokus-verz>...]

Der Plan gibt einen Block pro Aktion aus.

• ## update nennt eine Ausgangsbasis, einen Geltungsbereich und die Dokumente, die ihn teilen, gefolgt von den Commits, der Diff-Statistik und dem Status seit dieser Basis. Bringe diese Dokumente auf den neuesten Stand. Ein Dokument, das von den Änderungen nicht betroffen ist, behält seinen Inhalt.
• ## new listet Dokumente auf, die aus dem aktuellen Code geschrieben werden sollen. Sie benötigen keine Historie.
• ## unchanged und ## outside the focus listen Dokumente auf, die genau so bleiben, wie sie sind.

head none bedeutet, dass das Repository keine Commits hat. Jedes Dokument ist neu.

Zähle für einen 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, gekennzeichnet mit ??, erscheinen in keinem Diff, also lies sie in beiden Fällen direkt. Der Gültigkeitsbereich kann der Geltungsbereich des Blocks oder eine einzelne Datei sein, da es sich um einen Git-Pathspec handelt.

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

Dann, für jedes CLAUDE.md/.llmdocs/-Paar mit zu aktualisierenden oder zu schreibenden Dokumenten:

1. Lies das aktuelle CLAUDE.md und jede Datei in .llmdocs/ (falls vorhanden)
2. Erkunde die Codebasis auf dieser Verzeichnisebene und darunter
3. Überprüfe den Konversationsverlauf auf relevante Entscheidungen, Änderungen oder gewonnene Erkenntnisse
4. Verwende die Änderungen und den Gesprächskontext, um zu identifizieren, was sich geändert hat. LLM-Dokumente sind eine Spezifikation des aktuellen Zustands, kein Änderungsprotokoll, kein Entscheidungsprotokoll, kein historischer Bericht. Halte niemals historische Informationen oder getroffene Entscheidungen fest, sondern nur die Spezifikation, wie sie zum Zeitpunkt des Schreibens der LLM-Dokumente besteht.

CLAUDE.md schreiben/aktualisieren

Ziel: unter 500 Zeilen. Jede Zeile muss ihren Platz verdienen.

# <Name>

<1-2-zeiliger Zweck dieses Verzeichnisses/Komponente>

## Stack

<Aufzählungsliste: Sprache, Frameworks, wichtige Abhängigkeiten auf dieser Ebene>

## Layout

<wichtige Verzeichnisse und ihren Inhalt auf dieser Ebene>

## Befehle

<Build, Test, Lint, Deploy — nur Befehle>

## Konventionen

<Stil, Namenskonventionen, Muster — nur was Fehler verhindert>

## Wichtige Konzepte

<Domain-Begriffe, Geschäftslogik, die Claude auf dieser Ebene kennen muss>

## LLM-Dokumente

Detailierte Dokumente in `.llmdocs/`:

- @.llmdocs/architecture.md — <1-zeilige Beschreibung>
- @.llmdocs/data-model.md — <1-zeilige Beschreibung>

CLAUDE.md Regeln

• KEINE ausführlichen Erklärungen — Claude inferiert
• KEINE Duplizierung von .llmdocs/-Inhalten — nur mit kurzer Beschreibung verweisen
• Der Abschnitt ## LLM-Dokumente MUSS alle .llmdocs/-Dateien mit einer 1-zeiligen Beschreibung auflisten
• Eine CLAUDE.md, die ihre .llmdocs/-Dateien unter ## Docs aufführt, stammt vor der aktuellen Überschrift. Benenne diese Überschrift in ## LLM Dokumente um, sobald du die Datei aktualisierst
• Erhalte vorhandene benutzerdefinierte Anweisungen (Git-Workflow, Umgebungsvariablen usw.)
• Entferne Inhalte nur, wenn der Code ihnen widerspricht, und nenne jede Entfernung in der Zusammenfassung
• Wenn der Code eine Funktion, ein Flag oder ein Modul entfernt, durchsuche jedes Dokument dieser Ebene mit grep nach seinem Namen, lies dann jeden Treffer und die Zweckzeile jedes Dokuments erneut auf eine beschreibende Beschreibung derselben Sache. Das Entfernen des Namens aus einem Dokument reicht nicht aus

grep -rn '<entfernter Name>' <verz>/CLAUDE.md <verz>/.llmdocs

• Füge die Markerzeile niemals in Text ein, den du schreibst oder bearbeitest. finish fügt sie nach dem Schreiben hinzu. Wenn du ein Dokument bearbeitest, das bereits mit einer endet, lasse diese Zeile in Ruhe
• Verwende @.llmdocs/filename.md import, wenn ein Dokument immer geladen werden soll

---

2. .llmdocs/ — Das Territorium

Prozess

Eine Konzeptdatei über die sieben erforderlichen hinaus darfst du hinzufügen, und der Plan nennt sie nie. finish stempelt sie trotzdem, zusammen mit jedem anderen Dokument dieser Ebene, das während des Laufs erstellt wurde.

1. Bewerte: Verwende die Update-Blöcke des Plans, um zu ermitteln, welche Dokumente betroffen sind
2. Identifiziere: Bestimme, welche vorhandenen Dokumente betroffen sind oder ob ein neues Dokument benötigt wird
3. Aktualisiere CLAUDE.md: Stelle sicher, dass der Abschnitt ## LLM-Dokumente alle neuen Dokumentdateien auflistet

Wenn sich nichts geändert hat, das eine Dokumentationsaktualisierung rechtfertigt, sage das und fahre fort.

Ort

Verwende den Pfad, den der erste Import unter der Überschrift ## LLM-Dokumente der CLAUDE.md nennt, oder unter ## Docs in einer CLAUDE.md, die vor dieser Überschrift existiert. Ansonsten standardmäßig .llmdocs/ auf der Zielebene des Verzeichnisses. CLAUDE.md und .llmdocs/ können auf jeder Verzeichnisebene im Projekt existieren.

Struktur

Flach, 1 Datei pro Konzept. Die ersten 7 Dateien sind erforderlich und müssen immer existieren. testing.md wird erstellt, wenn das Projekt eine Testsuite hat, und weggelassen, wenn es keine hat. Zusätzliche Konzeptdateien werden nach Bedarf erstellt.

.llmdocs/
  architecture.md    # Komponenten, Interaktionen, Datenfluss (erforderlich)
  api.md             # Endpunkte, Anfrage/Antwort, Authentifizierung, Autorisierung (erforderlich)
  data-model.md      # Schema, Modelle, Beziehungen (erforderlich)
  deployment.md      # Bereitstellungsprozess, Umgebungen (erforderlich)
  ops.md             # Runbooks, Wartung, Fehlerbehebung (erforderlich)
  observability.md   # Logs, Metriken, Traces, Health Checks, Dashboards, Warnungen (erforderlich)
  security.md        # Vertrauensgrenzen, Umgang mit Geheimnissen, Authentifizierung/Autorisierung, Bedrohungsmodell (erforderlich)
  testing.md         # Testlayout, Testrunner, Testhilfsmittel, wie man die Suite ausführt (wenn das Projekt Tests hat)
  <konzept>.md       # Domänenspezifisch nach Bedarf

Dokumentdatei-Format

# <Konzept>

<1-zeiliger Zweck>

## <Abschnitt>

<Inhalt: Überschriften, Tabellen, Codeblöcke — keine Prosa-Absätze>

.llmdocs/ Regeln

• Maximal 500 Zeilen pro Datei — bei Größerem aufteilen
• Füge Dateipfade mit Zeilenverweisen ein, wo nützlich (src/auth/login.ts:42)
• Aktualisiere vorhandene Dokumente inkrementell, schreibe sie nicht von Grund auf neu
• Wenn ein Dokument korrekt und von den letzten Änderungen nicht betroffen ist, lasse seinen Inhalt in Ruhe. finish aktualisiert trotzdem seinen Marker.
• Genauigkeit vor Vollständigkeit: dokumentiere nur, was aus dem Code verifizierbar ist
• observability.md enthält die Signale, die das System aussendet, und ops.md enthält die Aktionen, die ein Betreiber ausführt. Ein Health-Endpunkt, ein Log-Format oder eine Warnung gehört in observability.md. Ein Projekt ohne Metriken oder Traces dokumentiert trotzdem seine stdout, stderr und Exitcodes dort
• Füge die Markerzeile niemals in Text ein, den du schreibst oder bearbeitest. finish fügt sie nach dem Schreiben hinzu. Eine Konzeptdatei, die du erstellst, ist hier die Falle, denn jedes Geschwisterdokument, das du gerade gelesen hast, endet mit einer. Das Kopieren dieser Zeile schreibt eine veraltete SHA, die behauptet, das Dokument sei gegen einen Commit geprüft worden, den es nie gesehen hat. Beende eine neue Datei mit ihrer letzten Inhaltszeile und lass finish den Marker hinzufügen

---

3. Abschluss

Führe finish jedes Mal aus, auch bei einem Lauf, der nichts geschrieben hat. plan hat eine Plan-Datei hinterlassen, und nur finish entfernt sie. Ein Lauf, der finish überspringt, hinterlässt einen Zustand, über den der nächste Lauf stolpert.

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

Es stempelt jedes Dokument, das der Plan als neu oder zu aktualisieren markiert hat, und jedes Dokument, das seit dem Plan erstellt wurde, wie z. B. testing.md, mit dem HEAD, den der Plan geprüft hat. Der Stempel ist eine Markerzeile am Ende des Dokuments, ein HTML-Kommentar, der diesen Commit nennt. finish lässt unveränderte Dokumente und Dokumente außerhalb des Fokus in Ruhe und stempelt nichts, wenn das Repository keine Commits hat. Exit 4 bedeutet, dass ein geplantes Dokument fehlt. Schreibe es und führe finish erneut aus.

• Rufe stamp niemals direkt auf und schreibe oder bearbeite die Markerzeile niemals von Hand. finish schreibt sie.
• Der Marker ist Metadaten. Die Regel gegen die Aufzeichnung von Historie gilt nicht für ihn.

---

4. Zusammenfassung der Ausgabe

Gib nach der Ausführung diese Zusammenfassung aus. Fülle jede Zeile aus dem Lauf und schreibe „none", wo eine Liste leer ist. Kopiere unter „Gestempelt" die eigenen Zeilen von finish wörtlich, eine pro Dokument. Schreibe dort niemals eine SHA und füge niemals ein Wort hinzu, das finish nicht gedruckt hat.

Ein Satz, der umformuliert wurde, um eine Fähigkeit zu entfernen, ist eine Entfernung. Nenne sie unter „Entfernt" mit der Formulierung, die verschwunden ist, auch wenn dieselbe Zeile noch existiert.

Ausgefülltes Beispiel, von einem Lauf, bei dem der Code die Zeichenzählung entfernt hat.

Erstellte Dateien: none
Geänderte Dateien: CLAUDE.md, .llmdocs/api.md
CLAUDE.md Abschnitte hinzugefügt, aktualisiert oder entfernt: Wichtige Konzepte aktualisiert
Entfernt, weil der Code dem widerspricht:
- CLAUDE.md: "oder Zeichen" aus der Zweckzeile und das --chars Schlüsselkonzept
- .llmdocs/api.md: die count_chars Zeile
Gestempelt:
- gestempelt CLAUDE.md (Markierung)
- gestempelt .llmdocs/api.md (Markierung)

Wenn die Änderungen keine Dokumentationsaktualisierung rechtfertigen, schreibe „keine Dokumentationsänderungen erforderlich" über die Zusammenfassung.