Craftsman Coder: SOLID, AST CodeGraph Impact & Evidence-First E…

Craftsman Coder: SOLID, AST CodeGraph Impact & Evidence-First Engineering

Ein disziplinierter, repository-unabhängiger Engineering-Workflow für den Bau robuster, entkoppelter und verifizierbarer Software.

---

Kernprinzipien

1. AST & CodeGraph Exploration First: Code niemals blind ändern oder refactoren. Immer zuerst Symboldefinitionen, Aufrufer, Aufgerufene und den Blast Radius vor der Implementierungsänderung kartieren.
2. SOLID & Single Responsibility Principle (SRP): Jedes Modul, jede Funktion und jede Klasse muss genau einen Grund für eine Änderung haben. Trenne Geschäftslogik von I/O, Persistenz und externen APIs.
   • Zerlegungsregel: Wenn eine Komponente, Klasse oder Funktion zu lang ist oder mehrere Aufgaben übernimmt, sofort in kleinere, atomare Unterkomponenten/Dienste mit einzelnem Verantwortungsbereich zerlegen.
3. Dependency Injection (DI) & Inversion of Control: Injiziere Abhängigkeiten (Repositories, Clients, Logger) über Konstruktoren oder Framework-Mechanismen. Entkopple Logik von konkreter Infrastruktur. Vermeide hartcodierte direkte externe Instanziierungen.
4. Fallback-Architektur: Vertical Slice Architecture (VSA) + EIP: Wenn ein Repository keine etablierte Framework-Konvention besitzt, priorisiere immer Vertical Slice Architecture (VSA) in Verbindung mit SOLID und Enterprise Integration Patterns (EIP):
   • Organisiere Code nach Geschäftsfähigkeiten (features/<feature_name>/) mit dem Request-Endpoint-Response (REPR)-Muster anstelle von horizontalen technischen Schichten.
   • Verwende EIP-Muster für die Slice-Koordination: Command/Query Router, Pipes and Filters, Idempotent Receiver und Domain Event Pub/Sub.
   • Detaillierte Anleitung: Vertical Slice & EIP Guide
5. Deterministisches VSA Architectural Boundary Linting: Wenn ein Repository VSA implementiert, konfiguriere einen deterministischen Grenz-Linter (z.B. dependency-cruiser für JS/TS, import-linter für Python, depguard für Go oder vsa_boundary_checker.py), um direkte Cross-Slice-Importe zu verbieten.
   • Detaillierte Anleitung: VSA Boundary Enforcement & Repo GEMINI.md Guide
6. Verpflichtende Repository-weite GEMINI.md (Portabel & Git-Ready): Beim Erstellen oder Initialisieren eines Repositorys immer eine projektweite GEMINI.md im Repo-Root generieren, um Architekturentscheidungen, Grenzregeln und Gauntlet-Befehle zu persistieren.
   • Strenge Portabilitätsregel: Da diese Datei committet und gepusht wird, darf niemals auf externe Host-Pfade (z.B. kein ~/.gemini/config/..., kein /data/data/...) oder maschinenspezifische Secrets verwiesen werden. Sie muss 100% in sich geschlossen und portabel sein.
7. Echtzeit-Web-Recherche & Optimale Big-O-Komplexität: Wähle immer Algorithmus- und Datenstrukturmuster mit der optimalen Big-O-Zeit- und -Speicherkomplexität ($O(1)$ Lookups, $O(N \log N)$ Sortierung, Streaming $O(1)$ Speicher).
   • Verpflichtende Web-Recherche: Verlasse dich niemals ausschließlich auf vortrainierte Annahmen, da das Wissen veraltet sein kann. Recherchiere immer im Web basierend auf dem aktuellen Monat und Jahr, um modernste Algorithmusmuster, optimale Datenstrukturen und neueste Hochleistungsbibliotheksimplementierungen zu entdecken.
8. Hochleistungs-, RAM-arme Bibliotheken & Enterprise-Lizenz-Compliance:
   • Spitzenleistung & geringer Speicher: Bevorzuge moderne, cache-freundliche, zero-copy, SIMD-beschleunigte Bibliotheken (z.B. orjson/msgspec, polars, sonic, zerolog, simd-json, fast-json-stringify).
   • Enterprise-Lizenz-Compliance: Wähle permissive Open-Source-Lizenzen (MIT, Apache 2.0, BSD-2/3, ISC). Vermeide streng virale Copyleft-Lizenzen (GPL, AGPL, SSPL), um eine reibungslose Passage von Unternehmensaudits ohne Offenlegungspflichten zu gewährleisten.
   • Detaillierte Anleitung: High-Performance Libraries & Licensing Guide
9. Deterministische statische Code-Analyse für SRP & Abstraktionen: Priorisiere immer deterministische statische Analysewerkzeuge, um Code auf SRP-Verletzungen (z.B. aufgeblähte Länge, übermäßige Verantwortlichkeiten) und Abstraktionsumgehungen (z.B. direkte rohe SQL- oder HTTP-Aufrufe innerhalb von Präsentations-/Geschäftslogik) zu prüfen.
10. Zentrale Secret-Injektion (Infisical): Hartcodiere niemals Secrets oder speichere rohe Anmeldeinformationen in Git/lokalen env-Dateien. Behandle Secrets als runtime-injizierte Abhängigkeiten über Infisical (infisical run -- ...).
    • Detaillierte Anleitung: Infisical Secret Management Guide
11. Framework Convention First: Respektiere idiomatische Konventionen des vorhandenen Frameworks (z.B. FastAPI Depends, NestJS @Injectable, React Hooks, Go Interfaces), anstatt Ad-hoc-Abstraktionen zu erfinden.
12. Parallelisierbare, hermetic Tests: Alle Tests müssen zustandslos, isoliert und parallelisierbar sein (z.B. pytest -n auto, go test -parallel). Kein gemeinsamer veränderlicher Zustand oder statische Singleton-Seiteneffekte.
13. Die "Old Coder"-Evidenzbasierte Disziplin: Überprüfe Evidenz, nicht Code. Folge der Spec -> RED -> GREEN -> REFACTOR-Schleife und verifiziere durch automatisierte Terminal-Prüfungen, bevor der Abschluss gemeldet wird.
14. KI-Agenten-Ready Tool & Skill Engineering: Beim Extrahieren wiederkehrender Muster in Tools und Skills: garantiere --json-Ausgabe, nicht-interaktive Ausführung (null Prompts), --dry-run-Sicherheit, vorhersagbare Nomen-Aktion-Verben und typisierte Exit-Codes.
    • Detaillierte Anleitung: AI-Agent-Ready CLI Design Guide

---

Schritt-für-Schritt-Workflow

Schritt 1: Blast-Radius-Analyse vor Änderung (CodeGraph AST)

Bevor eine Funktion, Klasse oder ein Dienst geändert wird, inspiziere den Blast-Radius, um die nachgelagerten Auswirkungen zu bestimmen:

python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <path_to_repo> --symbol <TargetSymbol>

• Überprüfe Direkte Aufrufer und Referenzierende Dateien.
• Überprüfe Betroffene Testsuiten: Wenn keine Tests dieses Symbol abdecken, musst du einen Test erstellen, bevor du refaktorierst.

Schritt 2: Architektur, Algorithmische Big-O & Repo-weite GEMINI.md

• Formuliere eine klare Spezifikation und ein klares Design:
  • Wenn ein Repository erstellt/initialisiert wird, erstelle eine in sich geschlossene GEMINI.md im Repo-Root (keine externen Pfade, keine Secrets).
  • Wenn keine Framework-Konvention existiert, organisiere in Vertical Slices (features/<name>/) mit REPR- und EIP-Mustern.
  • Richte ein oder verifiziere einen Architekturgrenz-Linter (z.B. dependency-cruiser, import-linter oder vsa_boundary_checker.py).
  • Erledigt die Klasse/Funktion/Komponente mehr als eine Aufgabe oder überschreitet sie Längenschwellen? Zerlege sie in fokussierte Unterkomponenten (SRP).
  • Sind externe Systeme eng gekoppelt? Definiere ein Interface/Protokoll und verwende Dependency Injection.
  • Algorithmische Komplexität & Websuche: Bewerte die Big-O-Zeit-/Speicherkomplexität. Suche aktiv im Web basierend auf dem aktuellen Monat und Jahr nach modernen algorithmischen Optimierungen.
  • Abhängigkeits-Audit: Wähle RAM-arme, durchsatzstarke Bibliotheken mit unternehmenssicheren Lizenzen (MIT / Apache 2.0 / BSD). Stelle sicher, dass keine copyleft/AGPL-transitiven Abhängigkeiten vorhanden sind.
• Detaillierte Referenz: SOLID & DI Patterns Guide
• Detaillierte Referenz: Vertical Slice & EIP Guide
• Detaillierte Referenz: VSA Boundary Enforcement & Repo GEMINI.md Guide
• Detaillierte Referenz: High-Performance Libraries & Licensing Guide

Schritt 3: Parallelisierbare Tests schreiben (RED)

• Schreibe einen isolierten, hermetic Unit- oder Integrationstest, der das erwartete Verhalten oder den Bugfix verifiziert.
• Stelle sicher, dass der Test unabhängige temporäre Ressourcen oder In-Memory-Mocks verwendet.
• Führe den Test aus, um zu bestätigen, dass er fehlschlägt (RED).
• Detaillierte Referenz: Parallel Testing & Old Coder Guide

Schritt 4: Minimale, saubere Lösung implementieren (GREEN)

• Implementiere nur das, was erforderlich ist, um den Test zu bestehen.
• Halte Komponenten zusammenhängend und zweckgebunden.
• Injiziere Abhängigkeiten sauber.

Schritt 5: Refaktorieren & Der Gauntlet (REFACTOR & EVIDENCE)

• Bereinige den Code, während die Tests grün bleiben.
• Führe The Gauntlet aus (alle Überprüfungen müssen automatisiert & deterministisch sein):
  1. VSA-Grenzen-Prüfung: Führe die Architekturgrenzen-Prüfung aus (z.B. npx depcruise --config .dependency-cruiser.js src oder python3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <path_to_repo>).
  2. Deterministische statische SRP- & Abstraktionsanalyse:

     python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <path_to_repo> --strict
     

  3. Linter & Statische Analyse (z.B. ruff check ., eslint, golangci-lint)
  4. Typüberprüfung (z.B. mypy, tsc --noEmit)
  5. Vollständige Testsuite parallel ausgeführt (z.B. pytest -n auto, go test -parallel 4 ./...)
• Gib Terminal-Evidenz (Exit-Codes, Zusammenfassung der bestandenen Tests) in deiner endgültigen Antwort an.

---

Integrierte Skripte & Tools

• CodeGraph AST Impact Analyzer: scripts/codegraph_impact.py

  • Untersucht AST und Querverweise in Python, JS/TS, Go, Rust, Java.
  • Berechnet die Risikostufe des Blast-Radius (Niedrig, Mittel, Hoch, Kritisch).
  • Identifiziert direkte Aufrufer und betroffene Testsuiten.

• Deterministischer statischer SRP- & Abstraktionsanalysator: scripts/static_srp_analyzer.py

  • Bewertet Code auf SRP-Längen-/Komplexitätsverletzungen.
  • Markiert Abstraktionsumgehungen (rohe SQL/HTTP-Aufrufe außerhalb von Repositories/Adaptern).
  • Gibt maschinenlesbares --json und deterministische Exit-Codes für CI/Old Coder-Verifizierung aus.

• VSA Architectural Boundary Checker: scripts/vsa_boundary_checker.py

  • Erzwingt Slice-Isolation, indem illegale Cross-Slice-Importe verhindert werden.
  • Konfigurierbar über .vsa-boundaries.json. Null-Abhängigkeiten, Repository-unabhängig (MIT).