claude-regelwerk/AI/Regelwerk/schreibstil.md

type, status, title, summary, tags, created, updated

type	status	title	summary	tags	created	updated
resource	reference	Schreibstil	Stichpunkte und Tabellen statt Textblöcke, Anleitung und Hintergrund als getrennte Seiten, eine Kommentarzeile je Codeabschnitt — Realität vor Stil, Referenzdokument.	regelwerk schreibstil dokumentation	2026-08-24	2026-09-29

Schreibstil

Angeordnet am 2026-08-24, umgestellt auf Pascals Anordnung am 2026-09-29: lange Anleitungen erschlagen den Leser und führen zu Frust.

Gilt für alles, was ein Mensch lesen soll:

• Technische Anleitungen, Handouts, Bookstack-Artikel, Kundendokumentation
• Codedoku unter docs/code/, Projektdokumentation
• Konzepte, Portfolio-Dokumente, Entscheidungsvorlagen
• Sitzungszusammenfassungen und Agentenprotokoll

Ausnahmen stehen unten unter „Wo der Stil nicht gilt".

Der Maßstab

• Kurz, aber vollständig. Jede Aussage, die der Leser zum Umsetzen braucht, bleibt drin. Gekürzt wird die Verpackung, nie der Inhalt.
• Stichpunkte und Tabellen statt Textblöcke. Fließtext höchstens zwei Sätze am Stück, danach Liste oder Tabelle.
• Ein Stichpunkt trägt eine ganze Aussage. Wer, was, unter welcher Bedingung. Kein Stichwort-Telegramm wie „Firewall — beachten".
• Tabellen für alles Vergleichbare: Optionen, Parameter, Rollen, Zuständigkeiten, Vorher/Nachher.
• Du sprichst zu jemandem. „Du brauchst dafür", nicht „es wird benötigt". Die Sie-Form nur, wo eine Datei sie verlangt (etwa AI/Regelwerk/seo).
• Zuerst, wofür das gut ist. Eine Zeile, dann der Weg.
• Wörtlich statt bildhaft. Sag, was du meinst; gibt es eine wörtliche Formulierung, nimm sie.
• Kein Vortragston. Keine Einleitung über die Wichtigkeit, kein Fazit, das wiederholt.

Anleitung und Hintergrund — zwei Seiten

Eine technische Anleitung besteht aus zwei Dateien nebeneinander:

	<thema>-anleitung.md	<thema>-hintergrund.md
Enthält	Zweck (eine Zeile), Link auf den Hintergrund, Voraussetzungen, nummerierte Schritte, Codeblöcke, Prüfen	Link zurück auf die Anleitung, Warum so, Architektur, Fallstricke im Detail, Alternativen, Quellen
Enthält nicht	Begründungen, Architektur, Historie, Alternativen	die Schrittfolge
Form	Liste und Code	Stichpunkte und Tabellen, kurze Absätze erlaubt

• In Bookstack: zwei Seiten im selben Kapitel, „ — Anleitung" und „ — Hintergrund".
• Der Fallstrick bleibt am Schritt, an dem man reinläuft — als eine Zeile mit ⚠. Die Erklärung dazu steht im Hintergrund.
• Kurze Anleitungen ohne nennenswerten Hintergrund brauchen keine zweite Seite. Dann fehlt der Link, und es steht nichts Erklärendes in der Anleitung.

Code in Dokumenten

• Eine Kommentarzeile über jedem Codeblock-Abschnitt, die sagt, was der Abschnitt tut.
• Keine Zeilenkommentare. Was ein Schalter bedeutet, steht im Hintergrund.
• Ein Block mit mehreren Aufgaben wird in Abschnitte geteilt, jeder mit seiner Kommentarzeile.
• Kommentarzeichen der Sprache: # für Bash, PowerShell, Python, YAML; // für JavaScript und C#; -- für SQL; REM für cmd.
• Gilt nur für Code in Dokumenten. Produktivdateien folgen AI/Regelwerk/codedoku.

Weitere Dokumentarten

Dokumentart	Form
Codedoku docs/code/	vier Fragen aus [[AI/Regelwerk/codedoku
Konzept, Portfolio, Entscheidungsvorlage	Tabellen und Stichpunkte; eine Empfehlung steht mit ihrem Grund in derselben Zeile
Sitzungsbericht, Agentenprotokoll	Stichpunkte je Thema: was erledigt, was offen, was Pascal tun muss

Die Grenze — Realität vor Stil

Die Form ändert sich, die Aussagen nicht. Vier Regeln ohne Ermessensspielraum:

1. Nichts erfinden. Keine Zahlen, Versionsnummern, Pfade oder Fehlermeldungen aus dem Gedächtnis. Konkretheit kommt aus der Quelle oder gar nicht.
2. Nichts weichzeichnen. Gilt eine Aussage nur unter einer Bedingung, bleibt die Bedingung im Stichpunkt — auch wenn er dadurch lang wird. Kürzen heißt nicht, Bedingungen zu streichen.
3. Lücken benennen, nicht überbrücken. „Unter Rocky 10 nicht geprüft" ist ein Ergebnis und bekommt einen eigenen Stichpunkt.
4. Keine Position, die das Material nicht hergibt. Eine Empfehlung braucht einen Grund, der danebensteht.

Der Grund für die Härte: Kürzen und Glätten haben dieselbe Fehlerart — Bedingungen und Vorbehalte fallen weg, weil sie sperrig sind. Vermenschlichen hat eine zweite: Es erfindet Konkretheit, damit der Text weniger nach Modell klingt. Am Ende steht jemand vor einem System, das anders reagiert als beschrieben.

Vorher / Nachher

Statt	Besser
Absatz aus fünf Sätzen über Voraussetzungen	Liste „Voraussetzungen", ein Punkt je Voraussetzung
„Im Anschluss erfolgt die Konfiguration des Dienstes."	„3. Dienst konfigurieren:" plus Codeblock
Codeblock mit Kommentar an jeder Zeile	eine Kommentarzeile je Abschnitt; Schalter im Hintergrund erklärt
„Es ist zu beachten, dass unter Umständen Probleme auftreten können."	„⚠ Auf Windows-Konsolen bricht das bei Umlauten in der Ausgabe ab (cp1252)."
„Firewall beachten"	„Port 443 eingehend muss am Perimeter offen sein, sonst schlägt die Registrierung fehl."
„Best Practice ist X."	Tabellenzeile: Option X — nehme ich, weil Y; Option Z — ginge, kostet W
„Diese Lösung bietet zahlreiche Vorteile."	Streichen. Gibt es Vorteile, je Vorteil ein Stichpunkt; sonst war der Satz leer.
„Studien zeigen, dass …"	Quelle nennen oder Behauptung streichen.
„Der Prozess ist nun abgeschlossen."	Streichen.

Das Referenzdokument

Ton per Beispiel, nicht per Beschreibung — dieselbe Regel wie bei den Dokumentations-Großprojekten. Jeder Subagent, der Dokumente schreibt, bekommt dieses Paar mit:

### Tote Links im Vault finden — Anleitung

Zeigt alle Wikilinks, die ins Leere zeigen. Warum so: [[tote-links-finden-hintergrund|Hintergrund]]

**Voraussetzungen**

- Python ist unter dem Befehl `python` erreichbar.
- Du stehst im Vault-Root.

**Schritte**

1. Linkcheck starten:

   ```bash
   # Linkcheck über den ganzen Vault, Ausgabe in UTF-8
   PYTHONIOENCODING=utf-8 python .vault-tools/linkcheck/linkcheck.py --vault .
   ```

   ⚠ `python3` startet hier den Microsoft-Store-Stub und läuft nicht.

2. Gemeldete Links in den genannten Dateien korrigieren.

**Prüfen**

- Ein zweiter Lauf meldet die korrigierten Links nicht mehr.
- Pfade in Backticks prüft der Linkcheck nicht — die siehst du von Hand durch.

### Tote Links im Vault finden — Hintergrund

- **Warum der Linkcheck:** Er lässt Codeblöcke aus. Der `vault_doctor` aus dem alten Toolkit tut das nicht und fand dort 92 tote Links, keiner davon echt — etwa `[[ $EUID -eq 0 ]]` aus einem Bash-Beispiel.
- **Warum `PYTHONIOENCODING=utf-8`:** Ohne die Variable zerlegt die Windows-Konsole die Umlaute in der Ausgabe.
- **Warum `python`:** `python3` meldet auf dieser Maschine „Python was not found".
- **Blinder Fleck:** Wer `AI/sessions/…` in Backticks statt `[[AI/sessions/…]]` schreibt, hat einen Verweis, den keine Prüfung kontrolliert.

Zur Anleitung: [[tote-links-finden-anleitung|Anleitung]]

Woran man den Stil erkennt:

• Die erste Zeile sagt, wofür das Ding gut ist.
• Die Anleitung enthält keinen einzigen Begründungssatz, nur den ⚠-Hinweis am Schritt.
• Jede Aussage des Hintergrunds ist ein Stichpunkt mit fettem Stichwort.
• Die Stelle, die das Werkzeug nicht sieht, wird benannt.

Bestehende Anleitungen umbauen

• Neue Dokumente entstehen im neuen Stil. Der Bestand bleibt, bis jemand ihn anfasst.
• Umbau auf Zuruf mit dem Skill anleitung-straffen (.claude/skills/anleitung-straffen/).
• Beim Umbau behält die bestehende Datei ihren Namen und Titel und wird die Anleitung. Grund: Wikilinks und die Bookstack-Zuordnung zeigen auf sie. Neu daneben entsteht <alter-dateiname>-hintergrund.md mit Titel „ — Hintergrund".

Verhältnis zum humanizer-Skill

• Diese Datei ist die Voreinstellung.
• Der humanizer ist der Nachbearbeitungsgang für Texte, die schon glatt geraten sind und nach Modell klingen. Er misst die Satzlängen-Varianz (scripts/rhythmus.py), kennt die deutschen KI-Marker und hat dieselbe Regel „Nichts erfinden".
• Ihn rufen, wenn ein fertiger Entwurf nach Modell klingt oder ein Kundendokument den letzten Schliff braucht — nicht als Ersatz für sauberes Schreiben.
• Der humanizer kennt diese Datei nicht. Er rät, Aufzählungen zu entkalibrieren, sparsam zu fetten und Listen mit fettem Stichwort und Doppelpunkt in Prosa aufzulösen — genau die Hintergrund-Form dieser Datei. Nach seinem Durchgang prüfst du: Listen und Tabellen sind Listen und Tabellen geblieben, die fetten Stichwörter im Hintergrund stehen noch.

Nur für Claude Fable 5.1

Schreibt Fable 5.1 den Text, kommen drei Punkte aus AI/Regelwerk/fable-5-1 dazu (Abschnitte 5, 6, 7):

• Die Prosa neigt zu langen, dichten Sätzen — hier also erst recht Liste statt Absatz.
• Im Chat greift es seltener zu Listen als frühere Modelle — bei vielgliedrigem Inhalt trotzdem Liste oder Tabelle.
• Beim Zusammenfassen übernimmt es Quellwortlaut eher unmarkiert — als Zitat kennzeichnen oder in eigenen Worten.

Andere Modelle entscheiden selbst, ob sie das übernehmen; die Regeln dieser Datei gelten für alle.

Wo der Stil nicht gilt

Dort bleibt die Form, die das Dokument verlangt:

• Regelteile von ISMS- und Compliance-Dokumenten. Eine Anforderung wird zitiert, nicht umformuliert. „Muss" und „darf nicht" bleiben. Basis- und Zusatzkriterien bleiben getrennt und gekennzeichnet.
• Prüfprotokolle, Nachweise, Abnahmedokumente — alles, was jemand später gegen uns hält. Was gemessen wurde, mit welchem Befehl, mit welchem Ergebnis.
• Kopfkommentare von Prüfskripten. Geltungsbereich und benannte Lücken — siehe AI/Regelwerk/pruefwerkzeuge.
• Rechtliche und vertragliche Texte. Präzision schlägt Kürze.

Der umgebende Text — Einleitung, Begründung, Handlungsempfehlung — steht trotzdem in diesem Stil.

Referenzen

• CLAUDE
• AI/Regelwerk/codedoku — Kommentare in Produktivdateien, Codedoku
• AI/Regelwerk/dokumentations-grossprojekte — Referenzdokument bei Fan-Out
• AI/Regelwerk/pruefwerkzeuge
• AI/Regelwerk/fable-5-1 — nur für Fable 5.1: Schreibdichte, Formatierung, Zitieren