CommunityCodierung & Entwicklunggithub.com

zu-hexagonaler-architektur

Analysiere eine bestehende Codebasis in jeder Sprache oder jedem Framework und erstelle einen schrittweisen Refactoring-Plan ohne Breaking Changes, um sie auf Hexagonale Architektur (Ports and Adapters) zu migrieren. Verwende dies, wenn der Benutzer eine Refaktorisierung, Migration oder Umstrukturierung eines Dienstes, einer API oder eines Monolithen in hexagonale Architektur, Ports and Adapters oder Clean Architecture wünscht, während bestehende Verträge erhalten bleiben.

Was ist zu-hexagonaler-architektur?

Diese Skill hilft dir, eine bestehende Codebasis sicher und schrittweise in Hexagonale Architektur (Ports and Adapters) zu migrieren, ohne externe Verträge zu verletzen. Sie ist ideal für Entwickler, die eine saubere Trennung von Geschäftslogik und technischen Details (Frameworks, ORMs, Datenbanken, Message Broker) erreichen möchten, und funktioniert mit jeder Sprache oder jedem Framework (TypeScript, Python, Go, Java, C#, Rust usw.). Die Skill arbeitet ausschließlich im Planmodus: Sie durchsucht zuerst die Codebasis, identifiziert Einstiegspunkte, externe Abhängigkeiten und aktuelle Datenflüsse und erstellt dann einen detaillierten, fünfphasigen Refactoring-Plan. Der Plan stellt sicher, dass jeder Schritt durch automatisierte Charakterisierungstests abgesichert ist, null Breaking Changes einführt und die strikte Abhängigkeitsregel einhält – wonach das Domain-Layer keinerlei Importe aus Web-Frameworks, Datenbanktreibern oder ORMs haben darf. Die Struktur des Zielprojekts folgt einem klaren Schema mit den Schichten `domain/`, `application/` und `infrastructure/`, ergänzt durch einen expliziten Composition-Root (DI-Komposition) für eine testbare und wartbare Architektur.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrandalisse/skills/tree/HEAD/skills/to-hexagonal-architecture

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Zu Hexagonaler Architektur

Analysiere ein vorhandenes Repository gründlich und entwerfe einen atomaren, schrittweisen Refactoring-Plan, um es auf Hexagonale Architektur (Ports and Adapters) zu migrieren, ohne externe Verträge oder beobachtbares Verhalten zu brechen.

Antworte in derselben Sprache wie die Anfrage des Benutzers. Arbeite streng im Planmodus: Untersuche zuerst die Codebasis und liefere den vollständigen Plan, bevor du Dateien änderst.

Wann verwenden

  • Der Benutzer bittet um Migration oder Refactoring eines bestehenden Projekts in Hexagonale Architektur oder Ports and Adapters.
  • Der Benutzer möchte die Geschäftslogik von Web-Frameworks, ORMs, Datenbanken, Message Brokern oder externen SDKs entkoppeln.
  • Der Benutzer wünscht einen sicheren, inkrementellen Architektur-Refactoring-Plan ohne Breaking Changes.

Kernprinzipien

  1. Null Breaking Changes (Goldene Regel): Jeder bestehende externe Vertrag muss erhalten bleiben. Routen, HTTP-Methoden, Statuscodes, Request/Response-Payload-Schemata, Header, Fehlerformate, CLI-Optionen oder Nachrichtenformate von Queues müssen identisch bleiben.
  2. Charakterisierung vor Refactoring: Verschiebe oder lösche keine Produktionslogik, bis automatisierte Vertrags-/Charakterisierungstests bestehende Endpunkte oder Einstiegspunkte abdecken.
  3. Strenge Abhängigkeitsregel: Quellcode-Abhängigkeiten müssen stets nach innen auf domain zeigen. Die Domain-Schicht darf keine Importe von Web-Frameworks, Datenbanktreibern, ORMs, Serialisierungsbibliotheken oder externen SDKs haben.
  4. Stack-idiomatische Anpassung: Passe Verzeichnispfade, Namenskonventionen, Typkonstrukte und Test-Runner an die erkannte Sprache und das Ökosystem des Projekts an (z.B. TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).

Arbeitsablauf

Schritt 1: Codebase-Erkundung

Scanne das Repository, bevor du einen Ordnerbaum oder Migrationsschritte vorschlägst:

  1. Stack und Tooling: Überprüfe Abhängigkeits-Manifeste, Compiler/Linter-Konfigurationen und Test-Runner, um die Sprache, das Framework, die Validierungsbibliothek, den ORM/Query Builder und den DI-Ansatz zu identifizieren.
  2. Einstiegspunkte und Verträge: Erfasse alle treibenden Einstiegspunkte (HTTP-Routen, GraphQL-Resolver, gRPC-Dienste, Message-Consumer, Cron-Jobs), deren Validierungsschemata, Middleware/Interceptor und globale Fehlerbehandler.
  3. Externe Abhängigkeiten: Erfasse alle getriebenen Seiteneffekte (Datenbanken, Caches, HTTP/RPC-Clients, Queues, Dateispeicher, Umgebungskonfiguration, Logger).
  4. Aktueller Ausführungsfluss: Verfolge, wie Daten derzeit vom Einstiegspunkt zur Persistenz/externen Aufruf und zurück fließen, und notiere, wo Geschäftsregeln mit Transport- oder Persistenzdetails vermischt sind.

Schritt 2: Entwurf des hexagonalen Zielaufbaus

Ordne die drei konzentrischen Schichten dem idiomatischen Quellstamm des Projekts zu (z.B. src/ in TypeScript/Rust, internal/ in Go, src/main/<lang>/ in JVM oder das Hauptpaketverzeichnis in Python):

  • domain/ (Reiner Geschäftskern - null Framework- oder I/O-Abhängigkeiten):
    • entities/ und value-objects/: Domänenmodelle, die Geschäftsregeln, Invarianten und Selbstvalidierung kapseln.
    • ports/in/: Treibende Port-Schnittstellen, die Use-Case-Verträge definieren.
    • ports/out/: Getriebene Port-Schnittstellen, die Verträge für Repository, externen Dienst, Event-Publisher und LoggerPort definieren.
    • errors/: Semantische Domänenausnahmen (z.B. ResourceNotFoundError, DomainValidationError, ConflictError).
  • application/ (Use-Case-Orchestrierung):
    • use-cases/: Implementierungen von ports/in, die Domänenentitäten und ports/out koordinieren.
    • dtos/: Unveränderliche Eingabe- und Ausgabedatenstrukturen, die von Transport-Payloads und Persistenzentitäten entkoppelt sind.
  • infrastructure/ (Technische Details und Adapter):
    • adapters/in/: Treibende Adapter (HTTP-Controller/Handler, Consumer-Handler), Transportvalidierungsschemata, Mapper (TransportInput -> InputDTO und OutputDTO -> TransportOutput) und ein globaler Fehlermapper, der domain/errors in die exakten Legacy-Fehlerantworten übersetzt.
    • adapters/out/: Konkrete Implementierungen von ports/out (Datenbank-Repositories, HTTP-Clients, Broker) mit Persistenz-/Externen-Mappern, sodass ORM-Modelle oder SDK-Typen niemals in domain/ eindringen.
    • config/: Strikte Laden und Startvalidierung von Umgebungsvariablen und Laufzeiteinstellungen.
    • di/ (Composition Root): Explizites Verkabeln von getriebenen Adaptern, Use Cases und treibenden Adaptern via Konstruktorinjektion, unter Vermeidung von versteckten Singletons oder Service Locators.
  • Bootstrap-Trennung: Trenne die Anwendungskonstruktion (buildApp / Factory-Funktion für isolierte Integrationstests) vom Server-/Prozess-Start (main / listen).

Schritt 3: Durchsetzung von Engineering-Standards im Plan

Stelle sicher, dass jede Phase im Plan Folgendes durchsetzt:

  • Starke Typisierung und Unveränderlichkeit: Verbiete untypisierte Entweichungen (wie any oder rohe untypisierte Maps, wo typisierte Strukturen anwendbar sind) und bevorzuge unveränderliche DTOs und Value Objects (readonly, eingefrorene Dataclasses, Records, Value Types).
  • SOLID und Konstruktorinjektion: Halte Klassen und Funktionen klein mit einzelnen Verantwortlichkeiten; injiziere Schnittstellen über Konstruktoren.
  • Beobachtbarkeit ohne Kopplung: Bewahre strukturiertes Logging und Request-Correlation-Kontext, während domain/ und application/ über LoggerPort von spezifischen Logging-Bibliotheken entkoppelt bleiben.
  • Pyramiden-Testing:
    • Unit-Tests für domain/ (reine Invarianten) und application/ (Mocking von ports/out).
    • Integrations-/Vertragstests, die reale treibende Adapter gegen die Anwendungsverkabelung mit dem nativen In-Memory-Test-Client des Stacks verifizieren (z.B. fastify.inject, Supertest, FastAPI TestClient, Spring MockMvc oder Go httptest).

Ausgabeformat (Planmodus)

Liefere die Antwort strukturiert in diese genauen Abschnitte:

  1. Aktuelle Architektur-Diagnose: Prägnante Inventur des erkannten Stacks, der Einstiegspunkte/Endpunkte, externen Abhängigkeiten und der wichtigsten Kopplungshotspots.
  2. Zielverzeichnisbaum: Vollständige vorgeschlagene Ordnerstruktur unter Verwendung der tatsächlichen Modul- und Feature-Namen aus dem Repository.
  3. Phasenweiser Ausführungsplan: Fünf atomare, verifizierbare Phasen:
    • Phase 1 - Charakterisierungstests und Basisgerüst: Erstelle Vertragstests, die das aktuelle Verhalten einfrieren, erstelle Zielordner, Konfigurationslader und Composition Root (di/).
    • Phase 2 - Domänenextraktion: Extrahiere Entitäten, Value Objects, Domänenfehler und ports/in + ports/out-Schnittstellen mit Unit-Tests.
    • Phase 3 - Anwendungsfälle und getriebene Adapter: Implementiere Use Cases, DTOs, adapters/out Repositories/Clients und Persistenz-Mapper.
    • Phase 4 - Treibende Adapter und Fehlerübersetzung: Refaktoriere Controller/Handler, um über Mapper an Use Cases zu delegieren, verdrahte globale Fehlerübersetzung und verbinde di/.
    • Phase 5 - Legacy-Bereinigung und finale Verifikation: Entferne obsolet gewordene Dateien, führe die vollständige Test-Suite, den Linter und den Typchecker aus und verifiziere null Vertragsabweichungen.
  4. Validierungs-Checkpoints: Am Ende jeder Phase expliziter Befehl oder Prüfung, die belegt, dass nichts gebrochen ist, bevor zur nächsten Phase übergegangen wird.

Stolperfallen

  • Code nicht vorzeitig bearbeiten: Sofern der Benutzer nicht explizit bittet, sofort mit Phase 1 zu beginnen, gib zunächst nur den Plan aus, damit er die Modulgrenzen überprüfen kann.
  • Über-Abstraktion bei trivialem CRUD vermeiden: Trenne dennoch sauber in domain, application und infrastructure, aber halte Durchgangs-Use-Cases prägnant, anstatt künstliche Domänenkomplexität zu erfinden.
  • Legacy-Eigenheiten übernehmen: Wenn ein bestehender Endpunkt einen nicht standardmäßigen Statuscode oder Fehlerfeldnamen zurückgibt, dokumentiere dies in Phase 1 und bewahre es im Fehlermapper von infrastructure, damit bestehende Clients nicht brechen.

Verwandte Skills