Pascal MichelandClaude Opus 5
60dee0ab68
- .claude/agents/executer.md - .claude/agents/recherche.md - .claude/skills/anleitung-straffen/SKILL.md - .vault-tools/linkcheck/docs/plans/2026-09-29-waisen/00-uebersicht.md - .vault-tools/linkcheck/docs/plans/2026-09-29-waisen/task-01-zaehler.md - .vault-tools/linkcheck/docs/plans/2026-09-29-waisen/task-02-sitzungsstart.md - .vault-tools/linkcheck/docs/plans/2026-09-29-waisen/task-03-regeltexte.md - .vault-tools/linkcheck/docs/plans/2026-09-29-waisen/task-04-bestandsskript.md - .vault-tools/linkcheck/docs/plans/2026-09-29-waisen/task-05-bestandslauf.md - .vault-tools/workflow-pruefung/docs/plans/2026-09-29-quorum/00-uebersicht.md - .vault-tools/workflow-pruefung/docs/plans/2026-09-29-quorum/task-01-quorum-werkzeug.md - .vault-tools/workflow-pruefung/docs/plans/2026-09-29-quorum/task-02-quorum-workflow.md - … und 13 weitere Erzeugt vom PostToolUse-Hook .vault-tools/auto-push/auto_push.py. Co-Authored-By: Claude Opus 5 <[email protected]>
182 lines
10 KiB
Markdown
182 lines
10 KiB
Markdown
---
|
|
type: resource
|
|
status: reference
|
|
title: Schreibstil
|
|
summary: "Stichpunkte und Tabellen statt Textblöcke, Anleitung und Hintergrund als getrennte Seiten, eine Kommentarzeile je Codeabschnitt — Realität vor Stil, Referenzdokument."
|
|
tags: [regelwerk, schreibstil, dokumentation]
|
|
created: 2026-08-24
|
|
updated: 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|seo.md]]).
|
|
- **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, „<Thema> — Anleitung" und „<Thema> — 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|codedoku.md]].
|
|
|
|
## Weitere Dokumentarten
|
|
|
|
| Dokumentart | Form |
|
|
|---|---|
|
|
| Codedoku `docs/code/` | vier Fragen aus [[AI/Regelwerk/codedoku|codedoku.md]] als Überschriften, darunter Stichpunkte; Ablauf als nummerierte Liste |
|
|
| 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:
|
|
|
|
````markdown
|
|
### 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.
|
|
````
|
|
|
|
````markdown
|
|
### 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 „<alter 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|fable-5-1.md]] 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|pruefwerkzeuge.md]].
|
|
- **Rechtliche und vertragliche Texte.** Präzision schlägt Kürze.
|
|
|
|
Der **umgebende** Text — Einleitung, Begründung, Handlungsempfehlung — steht trotzdem in diesem Stil.
|
|
|
|
## Referenzen
|
|
|
|
- [[CLAUDE|↑ Claude.md (Stamm)]]
|
|
- [[AI/Regelwerk/codedoku|codedoku.md]] — Kommentare in Produktivdateien, Codedoku
|
|
- [[AI/Regelwerk/dokumentations-grossprojekte|dokumentations-grossprojekte.md]] — Referenzdokument bei Fan-Out
|
|
- [[AI/Regelwerk/pruefwerkzeuge|Prüfwerkzeuge]]
|
|
- [[AI/Regelwerk/fable-5-1|fable-5-1.md]] — nur für Fable 5.1: Schreibdichte, Formatierung, Zitieren
|