Regelwerk, Agenten, Skills und Werkzeuge veröffentlichen

Erster Stand des öffentlichen Ausschnitts aus dem Vault. Die .gitignore
arbeitet als Positivliste: ausgeschlossen ist alles, eingeschlossen nur,
was ausdrücklich wieder aufgenommen wird. Notizen, Projekte, Finanzen,
das Sitzungsgedächtnis und settings.local.json bleiben damit außen vor.

Der Kundenname in AI/Regelwerk/seo.md ist durch eine neutrale
Bezeichnung ersetzt; die Regeln selbst sind unverändert.

Co-Authored-By: Claude Opus 5 <[email protected]>

AI/Regelwerk/codedoku.md

@@ -0,0 +1,97 @@
+---
+type: resource
+status: reference
+title: Codedoku und Dateikopf
+summary: Wie Produktivdateien aussehen — Dateikopf mit genau drei Angaben, CHANGELOG statt Versionsnummern in der Datei, was aus dem Code verschwindet, was drinbleibt, und wohin die Codedoku gehört.
+tags: [regelwerk, codeworkflow, code-projekte, dokumentation]
+created: 2026-08-30
+updated: 2026-08-30
+---
+
+# Codedoku und Dateikopf
+
+Ausgelagert aus [[AI/Regelwerk/codeworkflow|codeworkflow.md]] am 2026-08-30. Laden, wenn Produktivdateien angelegt oder angefasst werden — nicht beim Debuggen und nicht beim Planen.
+
+Angeordnet am 2026-08-24. Gilt für **neue und angefasste** Dateien — kein Umbau des Bestands auf Vorrat. Wer eine Datei ohnehin ändert, zieht sie beim Verlassen auf dieses Format nach.
+
+Der Zweck: eine Produktivdatei besteht aus Code und aus sonst fast nichts. Was ein Mensch zum Verstehen braucht, gehört in die Codedoku — was er zum **Nicht-Kaputtmachen** braucht, bleibt im Code. Die Trennlinie steht unten.
+
+## Der Dateikopf
+
+Genau drei Angaben, mehr nicht:
+
+```python
+"""Ein Satz, was diese Datei tut.
+
+Ersteller: Pascal Michel
+Erstellt:  2026-08-24
+Doku:      docs/code/<modul>.md · Version und Änderungen: CHANGELOG.md
+"""
+```
+
+```powershell
+<#
+  Ein Satz, was dieses Skript tut.
+  Ersteller: Pascal Michel
+  Erstellt:  2026-08-24
+  Doku:      docs/code/<skript>.md · Version und Änderungen: CHANGELOG.md
+#>
+```
+
+```bash
+#!/usr/bin/env bash
+# Ein Satz, was dieses Skript tut.
+# Ersteller: Pascal Michel   Erstellt: 2026-08-24
+# Doku: docs/code/<skript>.md · Version und Änderungen: CHANGELOG.md
+```
+
+**Ersteller ist immer der Eigentümer des Vaults, nie der Agent.** Wer getippt hat, steht in git; wer verantwortet, steht im Kopf.
+
+**Versionsnummer, Versionsdatum und Versionslog stehen nicht in der Datei.** Sie leben einmal je Projekt in `CHANGELOG.md`, oberster Eintrag ist der aktuelle Stand:
+
+```markdown
+## 1.3.0 — 2026-08-24
+- Was sich geändert hat, ein Satz je Punkt.
+```
+
+Bewusst **nur** `CHANGELOG.md`, keine zusätzliche `VERSION`-Datei: zwei Orte für dieselbe Zahl sind zwei Orte, an denen sie auseinanderlaufen kann. Und je Datei von Hand gepflegte Zahlen fallen unter dieselbe Regel wie die Erwartungstexte weiter oben — sie werden nachgezogen und dabei falsch. Am 2026-08-23 zweimal in einer einzigen Sitzung passiert.
+
+## Was aus dem Code verschwindet
+
+- **Auskommentierter Code.** Ausnahmslos. git hat die Historie.
+- **Kommentare, die den Code nacherzählen.** `# Schleife über alle Dateien` über einer Schleife über alle Dateien.
+- **Abschnittsbanner und Trennlinien aus `=` oder `-`.** Wenn eine Datei Gliederung braucht, um lesbar zu sein, braucht sie eher eine zweite Datei.
+- **Mehrzeilige Ablaufbeschreibungen im Kopf** („1) liest … 2) erzeugt … 3) packt …"). Das ist der Einstieg der Codedoku, nicht des Skripts.
+- **Historie im Code** („früher lief das über X, seit Y nicht mehr").
+
+## Was im Code bleibt
+
+Die Trennlinie ist eine einzige Frage: **Würde jemand ohne diesen Kommentar die Zeile löschen oder falsch vereinfachen?**
+
+Wenn ja, bleibt er — kurz, eine Zeile, direkt an der Stelle. Das trifft vor allem:
+
+- Umgehungen fremder Macken, die ohne Erklärung wie Ballast aussehen. Beispiel aus `Build-IntunePackage.ps1`: der Fallback für `$PSScriptRoot`, das leer ist, wenn das Skript nicht per `-File` gestartet wird. Ohne den Hinweis fliegt der Fallback beim nächsten Aufräumen raus — und das Skript bricht genau dort, wo es niemand testet.
+- Bewusste Abweichungen von der naheliegenden Lösung, samt Grund.
+- Wertebereiche und Einheiten, die man der Variablen nicht ansieht.
+- Sicherheitsrelevante Reihenfolgen („erst Rechte setzen, dann Inhalt schreiben").
+
+Faustregel: **was** und **wie** gehören in die Doku, **warum ausgerechnet so** bleibt im Code.
+
+## Die Codedoku
+
+Liegt im Projektordner unter `docs/code/`, eine Datei je Modul oder Skript, gleicher Name. Sie beantwortet vier Dinge: wofür das Ding da ist, wie der Ablauf von oben nach unten läuft, welche Annahmen es über seine Umgebung macht, und was beim Anfassen weh tut. Ton und Grenzen: [[AI/Regelwerk/schreibstil|schreibstil.md]].
+
+`docs/plans/` bleibt wie gehabt für Umsetzungspläne. `books/` bleibt für Betriebs- und Kundendokumentation — die Codedoku ist für den, der den Code ändert, nicht für den, der ihn benutzt.
+
+## Ausnahme: Prüfskripte
+
+Alles, was **beurteilt** statt tut, behält seinen Kopfkommentar in voller Länge — Geltungsbereich, Fundstellen der abgeschriebenen Listen, benannte Lücken, und der Satz, dass es ein Fangnetz ist und kein Nachweis. So verlangt es [[AI/Regelwerk/pruefwerkzeuge|pruefwerkzeuge.md]] in den Abschnitten 1, 2 und 7.
+
+Der Grund für die Ausnahme: Wer ein Prüfskript aufruft und einen grünen Exit-Code bekommt, liest keine separate Doku. Der Vorbehalt muss dort stehen, wo der Irrtum entsteht.
+
+## Referenzen
+
+- [[AI/Regelwerk/codeworkflow|↑ Codeworkflow (Standardschleife)]]
+- [[AI/Regelwerk/schreibstil|schreibstil.md]] — Ton und Grenzen der Codedoku
+- [[AI/Regelwerk/pruefwerkzeuge|pruefwerkzeuge.md]] — Kopfkommentar von Prüfskripten
+- [[CLAUDE|↑ Claude.md (Stamm)]]