asv-format-validator/CLAUDE.md

# CLAUDE.md

Projektweite Instruktionen für Claude Code. Diese Datei wird automatisch gelesen und gilt für jeden Lauf in diesem Repository.

## Projektkontext

**Projekt:** ASV-Format-Validator
**Sprache:** Java 21 (Jakarta/Java SE, **kein Spring, kein Quarkus, kein DI-Framework**)
**Build:** Maven
**Zielplattform:** Windows, lokale CLI, eine Eingabedatei pro Lauf
**Spezifikation:** Technische Anlage ASV 1.09, Stand 09.10.2025
**Domäne:** Validierung von ASV-Abrechnungsdateien (EDIFACT, KKS, PKCS#7) gegen eine normative Spezifikation der GKV

## Normative Dokumente (Rangfolge bei Konflikten)

1. **`Spec.docx`** — Technische Anlage ASV 1.09 ist die **fachlich-technische Wahrheit**. Bei jedem Konflikt entscheidet die Spec. (Liegt außerhalb des Repos beim Projektinhaber.)
2. **`docs/specs/fachliche-anforderungen.md`** v4 — verbindlicher fachlicher Soll-Rahmen, feldgenauer Regelkatalog, Fehlercodes
3. **`docs/specs/technik-und-architektur.md`** v5 — verbindlicher technischer Soll-Rahmen, Architektur, Paketstruktur, Qualitätsgates
4. **`docs/specs/meilensteine.md`** v3 — **nachrangig**, strukturiert nur die Umsetzung

Die Grunddokumente (1–3) sind bei jeder Arbeit mitzudenken. Die Meilensteindatei ersetzt sie nicht.

## Arbeitsweise in diesem Repo

Die Implementierung folgt einem Meilenstein-/Arbeitspaket-Modell:

- **Meilensteine** sind in `docs/specs/meilensteine.md` definiert (M1 bis M9)
- **Arbeitspakete pro Meilenstein** liegen in `docs/arbeitspakete/m<n>/APxx-*.md`
- **Abschlussberichte** pro Arbeitspaket gehören nach `docs/arbeitspakete/m<n>/berichte/APxx-bericht.md`
- **Berichtsvorlage** ist `docs/arbeitspakete/m<n>/templates/ap-bericht.md`

**Ein Claude-Code-Lauf bearbeitet genau ein Arbeitspaket.** Nicht mehr, nicht weniger.

## Harte Regeln für jeden Lauf

1. **Scope-Treue:** Was im Arbeitspaket unter „Scope OUT" steht, wird **nicht** angefasst. Auch nicht nebenbei, auch nicht „schnell aufgeräumt". Wenn du etwas Merkwürdiges außerhalb des Scopes siehst, dokumentiere es unter „Rest-Risiken" im Abschlussbericht.
2. **Keine stillen Annahmen:** Wo die Spec etwas nicht festlegt, wird nichts stillschweigend ergänzt. Unsicherheiten werden explizit benannt.
3. **Kein `git commit`, kein `git push`, kein `git add`** — der Mensch committet am Ende selbst nach Sichtung.
4. **Kein Schreiben außerhalb des Auftragsbereichs.** Wenn das Arbeitspaket sagt „keine Code-Änderungen", dann wird **keine** `.java`-Datei angefasst.
5. **Grünes Zwischenziel:** Jeder Arbeitspaket-Lauf endet mit einem grünen `mvn clean verify` — es sei denn, das Arbeitspaket sagt ausdrücklich etwas anderes.
6. **Abschlussbericht ist Pflicht:** Am Ende jedes Arbeitspaket-Laufs entsteht der Bericht nach Vorlage in `docs/arbeitspakete/m<n>/berichte/APxx-bericht.md`. Reviewer-Checkliste am Ende ausfüllen.

## Architekturprinzipien (aus technik-und-architektur.md)

- **Hexagonale Architektur** innerhalb des bestehenden Maven-Projekts
- **Manuelle Constructor Injection**, kein DI-Framework
- **Strikte Trennung** Domain/Application von Adaptern/Infrastruktur
- **SLF4J als Logging-Fassade, Log4j2 als Bindung**, Log4j2-Typen sichtbar **nur** in `adapter.out.logging` und `bootstrap`
- **Befundmodell unterscheidet Spec-Urteil und diagnostische Weiteranalyse** — Diagnose verändert das Spec-Urteil nie
- **Exit-Codes:** `0` = gültig, `1` = ungültig, `2` = Bedienfehler. **Nicht** `0/1/2/3`.
- **Eingabe-Encoding:** ISO 8859-15. Niemals UTF-8 oder Plattform-Default für Eingabedateien.
- **Ausgabe (Berichtdatei `.txt`, Log-Datei `.log`):** UTF-8
- **Paketstruktur** wie in `technik-und-architektur.md` unter „Gewünschte Paketstruktur" beschrieben

## Code-Konventionen

- **Klassennamen, Methoden, Variablen:** Englisch
- **JavaDoc:** Deutsch
- **Benutzer-sichtbare Texte (Bericht, Logausgabe, Fehlermeldungen):** Deutsch
- **Unveränderliche Datenträger:** bevorzugt als Java Records, sofern fachlich-technisch passend
- **Wertobjekte mit Validierung:** reguläre Klassen
- **Tests:** JUnit 5, Mockito. Tests liegen spiegelbildlich zur Produktionsklasse.

## V1-Kategorien (für Regel-Implementierung ab M3)

- **V1-V** = verbindlich in V1 zu prüfen
- **V1-T** = in V1 nur teilweise/lokal prüfbar (strukturell/formal ja, inhaltlich gegen Bestände nein)
- **V1-N** = fachlich existent, in V1 bewusst nicht belastbar prüfbar (keine aktiven Pflichtprüfungen umsetzen!)
- **V1-K** = konventionsbasiert aus angrenzenden Standards

**Wichtig:** V1-N-Regeln dürfen **nie** als harte Pflichtprüfung umgesetzt werden, auch wenn sie fachlich existieren.

## Was explizit NICHT zum Scope von Version 1 gehört

- GUI (JavaFX-Anbindung wird in V2 erwogen)
- Batch-/Verzeichnisverarbeitung
- Server-/Containerbetrieb, Web-UI
- Mehrversionssupport der ASV-Spezifikation
- Referenzdatenbestände (ICD, OPS, IK, BSNR, LANR, Teamnummer, Stammdaten)
- Stufe-4-Prüfungen
- Automatische Korrektur/Rewrite von Eingabedateien
- PDF-Bericht
- JSON-Ausgabe

## Tools und Befehle

- **Build:** `mvn clean verify`
- **Nur Compile:** `mvn clean compile`
- **JAR bauen:** `mvn clean package`
- **Mutation-Tests:** `mvn -P mutation test` (Profil, ab AP02 verfügbar)
- **Tests einzeln:** `mvn test -Dtest=ClassName`

## Wenn du unsicher bist

- **Lies die drei Grunddokumente.** Wahrscheinlich steht die Antwort dort.
- **Halte dich ans Arbeitspaket.** Wenn das Arbeitspaket eine Sache nicht erlaubt oder nicht erwähnt, mache sie nicht.
- **Dokumentiere die Unsicherheit.** Lieber im Abschlussbericht „hier war ich unsicher, Entscheidung X, weil Y" als eine stille, unsichtbare Annahme.
- **Frag nicht nach Bestätigung für Offensichtliches.** Wenn das Arbeitspaket sagt „lies Datei X", dann lies sie, ohne vorher zu fragen.