claude-regelwerk/AI/Regelwerk/codedoku.md

---
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-09-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

- Ort: Projektordner unter `docs/code/`, eine Datei je Modul oder Skript, gleicher Name.
- Direkt unter dem Frontmatter, ohne Frontmatter in der ersten Zeile, steht ein relativer Markdown-Link aufs Projekt-README, zum Beispiel `Projekt: [README](../../README.md)`. Der Dateikopf im Code nennt die Codedoku nur als Pfad, ohne diese Zeile ist sie im Graphen eine Waise. Regel: [[AI/Regelwerk/navigation|navigation.md]], Abschnitt „Links schreiben und Dateien verschieben“.
- 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|schreibstil.md]].
- `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|schreibstil.md]], „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|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)]]