# Arbeitspakete – Erweiterung um native Anthropic Claude-Anbindung ## Geltungsbereich Dieses Dokument beschreibt ausschließlich die Arbeitspakete für die Erweiterung **„Zusätzliche KI-Provider-Familie Anthropic Claude über die native Messages API"**. Der Basisstand des Projekts ist vollständig umgesetzt, dokumentiert, getestet und freigegeben. Diese Erweiterung ist eine **bewusst minimale Ergänzung** dieses Basisstands. Das einzige Ziel dieser Erweiterung ist: - den bestehenden, OpenAI-kompatiblen KI-Weg unverändert nutzbar zu halten, - zusätzlich die **native Anthropic Messages API** als zweiten, gleichwertig unterstützten KI-Provider anzubinden, - und zwischen beiden Providern über die Konfiguration genau **einen aktiven Provider** auszuwählen. Die Arbeitspakete sind so geschnitten, dass: - **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann, - **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann, - nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt. Die Reihenfolge der Arbeitspakete ist verbindlich. ## Schnittregeln für die KI-Bearbeitung - Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Konfiguration, Dokumentation und Tests ändern. - Keine Annahmen treffen, die nicht durch die verbindlichen Spezifikationen, dieses Dokument oder den tatsächlich vorliegenden Code gedeckt sind. - Änderungen strikt nach dem Prinzip: **so wenig wie möglich, so viel wie nötig**. - Keine allgemeine Provider-Plattform und keine Abstraktion für hypothetische weitere Provider. - Kein Umbau des bestehenden fachlichen Ablaufs ohne direkten Bezug zur Provider-Erweiterung. - Das bestehende fachliche Verhalten des Basisstands bleibt unverändert, soweit dieses Dokument nichts anderes ausdrücklich erweitert. - Jeder positive Zwischenstand muss bereits **vollständig buildbar, testbar und dokumentiert** sein. - Zu jedem Arbeitspaket gehören die unmittelbar betroffenen: - Implementierungen, - Tests (inkl. ggf. Mutationstests in den unmittelbar betroffenen Modulen), - JavaDoc / `package-info`, - Konfigurationsbeispiele, - sowie sonstige Repository-Dokumente mit direktem Bezug. ## Explizit nicht Bestandteil dieser Erweiterung - Provider-Familien jenseits der zwei explizit unterstützten (OpenAI-kompatibel, Anthropic Messages API) - mehrere Konfigurationen je Provider-Familie (Profilverwaltung) - automatische Fallback-Umschaltung zwischen Providern - parallele Nutzung mehrerer Provider in einem Lauf - Änderung des fachlichen Ergebnisvertrags der KI - Änderung der Dateinamensregeln - Änderung der Retry-Regeln - Änderung des Batch-Betriebsmodells - Änderung der bestehenden fachlichen Kernlogik außerhalb der für die Claude-Integration nötigen Anbindung - Persistenz- oder Schemaänderungen ohne zwingenden Bedarf für die Provider-Erweiterung (additive Provider-Identifikator-Spalte ist explizit zwingend, mehr nicht) ## Verbindliche Regeln für **alle** Arbeitspakete ### 1. Minimale Erweiterung des Basisstands Die Erweiterung darf den bestehenden fachlichen Ablauf **nicht stillschweigend verändern**. Ziel ist ausschließlich: - den bestehenden OpenAI-kompatiblen KI-Weg weiter nutzbar zu halten, - zusätzlich einen nativen Anthropic-Messages-API-Adapter zu integrieren, - und zwischen beiden Wegen über die Konfiguration genau **einen aktiven Provider** auszuwählen. ### 2. Einheitlicher fachlicher KI-Vertrag Unabhängig vom Provider gilt weiterhin derselbe fachliche Vertrag: - gleicher fachlicher Input - gleicher fachlicher Output (`NamingProposal`) - gleicher Validierungs- und Folgeprozess in der Anwendung - keine provider-spezifische Verzweigung im fachlichen Kern - der bestehende strukturierte Ergebnisvertrag bleibt unverändert; es entsteht **kein** provider-spezifischer Sonderweg ### 3. Genau ein aktiver Provider Es werden gespeichert: - **genau eine** Konfiguration für die OpenAI-kompatible Provider-Familie - **genau eine** Konfiguration für die Anthropic-Provider-Familie - **genau ein** aktiver Provider Es gibt: - keine Profilverwaltung - keine Prioritätenliste - keinen Mehrfach-Fallback - keine automatische Umschaltung bei Fehlern ### 4. Properties-Datei bleibt führend Die Konfiguration bleibt in der `.properties`-Datei geführt. Die Struktur darf weiterentwickelt werden, muss aber: - bestehende Properties-Dateien des Vorgängerstands **weiterhin akzeptieren**, - diese **beim ersten Start** kontrolliert in die neue Struktur überführen, - **vor** der Migration immer eine `.bak`-Sicherung anlegen. ### 5. Migration bestehender Properties beim ersten Start Wird eine Legacy-Form erkannt, gilt verbindlich: 1. Legacy-Form erkennen 2. `.bak`-Sicherung anlegen 3. Datei in die neue Struktur migrieren (Legacy-Werte → Namensraum `openai-compatible`, `ai.provider.active=openai-compatible`) 4. Datei erneut laden und validieren 5. Erst danach den normalen Lauf fortsetzen Alte und neue Struktur sind **kein** dauerhaft gleichrangiges Endformat. ### 6. OpenAI-kompatibler Weg bleibt funktional unverändert Der bestehende OpenAI-kompatible Adapter bleibt funktional unverändert nutzbar. Daraus folgt: - kein fachlicher Regressionsumbau des bisherigen Provider-Verhaltens - bestehende Konfigurationen müssen nach der Migration weiterhin funktional anschlussfähig sein - die Erweiterung darf den bestehenden Weg nicht beschädigen ### 7. Claude wird über die native Messages API angebunden Anthropic Claude wird über einen **eigenen nativen Adapter** im Adapter-Out-Modul angebunden. Daraus folgt: - Endpunkt, Authentifizierungsschema, Request- und Response-Format der Anthropic Messages API leben **ausschließlich** im Adapter - Domain und Application bleiben provider-neutral - die provider-spezifische Request-/Response-Abbildung darf den fachlichen Vertrag nicht verändern - Adapter dürfen nicht voneinander abhängen; es gibt keine gemeinsame Zwischenschicht ### 8. Provider-Auswahl ist strikt und ohne Fallback Der aktive Provider wird ausschließlich aus der Konfiguration bestimmt. Daraus folgt: - nur der aktive Provider wird verwendet - der inaktive Provider wird in keiner Fehlersituation als Backup verwendet - Fehler des aktiven Providers bleiben Fehler dieses einen Pfads und folgen der bestehenden Retry- und Fehlersemantik ### 9. Keine Zusatzänderungen ohne direkten Provider-Bezug Es werden nur solche Änderungen eingeführt, die für die zusätzliche Claude-Integration und die dafür nötige Provider-Auswahl tatsächlich erforderlich sind. Daraus folgt: - keine zusätzlichen Komfortfunktionen - keine allgemeine Provider-Plattform - keine Änderungen an Persistenz oder Nachvollziehbarkeit, sofern sie für diese Erweiterung nicht zwingend erforderlich sind (additive Provider-Identifikator-Spalte ist die einzige zwingende Persistenzänderung) ### 10. Architekturtreue Es gilt unverändert: - strikte hexagonale Architektur - Abhängigkeiten zeigen nach innen - keine Infrastrukturtypen in Domain oder Application - keine direkte Adapter-zu-Adapter-Kopplung - keine Vermischung von Provider-spezifischer HTTP-Kommunikation mit fachlicher Entscheidungslogik - der `AiNamingPort` bleibt provider-neutral --- ## AP-001 – Konfigurations-Schema, Migration mit `.bak` und Startvalidierung ### Voraussetzung Keine. Dieses Arbeitspaket ist der Startpunkt der Erweiterung. ### Ziel Die Konfiguration wird mit minimalem Eingriff so erweitert, dass zwischen den unterstützten Provider-Familien gewählt werden kann, und bestehende Properties-Dateien aus dem Vorgängerstand werden beim ersten Start automatisch sicher in das neue Schema überführt. ### Muss umgesetzt werden - Properties-Schema minimal so erweitern, dass folgende Informationen konfigurierbar sind: - aktiver Provider (`ai.provider.active`), - Konfigurations-Namensraum für die OpenAI-kompatible Provider-Familie, - Konfigurations-Namensraum für die Claude-Provider-Familie. - Legacy-Form (flache `api.*`-Schlüssel) eindeutig erkennen. - Vor jeder Migration automatisch eine **`.bak`-Sicherung** anlegen. - Migration als **In-Place-Update** umsetzen: - Legacy lesen, - in neues Schema überführen, - in-place schreiben, - neu laden, - validieren. - Legacy-Werte korrekt in den Namensraum `openai-compatible` überführen und `ai.provider.active=openai-compatible` setzen. - Startvalidierung gezielt erweitern, insbesondere für: - genau ein gesetzter, unterstützter aktiver Provider, - nur die für den aktiven Provider nötigen Pflichtwerte, - technisch konsistente Provider-Konfiguration (Modellname, Timeout, ggf. Basis-URL), - API-Schlüssel des aktiven Providers (Umgebungsvariable hat Vorrang vor Properties). - Konfigurationsbeispiele, JavaDoc und unmittelbar betroffene Repository-Dokumente anpassen. - Tests ergänzen für: - erfolgreiche Migration einer realistischen Legacy-Datei, - `.bak`-Erzeugung, - korrekte Übernahme der Legacy-Werte in den `openai-compatible`-Namensraum, - Abweisung ungültiger oder fehlender `ai.provider.active`, - Abweisung unvollständiger Pflichtwerte für den aktiven Provider, - Vorrang der Umgebungsvariablen vor dem Properties-Schlüssel des aktiven Providers. ### Explizit nicht Teil - nativer Claude-Adapter - Bootstrap-Auswahl des aktiven Providers (folgt in AP-002) - Refactoring des bestehenden OpenAI-kompatiblen Adapters über das für das neue Schema nötige Maß hinaus - Persistenz- oder Schemaänderungen - fachliche Änderungen am KI-Ergebnisvertrag ### Fertig wenn - das erweiterte Properties-Schema technisch nutzbar ist, - Legacy-Dateien beim ersten Start sicher mit `.bak` migriert werden, - ungültige Provider-Konfigurationen sauber abgewiesen werden, - der Build weiterhin fehlerfrei ist und alle bestehenden Tests grün bleiben. --- ## AP-002 – Bestehenden OpenAI-kompatiblen Pfad an die Provider-Auswahl anbinden ### Voraussetzung AP-001 ist abgeschlossen. ### Ziel Der bestehende OpenAI-kompatible KI-Weg wird mit minimalem Umbau so eingebettet, dass das Bootstrap-Modul den aktiven Provider aus der Konfiguration auswählen und verdrahten kann, ohne den bisherigen fachlichen Ablauf zu verändern. ### Muss umgesetzt werden - Im Bootstrap-Modul eine **Provider-Auswahl** einführen, die anhand von `ai.provider.active` genau eine `AiNamingPort`-Implementierung als aktive Implementierung verdrahtet. - Den bestehenden OpenAI-kompatiblen Adapter so anbinden, dass er die Werte aus dem Namensraum `ai.provider.openai-compatible.*` konsumiert. - Den bisherigen OpenAI-kompatiblen Weg dabei funktional unverändert erhalten. - Application und Domain weiterhin frei von provider-spezifischen HTTP-/JSON-Typen halten. - Provider-spezifische Request-/Response-Abbildung und Fehlerbehandlung weiterhin klar im Adapter-Out kapseln. - Sicherstellen, dass ein zukünftiger zweiter Provider nur durch eine zusätzliche Implementierung im Adapter-Out und einen zusätzlichen Eintrag in der Provider-Auswahl angebunden wird – ohne neue Zwischenschicht und ohne Adapter-zu-Adapter-Kopplung. - Den Provider-Identifikator des aktiven Providers in die Versuchshistorie einfließen lassen (additive Schema-Erweiterung mit definiertem Default für historische Versuche). - Logging-Mindestumfang um den **aktiven Provider beim Laufstart** ergänzen. - Relevante JavaDoc- und Repository-Dokumentation mitziehen. - Tests gezielt anpassen oder ergänzen, um nachzuweisen: - der bisherige OpenAI-kompatible Pfad bleibt funktional intakt, - die Provider-Auswahl ist technisch sauber angebunden, - eine ungültige Provider-Auswahl scheitert in der Startvalidierung, - der Provider-Identifikator landet pro Versuch korrekt in der Persistenz, - der fachliche Ergebnisvertrag bleibt unverändert, - bestehende Datenbestände bleiben lesbar und korrekt interpretierbar. ### Explizit nicht Teil - nativer Claude-Adapter - Fallback-Logik - zusätzliche Provider-Familien - Persistenz- oder Schemaänderungen jenseits der additiven Provider-Identifikator-Spalte - globale Abschlussprüfung ### Fertig wenn - der OpenAI-kompatible Weg über die neue Provider-Auswahl sauber nutzbar bleibt, - sein fachliches Verhalten gegenüber dem Vorgängerstand unverändert ist, - keine Provider-Implementierungsdetails in den fachlichen Kern durchsickern, - der Provider-Identifikator persistent erfasst wird, - bestehende Datenbestände unverändert nutzbar bleiben, - der Build weiterhin fehlerfrei ist. --- ## AP-003 – Nativen Anthropic-Messages-API-Adapter implementieren und verdrahten ### Voraussetzung AP-001 und AP-002 sind abgeschlossen. ### Ziel Ein nativer Adapter für die Anthropic Messages API ist technisch nutzbar, wird über die Provider-Auswahl als aktiver Provider verdrahtet und liefert fachlich denselben Ergebnisvertrag wie der bestehende OpenAI-kompatible Weg. ### Muss umgesetzt werden - Im Adapter-Out-Modul eine zweite `AiNamingPort`-Implementierung anlegen, die die **native Anthropic Messages API** anspricht. - Die Claude-spezifische Konfiguration aus dem Namensraum `ai.provider.claude.*` technisch anbinden, mindestens: - Modellname, - API-Schlüssel (Umgebungsvariable hat Vorrang), - Timeout, - Basis-URL als optionaler Konfigurationswert mit fachlich neutralem Default. - Provider-spezifische Request-Erzeugung und Response-Verarbeitung so umsetzen, dass das fachliche JSON-Ergebnis (`date`, `title`, `reasoning`) wie beim bestehenden Weg in den vorhandenen Domain-Typ `NamingProposal` abgebildet wird. - Technische Fehlerfälle des Claude-Pfads (HTTP-Fehler, Timeouts, ungültige Antwortstrukturen, Authentifizierungsfehler) **im Adapter** klassifizieren und auf die bestehende technische Fehlersemantik des Projekts abbilden. Es entstehen keine neuen Fehlerklassen. - Sicherstellen, dass Claude **keinen** Sonderweg im fachlichen Kern erzwingt und keine Application-/Domain-Klasse provider-spezifisch wird. - Die Provider-Auswahl im Bootstrap-Modul um die neue Implementierung erweitern. Das geschieht ausschließlich in der bereits in AP-002 angelegten Auswahlstelle, ohne neue Zwischenschicht. - Adapter-zu-Adapter-Kopplung aktiv vermeiden: keine gemeinsame Basisklasse, kein gemeinsamer Hilfsadapter zwischen Port und konkreten Adaptern. - Konfigurationsbeispiele, JavaDoc und unmittelbar betroffene Repository-Dokumente mitziehen. - Tests ergänzen für: - korrekte Request-Erzeugung gegen die Anthropic Messages API (Adapter-Test mit gemocktem HTTP-Layer), - korrekte Response-Abbildung auf den bestehenden fachlichen Vertrag, - technische Claude-Fehlerfälle (HTTP-Fehler, Timeout, Auth-Fehler, defekte Antwortstruktur) und deren Klassifikation, - Auswahl und Nutzung von Claude als aktivem Provider über die Konfiguration, - keine fachliche Sonderbehandlung gegenüber dem OpenAI-kompatiblen Pfad, - korrekter Provider-Identifikator in der Versuchshistorie für Claude-Läufe. ### Explizit nicht Teil - automatische Fallback-Logik - weitere Provider-Familien - Persistenz- oder Schemaänderungen jenseits der bereits in AP-002 eingeführten additiven Provider-Identifikator-Spalte - neue Fachfunktionalität außerhalb der Provider-Erweiterung - globale Abschlussprüfung ### Fertig wenn - der native Anthropic-Messages-API-Adapter technisch nutzbar ist, - Claude über die Konfiguration als aktiver Provider auswählbar ist, - sein Ergebnis fachlich auf denselben Vertrag wie der bestehende Provider abgebildet wird, - provider-spezifische Details ausschließlich im Adapter-Out leben, - der bestehende OpenAI-kompatible Pfad weiterhin unverändert nutzbar ist, - der Build weiterhin fehlerfrei ist. --- ## AP-004 – Regressionsschutz, Dokumentationskonsolidierung und Abschlussnachweis ### Voraussetzung AP-001 bis AP-003 sind abgeschlossen. ### Ziel Der vollständige Erweiterungsstand wird automatisiert abgesichert, dokumentarisch konsolidiert und als minimale Erweiterung des freigegebenen Basisstands belastbar nachgewiesen. ### Muss umgesetzt werden - Den vollständigen Erweiterungsstand gegen die in diesem Dokument definierten Regeln prüfen. - Tests vervollständigen bzw. konsolidieren, insbesondere für: - erfolgreiche Migration einer realistischen Legacy-Properties-Datei, - `.bak`-Erzeugung, - OpenAI-kompatibler Provider weiterhin nutzbar (Regression), - nativer Anthropic-Provider nutzbar, - genau ein aktiver Provider, ohne Fallback-Umschaltung, - einheitlicher fachlicher Ergebnisvertrag über beide Provider hinweg, - Provider-Identifikator in der Versuchshistorie korrekt gesetzt, - Logging des aktiven Providers beim Laufstart vorhanden, - Sensibilitätsregel für KI-Inhalte gilt provider-unabhängig, - bestehende Datenbestände bleiben lesbar und korrekt interpretierbar. - Vorhandene PIT-/Mutationstest-Konfiguration auf die neuen oder geänderten Klassen ausdehnen, soweit für den Stand sinnvoll. - Smoke-Tests so erweitern, dass für **beide** Provider-Konfigurationen der Bootstrap-Pfad bis zur erfolgreichen Verdrahtung des `AiNamingPort` durchläuft (ohne realen externen Aufruf). - Konfigurationsbeispiele, Startdokumentation und sonstige Repository-Dokumente konsolidieren, sodass die Erweiterung ohne implizite Annahmen verständlich bleibt. - Einen knappen, im Repository verbleibenden Abschlussnachweis ergänzen, der mindestens festhält: - welche Prüfungen tatsächlich ausgeführt wurden, - dass die Erweiterung minimal-invasiv umgesetzt wurde, - dass beide Provider-Familien unterstützt werden, - dass die Konfigurationsmigration und `.bak`-Sicherung nachgewiesen sind, - dass keine Architekturbrüche eingeführt wurden. - Den relevanten Build-/Test-Umfang tatsächlich ausführen. ### Explizit nicht Teil - weitere Provider-Familien - zusätzliche Konfigurationsprofile - neue Komfort- oder Bedienfunktionen - weitergehende Architekturumbauten ohne direkten Bezug zur Erweiterung ### Fertig wenn - der vollständige Erweiterungsstand automatisiert abgesichert ist, - die Dokumentation konsistent zum realen Verhalten passt, - die Minimalinvasivität gegenüber dem Basisstand belastbar nachgewiesen ist, - ein fehlerfreier, übergabefähiger Stand vorliegt.