CLAUDE.md

Zweck

Dieses Repository implementiert einen lokal gestarteten PDF-Umbenenner mit KI. Das Programm liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem Quellordner, ermittelt daraus einen normierten Dateinamen und legt eine Kopie der Datei im Zielordner ab. Die Quelldatei bleibt unverändert.

Autoritative Dokumente

Nutze ausschließlich die im Repository abgelegten Dokumente als verbindliche Grundlage:

docs/specs/technik-und-architektur.md
docs/specs/fachliche-anforderungen.md
docs/specs/meilensteine.md
das jeweils aktive Arbeitspaket-Dokument unter docs/workpackages/, z. B. docs/workpackages/M1 - Arbeitspakete.md, docs/workpackages/M2 - Arbeitspakete.md

Diese Dateien müssen im Repository tatsächlich vorhanden sein. Vor Implementierungsentscheidungen sind die für das aktuelle Arbeitspaket relevanten Dokumente gezielt zu lesen. Nicht raten, wenn Dokumente fehlen, unklar sind oder sich widersprechen.

Priorisierung der Regeln

Die Dokumente haben folgende feste Bedeutung:

docs/specs/technik-und-architektur.md = verbindliche technische Zielarchitektur
docs/specs/fachliche-anforderungen.md = verbindliche fachliche Regeln
docs/specs/meilensteine.md = zulässiger Funktionsumfang pro Meilenstein
docs/workpackages/... = verbindlicher Scope, Reihenfolge und Inhalt des aktuell bearbeiteten Arbeitspakets

Bei Konflikten gilt folgende Priorität:

Technik- und Architektur-Dokument
Verbindliche technische Zielarchitektur. Architekturbrüche sind unzulässig.
Fachliche Anforderungen
Verbindliche fachliche Regeln und fachliches Zielverhalten.
Meilensteine
Begrenzen den zulässigen Funktionsumfang auf den aktuellen Entwicklungsstand.
Arbeitspakete
Definieren den konkret erlaubten Umsetzungsumfang des aktuellen Schritts.

Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und keine stillen Annahmen treffen.

Unverrückbare Technikvorgaben

Java 21
Maven Multi-Module
ausführbares Standalone-JAR
Start über Windows Task Scheduler
kein Webserver
kein Applikationsserver
keine Dauerlauf-Anwendung
kein interner Scheduler
Log4j2 für Logging
SQLite als lokaler Persistenzspeicher
OpenAI-kompatible HTTP-Schnittstelle für KI-Zugriff
API-Provider, Base-URL und Modellname sind Konfiguration, keine Architekturentscheidung

Verbindliche Modulstruktur

pdf-umbenenner-domain
pdf-umbenenner-application
pdf-umbenenner-adapter-in-cli
pdf-umbenenner-adapter-out
pdf-umbenenner-bootstrap

Architekturregeln

Strikte hexagonale Architektur / Ports and Adapters
Abhängigkeiten zeigen immer nach innen
Domain kennt keine Infrastruktur, keine Datenbank, kein Dateisystem und keine HTTP-Kommunikation
Application orchestriert Use Cases und enthält keine technischen Implementierungsdetails
Externe Zugriffe erfolgen ausschließlich über Ports
Konkrete technische Implementierungen sind Adapter
Adapter dürfen nicht direkt voneinander abhängen
Keine Vermischung von Dateisystem, PDF-Auslese, SQLite, KI-HTTP, Konfiguration, Logging, Benennungslogik und Retry-Entscheidungen
Logging ist technische Infrastruktur, kein fachlicher Port

Globale fachliche Leitplanken

Zielformat: YYYY-MM-DD - Titel.pdf
Bei Namenskollisionen: YYYY-MM-DD - Titel(1).pdf, YYYY-MM-DD - Titel(2).pdf, ...
Die 20 Zeichen gelten nur für den Basistitel; das Dubletten-Suffix zählt nicht mit
Titel sind deutsch, verständlich, eindeutig und enthalten keine Sonderzeichen außer Leerzeichen
Eigennamen bleiben unverändert
Datumsermittlung mit Priorität aus den fachlichen Anforderungen; wenn kein belastbares Datum eindeutig ableitbar ist, ist das aktuelle Datum als Fallback erlaubt
Mehrdeutige Dokumente liefern kein unsicheres Ergebnis, sondern einen Fehler
Erfolgreich verarbeitete Dateien werden nicht erneut verarbeitet
Retryable fehlgeschlagene Dateien dürfen in späteren Läufen erneut verarbeitet werden
Final fehlgeschlagene Dateien werden in späteren Läufen übersprungen
Identifikation erfolgt nicht über Dateinamen
Quelldateien werden nie überschrieben, verändert, verschoben oder gelöscht

Arbeitsweise

Arbeite immer nur im explizit aktiven Meilenstein und im explizit aktiven Arbeitspaket
Kein Vorgriff auf spätere Meilensteine oder Arbeitspakete
Änderungen klein, fokussiert und architekturtreu halten
Keine unnötigen Umbenennungen, keine großflächigen Refactorings ohne Not
Vor Änderungen zuerst die betroffenen Dateien und Abhängigkeiten verstehen
Keine Vermutungen: Bei echter Unklarheit oder Dokumentkonflikten knapp nachfragen oder den Konflikt benennen

Definition of Done pro Arbeitspaket

Ein Arbeitspaket ist erst fertig, wenn:

der Zielumfang des aktuellen Arbeitspakets vollständig umgesetzt ist
der Stand konsistent, fehlerfrei und buildbar ist
Implementierung, Konfiguration, JavaDoc und Tests ergänzt sind, soweit für den Stand sinnvoll
keine Inhalte späterer Meilensteine vorweggenommen wurden
der Zwischenstand in sich geschlossen und übergabefähig ist

Qualitäts- und Prüfreihenfolge

Nur den für das aktuelle Arbeitspaket nötigen Scope ändern
Nach Änderungen den kleinsten sinnvollen Build-/Test-Umfang ausführen
Vor Abschluss sicherstellen, dass der relevante Maven-Reactor-Stand fehlerfrei ist
Fehler nicht kaschieren; Ursachen sauber beheben oder offen benennen

Wichtige Betriebsregeln

Ungültige Startkonfiguration verhindert den Verarbeitungslauf und führt zu Exit-Code 1
Run-Lock verhindert parallele Instanzen; wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort
Exit-Code 0: Lauf technisch ordnungsgemäß ausgeführt, auch wenn einzelne Dateien fachlich oder transient fehlgeschlagen sind
Exit-Code 1: harter Start-/Bootstrap-Fehler
Umgebungsvariable hat Vorrang vor Properties beim API-Key

Nicht-Ziele / Verbote

kein Web-UI
keine REST-API zur Bedienung
keine OCR innerhalb der Java-Anwendung
keine DMS-Funktionalität
kein menschlicher Review-Workflow in der Anwendung
keine interne Scheduler-Logik
keine Architekturbrüche
keine neuen Bibliotheken oder Frameworks ohne klare Notwendigkeit und Begründung
keine stillen Änderungen an Provider-Bindung oder Architekturprinzipien

6.3 KiB Raw Blame History