# 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/APxx-*.md` - **Abschlussberichte** pro Arbeitspaket gehören nach `docs/arbeitspakete/m/berichte/APxx-bericht.md` - **Berichtsvorlage** ist `docs/arbeitspakete/m/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/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.