pdf-umbenenner/docs/workpackages/V1.1 - Neue Arbeitspakete.md

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.