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.