Nexhorizons-Public/claude-regelwerk
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Automatischer Push: 25 Datei(en) geändert

Browse Source 
- .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]>
This commit is contained in:
Pascal MichelandClaude Opus 5 committed 2026-09-30 04:00:02 +02:00
1 parent 8e29a16e7b
commit e8472409e9
25 files changed
+6403 -86
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AI/Regelwerk/schreibstil.md
+133 -47
View File
@@ -2,94 +2,180 @@
type: resource
status: reference
title: Schreibstil
summary: Ton und harte Grenzen für Anleitungen, Handouts, Kunden- und Codedoku — Kaffeepausen-Maßstab, Realität vor Stil, Referenzdokument.
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-05
updated: 2026-09-29
---
# Schreibstil
Angeordnet am 2026-08-24. Gilt für alles, was ein Mensch lesen soll: Anleitungen, Handouts, Kundendokumentation, Bookstack-Artikel, Projektdokumentation, Codedoku unter `docs/`, Sitzungszusammenfassungen.
Angeordnet am 2026-08-24, umgestellt auf Pascals Anordnung am 2026-09-29: lange Anleitungen erschlagen den Leser und führen zu Frust.
Nicht gemeint sind Prüfprotokolle, Regelteile von Compliance-Dokumenten und alles, was jemand später gegen mich hält — dazu unten „Wo der Ton nicht gilt".
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
Erklär es so, wie du es einem guten Freund in der Kaffeepause erklären würdest — und zwar dem, der es hinterher wirklich umsetzen muss.
- **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.
Das heißt konkret:
## Anleitung und Hintergrund — zwei Seiten
- **Du sprichst zu jemandem.** Nicht ins Leere, nicht in eine Zielgruppe. Also „du brauchst dafür" statt „es wird benötigt".
- **Die Reihenfolge folgt dem Gespräch, nicht dem Handbuch.** Zuerst wofür das gut ist, dann der Weg, dann die Fallstricke. Nicht: Definition, Architektur, Voraussetzungen, Schritt 1.
- **Der Fallstrick kommt da, wo man reinläuft.** Nicht gesammelt in einem Kapitel „Bekannte Probleme" am Ende.
- **Ganze Sätze.** Ein Stichpunkt ist keine Erklärung, sondern die Erinnerung an eine, die mal jemand hatte.
- **Kein Vortragston.** Keine Einleitung darüber, wie wichtig das Thema ist. Kein Fazit, das wiederholt, was oben stand.
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
Der Ton ändert sich, die Aussagen nicht. Vier Regeln, die keinen Ermessensspielraum haben:
Die Form ändert sich, die Aussagen nicht. Vier Regeln ohne Ermessensspielraum:
1. **Nichts erfinden.** Keine Zahlen, keine Versionsnummern, keine Pfade, keine Fehlermeldungen aus dem Gedächtnis. Konkretheit kommt aus der Quelle oder gar nicht.
2. **Nichts weichzeichnen.** Wenn eine Aussage nur unter einer Bedingung stimmt, bleibt die Bedingung im Satz. Auch wenn er dadurch sperrig wird. Ein sperriger Satz, der stimmt, schlägt einen schönen, der beim Kunden bricht.
3. **Lücken benennen, nicht überbrücken.** „Ob das unter Rocky 10 genauso läuft, habe ich nicht geprüft" ist ein Ergebnis. Ein glatter Satz, der die Frage offen lässt, ohne es zu sagen, ist eine Falle.
4. **Keine Position, die das Material nicht hergibt.** Eine Empfehlung braucht einen Grund, der im Text steht. Sonst ist es Geschmack im Gewand einer Aussage.
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: Vermenschlichen hat genau eine bekannte Fehlerart — es erfindet Konkretheit, damit der Text weniger nach Modell klingt. Bei einem Blogpost ist das peinlich. Bei einer Kundendokumentation steht am Ende jemand vor einem System, das anders reagiert als beschrieben.
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 |
|---|---|
| „Im Anschluss erfolgt die Konfiguration des Dienstes." | „Danach konfigurierst du den Dienst." |
| „Es ist zu beachten, dass unter Umständen Probleme auftreten können." | „Auf Windows-Konsolen bricht das ab, wenn ein Umlaut in der Ausgabe steht — cp1252." |
| „Diese Lösung bietet zahlreiche Vorteile." | Streichen. Wenn es Vorteile gibt, benenne sie; wenn nicht, war der Satz leer. |
| „Best Practice ist die Verwendung von X." | „Ich nehme X, weil Y. Z ginge auch, kostet aber W." |
| 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. Der Leser merkt, wenn die Anleitung aufhört. |
| „Der Prozess ist nun abgeschlossen." | Streichen. |
## Das Referenzdokument
Ton per Beispiel, nicht per Beschreibung — dieselbe Regel wie bei den Dokumentations-Großprojekten. Wenn ein Set von Dokumenten entsteht, bekommt jeder Subagent ein fertiges Referenzdokument mit. Das hier ist die Vorlage, an der sich alles ausrichtet:
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
>
> Der Linkcheck zeigt dir, welche Wikilinks ins Leere zeigen. Er lässt Codeblöcke aus. Deshalb meldet er ein `[[ $EUID -eq 0 ]]` aus einem Bash-Beispiel nicht als toten Link. Der `vault_doctor` aus dem alten Toolkit tut genau das: Er fand dort 92 Leichen, und keine davon war echt.
>
> ```bash
> PYTHONIOENCODING=utf-8 python .vault-tools/linkcheck/linkcheck.py --vault .
> ```
>
> Das `python` ist kein Tippfehler. `python3` startet auf dieser Maschine den Microsoft-Store-Stub und meldet „Python was not found", statt zu laufen. Ohne `PYTHONIOENCODING` zerlegt die Windows-Konsole außerdem die Umlaute in der Ausgabe.
>
> Was der Linkcheck nicht sieht, sind Pfade in Backticks. Wer in einer Tagesnotiz `AI/sessions/…` statt `[[AI/sessions/…]]` schreibt, hat einen Verweis, den keine Prüfung kontrolliert.
````markdown
### Tote Links im Vault finden — Anleitung
Woran man den Ton erkennt: Der erste Satz sagt, wofür das Ding gut ist. Der Fallstrick steht direkt am Befehl, nicht in einem Kapitel weiter unten. Und die Stelle, die das Werkzeug nicht sieht, wird benannt statt umschifft.
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** — so wird geschrieben, ohne dass jemand danach fragt.
Der `humanizer`-Skill ist der **Nachbearbeitungsgang** für Texte, die schon glatt geraten sind: er misst Satzlängen-Varianz objektiv (`scripts/rhythmus.py`), kennt die deutschen KI-Marker und hat dieselbe harte 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 von Anfang an.
- 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 modellspezifische Punkte aus [[AI/Regelwerk/fable-5-1|fable-5-1.md]] dazu (Abschnitte 5, 6, 7): Die Prosa neigt zu langen, dichten Sätzen ohne Absatzbrüche — also Absätze brechen und die wörtliche Formulierung der bildhaften vorziehen. Im Chat greift es seltener zu Listen und Fettdruck als frühere Modelle — bei vielgliedrigem Inhalt trotzdem eine Liste nehmen. Und beim Zusammenfassen übernimmt es Quellwortlaut eher unmarkiert — entweder als Zitat kennzeichnen oder in eigenen Worten wiedergeben. Andere Modelle entscheiden selbst, ob sie das übernehmen; die Regeln dieser Datei gelten für alle.
Schreibt Fable 5.1 den Text, kommen drei Punkte aus [[AI/Regelwerk/fable-5-1|fable-5-1.md]] dazu (Abschnitte 5, 6, 7):
## Wo der Ton nicht gilt
- 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.
Gleichförmigkeit ist dort ein Feature, nicht ein Fehler:
Andere Modelle entscheiden selbst, ob sie das übernehmen; die Regeln dieser Datei gelten für alle.
- **Regelteile von ISMS- und Compliance-Dokumenten.** Eine Anforderung wird zitiert, nicht erzählt. Basis- und Zusatzkriterien bleiben getrennt und gekennzeichnet.
- **Prüfprotokolle, Nachweise, Abnahmedokumente.** Dort steht, was gemessen wurde, mit welchem Befehl, mit welchem Ergebnis.
- **Kopfkommentare von Prüfskripten.** Geltungsbereich und benannte Lücken, so nüchtern wie möglich — siehe [[AI/Regelwerk/pruefwerkzeuge|pruefwerkzeuge.md]].
- **Rechtliche und vertragliche Texte.** Präzision schlägt Lesbarkeit.
## Wo der Stil nicht gilt
In allen vier Fällen darf der **umgebende** Text trotzdem in diesem Ton stehen — Einleitung, Begründung, Handlungsempfehlung. Nur der Kern bleibt formal.
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/codeworkflow|Codeworkflow]] — Abschnitt „Produktivdateien und Codedoku"
- [[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