Dokumentation

Dokumenttyp: Developer Playbook
Status: Draft v0.2
Stand: 2026-08-29
Prinzip: Allgemeine Anleitung mit Praxisbeispiel aus Junctar

Ziel

Dieses Dokument beschreibt, wie die Projektdokumentation von Anfang an aufgebaut wird, damit sie mitwächst statt zu verwildern — und damit ein KI-Assistent (Claude Code o. ä.) sich ohne Nachfragen zurechtfindet.

Das Problem, das diese Struktur löst

Ohne feste Rollen passiert in jedem Projekt dasselbe:

• Dieselbe Aussage steht in drei Dateien — zwei davon veraltet.
• Niemand weiß, welches Dokument bei Widerspruch gilt.
• Ein Assistent liest die falsche Datei und baut auf einem alten Stand auf.
• Eine Datei wird aktualisiert, drei abhängige nicht.

Die Gegenmittel sind eine Einstiegskette, klare Rollen je Datei und ein verbindlicher Update-Weg.

Die Einstiegskette

CLAUDE.md   ← der EINZIGE Einstieg, wird automatisch gelesen
   ↓ verweist auf
README.md   ← das Hauptdokument: Landkarte + Workflow
   ↓ verweist auf
docs/…      ← die Fachbereiche

Warum genau diese Kette: Ein Assistent liest nicht das ganze Repository. Er liest zuverlässig genau eine Datei — und die muss ihn zu allem anderen führen.

⚠️ DIE FALLE, DIE DAS IN DER PRAXIS KOSTET. Automatisch gelesen wird die CLAUDE.md im Arbeitsverzeichnis — das ist bei Fernwartung der lokale Ordner, nicht das Repo auf dem Server. Eine CLAUDE.md, die brav im Repo liegt und dort auf das README verweist, erreicht dann niemanden. In Junctar war diese Kette dadurch wochenlang offen.

Regel: Die CLAUDE.md gehört an jeden Ort, von dem aus gearbeitet wird — und wer eine ändert, ändert die andere mit. Sonst gibt es zwei Einstiege und einer ist falsch.

Die CLAUDE.md ist kurz und doppelt keine Inhalte. Sie enthält nur: wo das Projekt liegt, was zuerst zu lesen ist, und die zwei bis drei Regeln, die sonst vergessen werden. Alles andere ist ein Zeiger.

Die Bereiche und was sie tun

Ein docs/-Ordner mit nummerierten Unterordnern. Die Nummer sagt die Lesereihenfolge, nicht die Wichtigkeit.

Ordner	Rolle	Änderungsrhythmus
docs/1-status/	Was gerade gilt — Roadmap · Changelog · Übergabe	bei jeder Session
docs/2-grundlagen/	Wie es gedacht ist — Vision · Konzept · Architektur · Design	selten, dafür führend
docs/3-features/	Je ein Fachbereich — eine Datei je Feature	wenn das Feature sich ändert
docs/4-betrieb/	Server und Dienst — Deploy, Infrastruktur, Launch	bei Betriebsänderungen
archiv/	Abgeschlossenes, datiert — nachschlagbar, nicht mehr gepflegt	nie

Dazu auf oberster Ebene:

Datei	Rolle
README.md	Landkarte + Workflow. Keine Fachinhalte.
AGENTS.md	Wie in diesem Projekt gearbeitet wird — Teil A Regeln/Prinzipien, Teil B operativer Ablauf

Die drei Status-Dateien sauber trennen

Das ist die Unterscheidung, die am häufigsten verwischt — und jedes Mal Arbeit kostet:

Datei	Beantwortet	NICHT darin
ROADMAP	Was ist offen, in welcher Reihenfolge?	der Tagesstand
UEBERGABE	Wo stehe ich gerade? Neuester Block oben	keine zweite Aufgabenliste
CHANGELOG	Was ist wann passiert? Datum · Commit · was	keine Planung

Wenn die Übergabe anfängt, Aufgaben zu listen, gibt es zwei Aufgabenlisten — und eine ist immer veraltet.

Jedes Dokument trägt einen Kopf

Vier Zeilen, ganz oben, in jeder Datei:

> Zweck:           wofür dieses Dokument da ist
> Führend für:     worüber es entscheidet, wenn Dokumente sich widersprechen
> NICHT hier:      was ausdrücklich woanders steht (mit Verweis)
> Zuletzt geprüft: JJJJ-MM-TT

„NICHT hier" ist die wertvollste Zeile. Sie verhindert, dass dieselbe Sache an zwei Stellen wächst — der häufigste Weg, wie Dokumentation still falsch wird.

„Zuletzt geprüft" ist keine Formalie. Ein Wegweiser ist so viel wert wie sein Datum.

Der Workflow

A) Lesen — zu Sessionbeginn und nach jeder Übergabe

1. README.md — Landkarte + Workflow
2. AGENTS.md — die Arbeitsregeln
3. docs/1-status/UEBERGABE.md — oberster Block
4. docs/1-status/ROADMAP.md — was offen ist
5. das führende Fach-Dokument für die konkrete Aufgabe
6. git log --oneline -3 und git status --short

README und AGENTS genügen einmal je Session. Das Fach-Dokument dagegen je Aufgabe frisch.

B) Updaten — nach jeder abgeschlossenen Einheit

⚠️ Ein Doku-Update zieht IMMER alle betroffenen Dokumente mit — nie nur eins. Das ist die teuerste Lehre aus der Praxis: Eine Änderung, die nur an einer Stelle nachgezogen wird, erzeugt genau den Widerspruch, den die Struktur verhindern soll.

Mindestens:

1. CHANGELOG — Eintrag mit Datum und Commit
2. ROADMAP — Erledigtes abhaken, Neues aufnehmen
3. UEBERGABE — neuer Block oben
4. betroffene Fach-Dokumente

C) Die Regeln, die den Workflow tragen

• Ein Ort ist kanonisch. Bei verteiltem Arbeiten (lokal + Server) muss eindeutig feststehen, welche Kopie führt. Zwei Master sind schlimmer als gar keine Doku, weil beide glaubwürdig aussehen.
• Bei Widerspruch zwischen Doku und Code gilt der Code. Die Doku wird nachgezogen — nicht stillschweigend angenommen, sie habe recht.
• Ideen sind keine Beschlüsse. „Man könnte…" gehört in einen Ideenspeicher, nicht in die Roadmap als Aufgabe.

Wachsende Dokumente rotieren -- von Anfang an

Status-Dokumente wachsen unbegrenzt, wenn niemand sie schneidet. Im Praxisprojekt sind Changelog und Roadmap auf 900 KB und 750 KB angewachsen: weder les- noch durchsuchbar, und ein Assistent kann sie nicht mehr am Stueck aufnehmen. Die Uebergabedatei wird dort in datierte Archivdateien rotiert -- Changelog und Roadmap aber nicht, und genau die sind die groessten.

⭐ Auslagern heisst KUERZEN, nicht WEGNEHMEN

Beim Auslagern bleibt am Ort eine Kurzfassung: Titel, was dort passiert ist, und der Zeiger aufs Archiv. Ein blosser Verweis genuegt nicht.

schlecht   ### Bahn 13 -> siehe archiv-....md

gut        ### Bahn 13 - Baeume statt Listen  [ARCHIVIERT]
           > Baeume statt Listen in drei Bereichen, alle ueber EINE Funktion.
           > Vollstaendig im Archiv, Abschnitt bahn-13.

Warum das der eigentliche Punkt ist. Wer das Dokument von oben nach unten liest, soll weiter ERFAHREN, was passiert ist -- ohne eine zweite Datei zu oeffnen. Ein Dokument, das nach dem Kuerzen nur noch aus Verweisen besteht, ist zwar kuerzer, aber aermer: Es beantwortet die Frage nicht mehr, fuer die man es aufgeschlagen hat.

⚠️ Und es ist die Bremse gegen den einfachsten Missbrauch. Ohne diese Regel waere Loeschen der bequemste Weg, einen Abschnitt "abzuschliessen": Die Datei wird kuerzer, jede Groessenpruefung wird gruen, und niemand erfaehrt je, dass es den Abschnitt gab. Eine Probe, die die Kurzfassung verlangt, faengt genau das.

Regel: Ueber etwa 100 KB wandert der aeltere Teil nach archiv/<name>-bis-JJJJ-MM-TT.md, mit einem Zeiger darauf im aktiven Dokument. Das gilt fuer alle wachsenden Dateien, nicht nur fuer eine.

Zwei stille Fehlerquellen in Markdown

Beides bricht nicht — es rendert falsch, und niemand merkt es:

• Die Zahl der Code-Zäune muss gerade sein. Ein einzelner nicht geschlossener Zaun verschluckt den halben Rest der Datei in einem Codeblock.
• Jede Überschrift genau einmal. Doppelte Überschriften brechen Anker und Navigation.

Beides lässt sich in einem Zweizeiler prüfen und gehört in die Vor-Commit-Prüfung:

test $(( $(grep -c '^```' datei.md) % 2 )) -eq 0 || echo "ungerade Code-Zaeune"
grep '^#' datei.md | sort | uniq -d

Und: Zahlen in Verweisen veralten still

Aus der Junctar-Praxis: Ein Einstiegsdokument nannte lange „die 14 Fallen", während die Liste dahinter längst 22 enthielt. Niemand merkte es, weil ein Verweis nie rot wird.

Regel: In Verweisen keine Anzahl nennen — „die Fallen" statt „die 14 Fallen". Wenn eine Zahl unvermeidbar ist, gehört sie in dieselbe Datei wie das Gezählte.

Praxisbeispiel Junctar

Junctar nutzt genau diese Struktur: CLAUDE.md (an zwei Orten) → README.md (Dokumentenlandkarte mit Tier 0–4) → docs/1-status · 2-grundlagen · 3-features · 4-betrieb. Jedes Dokument trägt den Vier-Zeilen-Kopf, der Update-Weg ist im README.md als verbindlich festgeschrieben.

Zur Darstellung im Browser eignet sich MkDocs Material (siehe mkdocs.yml) — die Struktur oben funktioniert aber unabhängig davon, auch als reines Markdown im Repo.

Fertige Vorlage zum Kopieren

Im Playbook liegt ein vollständiger, kopierbarer Satz dieser Struktur:

vorlagen/projekt-doku/
  LIESMICH.md                     Anleitung + Platzhalter-Liste
  CLAUDE.md                       der Einstieg (an JEDEN Arbeitsort kopieren)
  README.md                       Landkarte + Workflow
  AGENTS.md                       Teil A Regeln / Teil B Ablauf
  docs/1-status/                  ROADMAP + UEBERGABE + CHANGELOG
  docs/2-grundlagen/KONZEPT.md
  docs/4-betrieb/BETRIEB.md
  scripts/doku-pruefen.sh         prüft Zäune, Überschriften, Platzhalter

Übernehmen:

cp -r vorlagen/projekt-doku/. /pfad/zum/neuen/projekt/
grep -rn '<[A-Za-z]' --include='*.md' /pfad/zum/neuen/projekt/

Alle Platzhalter stehen in spitzen Klammern, damit der zweite Befehl jeden findet, der liegengeblieben ist. Das Skript scripts/doku-pruefen.sh meldet sie ebenfalls -- und fällt selbst fehl, wenn er gar keine Datei findet, damit eine leere Prüfung nicht grün meldet.

Verwandt

Wie man prueft, dass eine Pruefung ueberhaupt etwas prueft -- die vier Fragen, die Gegenprobe und der Bauablauf -- steht in docs/setup/05-projektstart/06-qualitaet-und-proben.md.

Checkliste

• [ ] CLAUDE.md vorhanden — an jedem Ort, von dem aus gearbeitet wird
• [ ] CLAUDE.md verweist auf README.md und dupliziert keine Inhalte
• [ ] README.md enthält die vollständige Dokumentenlandkarte
• [ ] AGENTS.md trennt Regeln (Teil A) vom Ablauf (Teil B)
• [ ] docs/ mit nummerierten Bereichen angelegt
• [ ] ROADMAP · UEBERGABE · CHANGELOG existieren mit getrennten Rollen
• [ ] Jedes Dokument trägt Zweck · Führend für · NICHT hier · Zuletzt geprüft
• [ ] Der kanonische Ort ist benannt
• [ ] Update-Weg im README festgeschrieben
• [ ] Markdown-Prüfung (gerade Code-Zäune, eindeutige Überschriften) eingerichtet