claude-regelwerk/AI/Regelwerk/codedoku.md

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

type	status	title	summary	tags	created	updated
resource	reference	Codedoku und Dateikopf	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.	regelwerk codeworkflow code-projekte dokumentation	2026-08-30	2026-08-30

Codedoku und Dateikopf

Ausgelagert aus AI/Regelwerk/codeworkflow 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:

"""Ein Satz, was diese Datei tut.

Ersteller: Pascal Michel
Erstellt:  2026-08-24
Doku:      docs/code/<modul>.md · Version und Änderungen: CHANGELOG.md
"""

<#
  Ein Satz, was dieses Skript tut.
  Ersteller: Pascal Michel
  Erstellt:  2026-08-24
  Doku:      docs/code/<skript>.md · Version und Änderungen: CHANGELOG.md
#>

#!/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:

## 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.

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 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
• AI/Regelwerk/schreibstil — Ton und Grenzen der Codedoku
• AI/Regelwerk/pruefwerkzeuge — Kopfkommentar von Prüfskripten
• CLAUDE