claude-regelwerk/AI/Regelwerk/codedoku.md

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

type	status	title	summary	tags	created	updated
resource	pending-review	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-09-29

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

• Ort: Projektordner unter docs/code/, eine Datei je Modul oder Skript, gleicher Name.
• Vier Überschriften, darunter Stichpunkte, keine Textblöcke:
  • Wofür — eine Zeile
  • Ablauf — nummerierte Liste von oben nach unten
  • Annahmen über die Umgebung
  • Was beim Anfassen weh tut
• Form und Grenzen: AI/Regelwerk/schreibstil.
• docs/plans/ bleibt für Umsetzungspläne, books/ für Betriebs- und Kundendokumentation. Die Codedoku ist für den, der den Code ändert, nicht für den, der ihn benutzt.

Code in Dokumenten ist etwas anderes als Produktivcode. Codeblöcke in Anleitungen und Codedoku bekommen eine Kommentarzeile je Abschnitt, was er tut (AI/Regelwerk/schreibstil, „Code in Dokumenten"). Die Regeln oben über Kommentare, die Code nacherzählen, gelten nur für Produktivdateien. Ein wörtlicher Auszug aus einer Produktivdatei bleibt mit seinen Kommentaren stehen; die erste Zeile kennzeichnet ihn als Auszug (# Auszug aus <datei>).

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