Communitygithub.com

leanagentkit

Eine schlankere Alternative zu GitHub Spec Kit

Was ist leanagentkit?

Dieses Skill, „Clean Architecture Framework

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add renatoxm/leanagentkit

In Ihrer bevorzugten KI fragen

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

Dokumentation

Clean Architecture Framework

Ein disziplinierter Ansatz zur Strukturierung von Software, sodass Geschäftsregeln unabhängig von Frameworks, Datenbanken und Liefermechanismen bleiben. Wenden Sie diese Prinzipien an, wenn Sie Systemarchitekturen entwerfen, Modulgrenzen überprüfen oder bei der Abhängigkeitsverwaltung beraten.

Kernprinzip

Quellcode-Abhängigkeiten müssen nach innen zeigen – zu Richtlinien höherer Ebene. Nichts in einem inneren Kreis darf etwas über einen äußeren Kreis wissen. Diese einzige Regel erzeugt Systeme, die testbar und unabhängig von Frameworks, Benutzeroberflächen, Datenbanken und externen Instanzen sind. Geschäftsregeln sind das, was zählt; Datenbanken, Web-Frameworks und Liefermechanismen sind Details – wenn Details von Richtlinien abhängen, können Sie Entscheidungen aufschieben, Implementierungen austauschen und Geschäftslogik isoliert testen.

Bewertung

Ziel: 10/10. Vergeben Sie einen Punkt für jede der sieben Zeilen der Schnelldiagnose, die die Architektur erfüllt (0-7), und ordnen Sie diese dann einer 0-10-Skala zu: 6-7 erfüllt = 9-10 (Abhängigkeitsregel gilt, Geschäftslogik ist framework- und datenbankunabhängig); 4-5 = 6-8 (Kern ist testbar, aber einige Details sickern nach innen); 2-3 = 3-5 (Framework oder Persistenz bestimmt die Struktur); 0-1 = 0-2 (keine Grenzen – Geschäftsregeln leben in Controllern und ORM-Modellen). Berichten Sie die Punktzahl, die nicht bestandenen Diagnosezeilen und die spezifische Umkehrung, die zur Behebung jeder einzelnen erforderlich ist.

1. Abhängigkeitsregel und konzentrische Kreise

Kernkonzept: Organisieren Sie die Architektur als konzentrische Kreise – Entitäten (unternehmensweite Geschäftsregeln) am innersten, dann Anwendungsfälle (anwendungsspezifische Geschäftsregeln), dann Schnittstellenadapter, mit Frameworks und Treibern am äußersten. Quellcode-Abhängigkeiten zeigen immer nach innen.

Warum es funktioniert: Wenn Richtlinien hoher Ebene nicht von Details niedriger Ebene abhängen, können Sie die Datenbank, das Web-Framework oder den API-Stil austauschen, ohne die Geschäftslogik zu berühren – das System wird widerstandsfähig gegenüber den volatilsten Teilen des Stacks.

Wichtige Erkenntnisse:

  • Innere Kreise dürfen keine Namen äußerer Kreise erwähnen – keine Klassen, Funktionen, Variablen oder Datenformate von außen
  • Daten, die eine Grenze überschreiten, müssen in der für den inneren Kreis günstigsten Form vorliegen, niemals vom äußeren Kreis vorgegeben
  • Dependency Inversion (nach innen definierte, nach außen implementierte Schnittstellen) ist der Mechanismus, der die Regel durchsetzt
  • Die Anzahl der Kreise ist nicht festgelegt – vier sind typisch; die Regel bleibt gleich
  • Frameworks sind Details, keine Architektur – sie gehören in den äußersten Kreis

Code-Anwendungen:

KontextMusterBeispiel
SchichtenrichtungInnere Kreise definieren Schnittstellen; äußere implementierenBenutzerRepository-Schnittstelle in Anwendungsfällen; PostgresBenutzerRepository in Adaptern
DatenübertragungDTOs überqueren Grenzen, nicht ORM-EntitätenAnwendungsfall gibt Benutzerantwort-DTO zurück, nicht ein ActiveRecord-Modell
AbhängigkeitsrichtungImportpfeile zeigen immer nach innenController importiert Anwendungsfall; Anwendungsfall importiert niemals Controller

Siehe references/dependency-rule.md, wenn ein Import aus dem inneren Kreis nach außen zeigt und Sie die Code-Durchlauf durch die vier Kreise, die Regeln für Datenübertragung und die vierstufige Dependency-Inversion-Prozedur zur Behebung benötigen.

2. Entitäten und Anwendungsfälle

Kernkonzept: Entitäten kapseln unternehmensweite Geschäftsregeln – Regeln, die auch ohne Software existieren würden. Anwendungsfälle enthalten anwendungsspezifische Regeln, die den Datenfluss zu und von Entitäten orchestrieren.

Warum es funktioniert: Die Trennung von dem, was das Geschäft tut (Entitäten), und wie die Anwendung es orchestriert (Anwendungsfälle), ermöglicht die Wiederverwendung von Entitäten über Anwendungen hinweg und die Änderung des Anwendungsverhaltens, ohne die Kern-Geschäftsregeln zu verändern.

Wichtige Erkenntnisse:

  • Entitäten sind keine Datenbankzeilen – sie sind Objekte oder reine Funktionen, die kritische Geschäftsregeln kapseln
  • Anwendungsfälle akzeptieren Anforderungsmodelle und geben Antwortmodelle zurück – niemals Framework-Objekte
  • Jeder Anwendungsfall ist ein einzelner Anwendungsvorgang (BestellungErstellen, AusgabeGenehmigen)
  • Das Interactor-Muster: Eine Anwendungsfall-Klasse implementiert eine Eingabe-Grenzschnittstelle und ruft eine Ausgabe-Grenzschnittstelle auf
  • Änderungen an einem Anwendungsfall sollten niemals eine Entität betreffen; Änderungen an Entitäten können sich auf Anwendungsfälle auswirken

Code-Anwendungen:

KontextMusterBeispiel
EntitätsdesignKritische Geschäftsregeln, null Framework-AbhängigkeitenBestellung.berechneGesamtsumme() wendet Steuerregeln an; weiß nichts über HTTP
Anforderung/AntwortEinfache Datenstrukturen überqueren die GrenzeBestellungErstellenAnfrage { artikel, kundenId } – keine ORM-Modelle
EinzelverantwortungEin Anwendungsfall pro VorgangBestellungAufgeben, BestellungStornieren, BestellungRückerstatten als separate Klassen
InteractorImplementiert Eingabeport, ruft Ausgabeport aufBestellungAufgebenInteractor implements BestellungAufgebenEingabe

Siehe references/entities-use-cases.md beim Entwerfen eines Interactors oder bei der Entscheidung, was in eine Entität vs. einen Anwendungsfall gehört – vollständige Behandlung der Unternehmens- vs. Anwendungs-Geschäftsregeln mit Beispielen für Anforderungs-/Antwortmodelle.

3. Schnittstellenadapter und Frameworks

Kernkonzept: Schnittstellenadapter konvertieren Daten zwischen der für Anwendungsfälle/Entitäten bequemen Form und der von externen Instanzen geforderten Form. Frameworks und Treiber sind die äußerste Schicht – Klebecode zur Außenwelt.

Warum es funktioniert: Wenn das Web-Framework, ORM oder die Nachrichtenwarteschlange auf die äußeren Kreise beschränkt ist, ist das Ersetzen eines von ihnen eine lokalisierte Änderung. Die Datenbank ist ein Detail; das Web ist ein Detail; Details sollten Plugins für Ihre Geschäftsregeln sein, nicht das Skelett der Anwendung.

Wichtige Erkenntnisse:

  • Controller übersetzen HTTP in Anwendungsfalleingaben; Presenter übersetzen Anwendungsfallausgaben in Ansichtsmodelle
  • Gateways implementieren von Anwendungsfällen definierte Repository-Schnittstellen – der innere Kreis definiert den Vertrag, der äußere erfüllt ihn
  • Geschäftsregeln wissen nie, ob Daten in SQL, NoSQL oder flachen Dateien leben oder ob die Lieferung über HTTP erfolgt
  • Behandeln Sie Frameworks mit Misstrauen – sie möchten, dass Sie sich an sie koppeln; halten Sie sie auf Armeslänge

Code-Anwendungen:

KontextMusterBeispiel
ControllerLiefermechanismus → AnwendungsfalleingabeBestellungController.erstellen(req) erstellt BestellungErstellenAnfrage, ruft Interactor auf
PresenterAnwendungsfallausgabe → AnsichtsmodellBestellungPresenter.präsentieren(antwort) formatiert für JSON/HTML
GatewayPro DB implementierte Repository-SchnittstelleSqlBestellungRepository implementiert BestellungRepository
Framework-GrenzeFramework ruft nach innen auf, nie umgekehrtExpress-Routen-Handler ruft Controller auf; Controller importiert nie Express

Siehe references/adapters-frameworks.md beim Verdrahten von Controllern, Presentern oder Gateways oder beim Argumentieren, dass Datenbank/Web ein Detail sind – behandelt Plugin-Architektur und wie man ein Framework auf die Ränder beschränkt.

4. Komponentenprinzipien

Kernkonzept: Komponenten sind die Bereitstellungseinheiten. Drei Kohäsionsprinzipien bestimmen, was in eine Komponente gehört; drei Kopplungsprinzipien bestimmen die Beziehungen zwischen Komponenten.

Warum es funktioniert: Schlecht zusammengesetzte Komponenten erzeugen Auswirkungen, bei denen eine Änderung die erneute Bereitstellung von nicht zusammenhängendem Code erzwingt; die Prinzipien halten Änderungen lokal und veröffentlichungen unabhängig.

Wichtige Erkenntnisse:

  • REP (Wiederverwendungs-/Veröffentlichungsäquivalenz): Klassen in einer Komponente müssen als Einheit versionierbar und veröffentlichbar sein
  • CCP (Gemeinsamer Abschluss): Klassen, die sich aus demselben Grund zur selben Zeit ändern, gehören zusammen – SRP für Komponenten
  • CRP (Gemeinsame Wiederverwendung): Zwingen Sie Benutzer nicht, von Klassen abzuhängen, die sie nicht verwenden
  • ADP (Azyklische Abhängigkeiten): Der Komponentengraph darf keine Zyklen haben – brechen Sie sie mit DIP oder einer neuen Komponente auf
  • SDP (Stabile Abhängigkeiten): Hängen Sie in Richtung der Stabilität ab
  • SAP (Stabile Abstraktionen): Stabile Komponenten sollten abstrakt sein; instabile konkret

Code-Anwendungen:

KontextMusterBeispiel
KomponentengruppierungGruppieren Sie Klassen, die sich gemeinsam ändern (CCP)Alle bestellbezogenen Anwendungsfälle in einer Komponente
Zyklen brechenWenden Sie DIP an, um eine Abhängigkeitskante umzukehrenExtrahiere eine Schnittstelle in eine neue Komponente, um den Zyklus zu brechen
StabilitätsmetrikenInstabilität I = Ce / (Ca + Ce)Viele eingehende, keine ausgehenden Abhängigkeiten → I nahe 0 (stabil)

Siehe references/component-principles.md beim Gruppieren von Klassen in bereitstellbare Komponenten oder beim Brechen eines Abhängigkeitszyklus – jedes von REP, CCP, CRP, ADP, SDP, SAP durchgearbeitet mit der Instabilitätsmetrik.

5. SOLID-Prinzipien

Kernkonzept: Fünf Prinzipien auf Klassen- und Modulebene – Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion – die Bausteine der mittleren Ebene, die die Abhängigkeitsregel ermöglichen.

Warum es funktioniert: Jedes Prinzip adressiert eine spezifische Art und Weise, wie Abhängigkeiten schiefgehen, und verhindert die Starrheit, Zerbrechlichkeit und Unbeweglichkeit, die Codebasen zu Albtraum-Altsystemen machen.

Wichtige Erkenntnisse:

  • SRP: Ein Modul hat einen Grund, sich zu ändern – es dient einem Akteur (nicht „es tut eine Sache“)
  • OCP: Verhalten durch Hinzufügen von neuem Code erweitern, nicht durch Ändern von vorhandenem – Strategie- und Plugin-Muster
  • LSP: Untertypen müssen über die Basisschnittstelle nutzbar sein, ohne dass der Client es weiß – verletzt durch unerwartete Ausnahmen oder ignorierte Methoden
  • ISP: Clients sollten nicht von Methoden abhängen, die sie nicht verwenden – fette Schnittstellen erzeugen unnötige Kopplung
  • DIP: Hochwertige Module und niederwertige Module hängen beide von Abstraktionen ab, die vom hochwertigen Modul definiert werden

Code-Anwendungen:

KontextMusterBeispiel
SRP-VerletzungKlasse dient mehreren AkteurenMitarbeiter behandelt Gehalt (CFO), Berichterstattung (COO), Persistenz (CTO)
OCP via StrategieNeues Verhalten durch neue KlassenExpressVersand implementiert Versandstrategie; Bestellung unberührt
LSP-VerletzungUntertyp ändert erwartetes VerhaltenQuadrat erweitert Rechteck bricht den setBreite()/setHöhe()-Vertrag
ISP-AnwendungFette Schnittstellen in Rollenschnittstellen aufteilenDrucker, Scanner, Fax statt einem Multifunktionsgerät
DIP-VerdrahtungHochwertig definiert Schnittstelle; niederwertig implementiertBestellService hängt von ZahlungsGateway ab, nicht von StripeClient

Siehe references/solid-principles.md bei der Anwendung von SRP/OCP/LSP/ISP/DIP auf eine bestimmte Klasse oder bei der Diagnose einer Verletzung – jedes Prinzip durchgearbeitet mit Codebeispielen und dem Geruch, den es verhindert.

6. Grenzen und Grenzanatomie

Kernkonzept: Eine Grenze ist eine Linie zwischen Dingen, die wichtig sind, und Details, implementiert durch Polymorphismus: Abhängigkeiten kreuzen nach innen zeigend, während der Kontrollfluss in beide Richtungen verlaufen kann.

Warum es funktioniert: Jede Grenze erkauft die Option, eine Entscheidung aufzuschieben oder eine Implementierung auszutauschen; die strategische Platzierung von Grenzen bestimmt, ob ein System über Jahre hinweg eine Freude oder eine Qual zu warten ist.

Wichtige Erkenntnisse:

  • Vollständige Grenzen verwenden reziproke Schnittstellen auf beiden Seiten; partielle Grenzen verwenden eine einfachere Strategie oder Fassade
  • Bescheidenes-Objekt-Muster: Teilen Sie Grenzcode in einen schwer testbaren Teil (nahe der Grenze) und einen einfach testbaren Teil (die Logik)
  • Dienste sind nicht automatisch architektonische Grenzen – ein Microservice mit einem fetten gemeinsamen Datenmodell ist ein Monolith mit Netzwerkaufrufen
  • Tests sind die isolierteste Komponente: Sie hängen nach innen ab, nichts hängt von ihnen ab
  • Vorzeitige Grenzen sind teuer, aber fehlende auch – ziehen Sie sie an Punkten wahrscheinlicher Volatilität

Code-Anwendungen:

KontextMusterBeispiel
Vollständige vs. partielle GrenzeReziproke Ports oder eine einzelne StrategieAnwendungsfall definiert BestellungAufgebenEingabe/BestellungAufgebenAusgabe; einfachere Fälle nehmen eine Versandstrategie
Bescheidenes ObjektTestbare Logik von Infrastruktur trennenPresenterLogik (testbar) erzeugt Ansichtsmodell; Ansicht (bescheiden) rendert es
Main als PluginKompositionswurzel setzt das System zusammenmain() verdrahtet alle konkreten Implementierungen und startet die App

Siehe references/boundaries.md bei der Entscheidung, wo eine Grenze zu ziehen ist, bei der Wahl zwischen vollständiger und partieller Grenze oder bei der Anwendung des Bescheidenen-Objekt-Musters – behandelt auch Dienste als Grenzen, Testgrenzen und Main als das ultimative Plugin.

Häufige Fehler

FehlerWarum es scheitertBehebung
ORM sickert in GeschäftslogikEntitäten koppeln an das Schema; DB-Änderungen schreiben Geschäftsregeln neuTrennen Sie Domänenentitäten von Persistenzmodellen; mappen Sie auf der Adapterschicht
Geschäftsregeln in ControllernOhne HTTP nicht testbar; über Endpunkte dupliziertVerschieben Sie Logik in Anwendungsfall-Interactors; Controller übersetzen und delegieren nur
Framework-zentrierte ArchitekturFramework bestimmt Struktur; Austausch bedeutet NeuschreibungBehandeln Sie das Framework als Plugin; strukturieren Sie Code nach Geschäftsfähigkeit
Zirkuläre KomponentenabhängigkeitenÄnderungen wirken sich unvorhersehbar aus; keine unabhängigen VeröffentlichungenWenden Sie DIP an oder extrahieren Sie eine gemeinsame Abstraktionskomponente
Ein riesiger Anwendungsfall pro FunktionAufgeblähte tausendzeilige OrchestratorenTeilen Sie in fokussierte Einzelvorgangs-Anwendungsfälle auf
Grenzen überspringen, „weil es einfach ist“Kopplung sammelt sich still an, bis die Kosten enorm sindZiehen Sie Grenzen proaktiv an Punkten wahrscheinlicher Volatilität
Microservices als automatisch gute ArchitekturEin verteilter Monolith ist schlimmer als ein sauberer MonolithWenden Sie die Abhängigkeitsregel innerhalb und zwischen Diensten an; Dienste sind Bereitstellungsgrenzen, keine architektonischen

Schnelldiagnose

FrageWenn NeinAktion
Können Sie Geschäftsregeln ohne DB, Webserver oder Framework testen?Regeln an Infrastruktur gekoppeltExtrahiere Entitäten und Anwendungsfälle hinter Schnittstellen; mocke äußere Schichten
Zeigen alle Quellcode-Abhängigkeiten nach innen? (Kein Import aus innerem Kreis nach außen)Abhängigkeitsregel verletztWende Dependency Inversion an: Definiere Schnittstelle im inneren Kreis, verschiebe Implementierung nach außen
Können Sie die Datenbank wechseln, ohne Geschäftslogik zu ändern?Geschäftslogik kennt DB-APIMappe ORM auf Domänen-Entitäten im Repository-Adapter; ändere Geschäftslogik nie
Haben Sie isolierte Anwendungsfälle, die eine Sache tun?Anwendungsfälle sind aufgebläht oder fehlenRefaktoriere in einzelne, nach Aktion benannte Anwendungsfall-Klassen
Sind Framework-Importe auf die äußerste Schicht beschränkt?Framework sickert in Anwendungsfälle oder EntitätenExtrahiere Framework-Code in Adapter; Geschäftslogik darf Framework nicht importieren
Kann eine neue Version einer Komponente bereitgestellt werden, ohne andere neu zu deployen?Zirkuläre Abhängigkeiten oder verdeckte KopplungBreche Zyklen auf; wende Stabile-Abhängigkeiten-Prinzip (SDP) an
Prüfen Sie regelmäßig Abhängigkeiten mit Abhängigkeits- und Stabilitätsmetriken?Architektur degradiert ohne MessungFühre automatische Prüfungen in CI/CD ein; richte Governance mit ADRs ein

Nächste Schritte

  1. Diagnostizieren: Beantworten Sie die 7 Schnelldiagnose-Fragen für jedes Modul oder jeden Dienst
  2. Scoren: Berechnen Sie den Clean Architecture Score 0-10
  3. Priorisieren: Wählen Sie den niedrigsten Score und die einfachste Behebung aus der Fehlertabelle
  4. Umsetzen: Verwenden Sie die Referenzdateien (references/*.md) für Schritt-für-Schritt-Code-Anwendungen:

Verwandte Skills