inetgas/arch-compiler

Architektur-Compiler: Ein Architektur-Level-KI-Framework

Sprachen: English | 简体中文

Hinweis: Die englische Dokumentation ist die maßgebliche Quelle. Wenn Übersetzungen abweichen, folgen Sie der englischen Version.

ArchCompiler kompiliert Einschränkungen und NFAs in explizite, überprüfbare Architekturentscheidungen mit klaren Kompromissen und Kostenauswirkungen.

Es ist ein Architektur-Level-KI-Framework, das aus drei Teilen besteht: einem deterministischen Compiler, einer kuratierten Mustersammlung und Workflow-Skills für Agenten. Gemeinsam verwandeln sie Anforderungen in kompilierte Architektur, leiten Arbeit durch Genehmigungs- und erneute Genehmigungsprozesse, wenn sich Architekturentscheidungen ändern, und steuern die Implementierung gemäß einem expliziten Architekturvertrag.

Der Compiler selbst ist bewusst einfach: keine LLM-Inferenz, keine versteckten Standardwerte und keine Black-Box-Auswahllogik. Die Architekturintelligenz lebt in der Mustersammlung und in der Workflow-Disziplin, die von folgenden Komponenten getragen wird:

• using-arch-compiler
• compiling-architecture
• implementing-architecture

Tags: architecture-as-code, architecture-harness, agent-harness, deterministic-compiler, pattern-registry, nfr-enforcement, ai-governance

Kernphilosophie

• Muster sind die Wissensbasis. Die gesamte Architekturlogik lebt in den Musterdateien unter patterns/. Der Compiler ist bewusst einfach.
• Include-basierte Filterung. Muster deklarieren, welche Spezifikationsbedingungen sie über supports_constraints- und supports_nfr-Regeln unterstützen. Ein Muster wird ausgewählt, wenn alle seine Regeln auf die Spezifikation zutreffen.
• Schema zuerst. schemas/canonical-schema.yaml definiert den Spezifikationsvertrag; schemas/pattern-schema.yaml definiert den Mustervertrag. Beide sind die maßgebliche Quelle.

---

Schnellstart

Falls python auf Ihrem System nicht verfügbar ist, ersetzen Sie es in den folgenden Befehlen durch python3.

# Installieren Sie pipx, falls nötig (empfohlen für Python-CLI-Anwendungen)
brew install pipx

# Installieren Sie die CLI aus dem aktuellen Repository
pipx install .

# Kompilieren Sie ein reales Beispiel-Spezifikation (Ausgabe auf stdout)
archcompiler tests/fixtures/no-advisory-success.yaml

# Kompilieren und schreiben Sie Artefakte in ein Verzeichnis
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/

# Ausführlicher Modus – Inline-Musterkommentare + rejected-patterns-Datei
archcompiler tests/fixtures/no-advisory-success.yaml -v
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v

# UTC-Zeitstempel zu Ausgabedateinamen hinzufügen
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v -t

Entwicklungseinrichtung

# Erstellen und aktivieren Sie eine virtuelle Umgebung
python3 -m venv .venv
source .venv/bin/activate

# Installieren Sie Repo-Abhängigkeiten für die lokale Entwicklung
python -m pip install -r tools/requirements.txt
python -m pip install -e .

# Führen Sie den Compiler aus dem Quellbaum aus
python tools/archcompiler.py tests/fixtures/no-advisory-success.yaml

Führen Sie Entwicklungsbefehle aus dem Stammverzeichnis arch-compiler/ aus. Einige Tests rufen tools/archcompiler.py über einen cwd-relativen Pfad auf und schlagen fehl, wenn Sie sie aus einem übergeordneten Verzeichnis ausführen.

---

Installieren Sie die Agenten-Skills

Dieses Repository enthält auch installierbare Agenten-Skills.

Codex

Sagen Sie Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/inetgas/arch-compiler/refs/heads/main/.codex/INSTALL.md

Oder folgen Sie den nativen Installationsschritten direkt:

git clone https://github.com/inetgas/arch-compiler.git ~/.codex/arch-compiler
mkdir -p ~/.agents/skills
ln -s ~/.codex/arch-compiler/skills ~/.agents/skills/arch-compiler

Starten Sie Codex nach der Installation neu.

Wichtig: Die Skill-Dateien allein reichen nicht aus. Die Workflows hängen davon ab, dass das gesamte Repository in einem stabilen lokalen Pfad verfügbar ist, sodass Agenten auf den Compiler, die Mustersammlung, Schemas und Adapter zugreifen können, ohne das Repository erneut zu klonen oder auf /tmp/ angewiesen zu sein.

Oder installieren Sie die drei Skills direkt aus dem öffentlichen Repository:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo inetgas/arch-compiler \
  --path skills/using-arch-compiler skills/compiling-architecture skills/implementing-architecture

Hinweis zum Codex-Installer: Wenn Sie mehrere Skills aus diesem Repository installieren, übergeben Sie alle Skill-Pfade nach einem einzigen --path-Argument. Wiederholen Sie --path nicht; im aktuellen Installer wird nur der letzte wiederholte Wert behalten.

Überprüfen Sie nach der Installation, ob die drei Verzeichnisse existieren:

ls ~/.codex/skills | rg 'using-arch-compiler|compiling-architecture|implementing-architecture'

Skill-Einstiegspunkte

• skills/using-arch-compiler = Wählen Sie den richtigen Workflow und leiten Sie zurück zur Kompilierung, wenn sich die Architektur ändert
• skills/compiling-architecture = Kompilieren und finalisieren Sie die Architektur
• skills/implementing-architecture = Implementieren Sie eine genehmigte Architektur

Agenten-Workflow-Vorbereitung

Führen Sie vor anwendungsorientierten Architektur-Kompilierungs- oder Implementierungs-Workflows das gemeinsame Vorbereitungs-Hilfsprogramm aus. Dies gilt unabhängig davon, ob der Workflow von Codex, Claude Code oder einem anderen Agenten-Wrapper gesteuert wird.

# Wenn Sie das Paket als CLI installiert haben:
archcompiler-preflight --app-repo /pfad/zum/app-repo --mode compile

# Oder führen Sie das Hilfsprogramm direkt aus einem stabilen lokalen Repo-Pfad aus:
python3 ~/.codex/arch-compiler/tools/archcompiler_preflight.py --app-repo /pfad/zum/app-repo --mode compile
python3 ~/.claude/arch-compiler/tools/archcompiler_preflight.py --app-repo /pfad/zum/app-repo --mode compile

Verwenden Sie --mode implement, wenn der Workflow Code aus einem genehmigten docs/architecture/-Verzeichnis schreiben soll.

Claude Code

Claude Code verwendet keine native Codex-Skill-Erkennung, aber dieses Repository enthält kopierfertige Befehlsadapter in adapters/claude-code/commands/, einschließlich eines Router-Einstiegspunkts.

Halten Sie das gesamte Repository in einem stabilen lokalen Pfad wie ~/.claude/arch-compiler, damit Befehle konsistent den Compiler, Muster und Schemas über Sitzungen hinweg finden.

Verfügbare Befehlsadapter:

• using-arch-compiler.md
• compile-architecture.md
• implement-architecture.md

---

Spezifikationsformat

Die Eingabespezifikation ist eine YAML-Datei, die gegen schemas/canonical-schema.yaml validiert wird. Ein Beispiel:

# ─── BEISPIEL-SPEZIFIKATION ───
# Dies ist eine minimale Spezifikation, die die grundlegende Struktur zeigt.
# Sie werden nach und nach Felder hinzufügen, wenn Ihre Anforderungen klarer werden.
# Siehe test-specs/ für vollständigere Beispiele und Randfälle.
project:
  name: Mein Dienst
  domain: ecommerce
functional:
  summary: REST-API für Produktkatalog
constraints:
  cloud: azure
  language: python
  platform: api
nfr:
  availability:
    target: 0.999
  latency:
    p95Milliseconds: 100
    p99Milliseconds: 200
  security:
    auth: jwt

Alle nicht bereitgestellten Felder werden aus config/defaults.yaml übernommen und im Abschnitt assumptions der Ausgabe aufgezeichnet.

Um Muster explizit auszuschließen, die andernfalls ausgewählt würden (z. B. zu komplex für den Umfang), fügen Sie eine Liste disallowed-patterns auf oberster Ebene hinzu:

disallowed-patterns:
  - ops-low-cost-observability
  - ops-slo-error-budgets

Ausgeschlossene Muster erscheinen in rejected-patterns.yaml mit phase: phase_2_5_disallowed_patterns. Eine Warnung wird ausgegeben, wenn eine ID nicht in der Mustersammlung gefunden wird.

Siehe test-specs/ für eine umfassende Sammlung von Beispielspezifikationen, die Randfälle, Plattformkombinationen, Compliance-Anforderungen und mehr abdecken.

---

Compiler-Ausgabe

stdout

Der Compiler gibt immer die kompilierte Spezifikation auf stdout aus – die zusammengeführte Spezifikation mit allen angewendeten Standardwerten und Inline-Musterkommentaren (im ausführlichen Modus). Exit-Code 0 bei Erfolg, 1 bei Validierungsfehlern.

Mit -o geschriebene Dateien

Datei	Modus	Beschreibung
compiled-spec.yaml	immer	Vollständig zusammengeführte Spezifikation mit Annahmen; kann erneut als Eingabe verwendet werden
selected-patterns.yaml	immer	Ausgewählte Muster mit Übereinstimmungswerten und beachteten Regeln
rejected-patterns.yaml	nur -v	Abgelehnte Muster mit Grund und Filterphase
compiled-spec-<timestamp>.yaml	-t	Gleiche Dateien mit UTC-Zeitstempel-Anhang (z. B. compiled-spec-2026-03-17T19:36:31Z.yaml)

Inline-Kommentare im ausführlichen Modus

Mit -v kommentiert die kompilierte Spezifikation jedes Feld mit den Mustern, die es ausgelöst hat:

constraints:
  platform: api  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (13 weitere)
  cloud: aws     # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (13 weitere)
nfr:
  availability:
    target: 0.999  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (14 weitere)

Dadurch wird die Beziehung zwischen Ihren Spezifikationswerten und den ausgewählten Mustern sofort sichtbar.

---

Wie die Musterauswahl funktioniert

Phase	Was passiert
1. Parsen & Validieren	Spezifikation laden, Schema validieren, semantische Konsistenz prüfen
2. Standardwerte zusammenführen	Fehlende Felder aus config/defaults.yaml füllen; in assumptions aufzeichnen
2.5 Ausschlussfilter	Alle in disallowed-patterns aufgeführten Muster entfernen; bei unbekannten IDs warnen
3.1 Einschränkungsfilter	Muster behalten, deren supports_constraints-Regeln alle auf die Spezifikation zutreffen
3.2 NFR-Filter	Muster behalten, deren supports_nfr-Regeln alle auf die Spezifikation zutreffen
3.3 Konfliktauflösung	Konflikthafte Muster entfernen; Gewinner = höchster Übereinstimmungswert, dann niedrigste Kosten basierend auf Absicht
3.4 Konfigurationszusammenführung	Muster-defaultConfig in assumptions.patterns zusammenführen
3.5 Codierungsfilter	Codierungsmuster auf Ebene fallen lassen, es sei denn, --include-coding-patterns ist gesetzt
4. Kostenmachbarkeit	Gesamtkosten gegen cost.ceilings prüfen; Hinweiswarnungen ausgeben
5. Ausgabe	Kompilierte Spezifikation auf stdout ausgeben; Artefaktdateien schreiben, wenn -o angegeben ist

Codierungsmuster

Standardmäßig werden Muster vom Typ coding (GoF, DI, Teststrategien, Entwicklungs-Workflows) ausgeschlossen – im Zeitalter der KI-Codierungsagenten können diese bei Bedarf behandelt werden. Verwenden Sie --include-coding-patterns, um sie einzuschließen.

---

Progressive Verfeinerung

Der Compiler ist für iterative, inkrementelle Nutzung ausgelegt. Sie brauchen nicht von Anfang an eine vollständige Spezifikation – beginnen Sie minimal und fügen Sie nach und nach Einschränkungen hinzu, wenn Ihr Verständnis wächst.

Ein Beispiel-Workflow

Start minimal → kompilieren → Annahmen überprüfen → Einschränkungen hinzufügen → neu kompilieren → ...

Schritt 1: Beginnen Sie mit den Grundlagen

constraints:
  cloud: aws
  language: javascript
  platform: api
nfr:
  availability:
    target: 0.999

Führen Sie den Compiler aus. Der Abschnitt assumptions in der Ausgabe zeigt jeden angewendeten Standardwert – dies sind Entscheidungen, die der Compiler in Ihrem Namen getroffen hat. Überprüfen Sie sie, um zu verstehen, was der Compiler angenommen hat.

Schritt 2: Fügen Sie NFR-Einschränkungen hinzu, wenn Sie sie entdecken

nfr:
  availability:
    target: 0.999
  latency:           # ← fügen Sie dies hinzu, wenn Sie Ihr Latenzziel kennen
    p95Milliseconds: 50
    p99Milliseconds: 100

Jede neue Einschränkung schränkt die Musterauswahl ein. Einige Muster, die zuvor nicht abgelehnt wurden, werden jetzt möglicherweise abgelehnt – der Compiler erklärt den Grund über die Datei rejected-patterns.yaml (im Modus -v).

In einigen Fällen kann die Spezifikation selbst abgelehnt werden: Wenn ein hartes NFR-Ziel (z. B. eine sehr enge Latenz oder hohe Verfügbarkeitsanforderung) von keinem verfügbaren Muster erfüllt werden kann, beendet sich der Compiler mit Code 1 und erklärt, was fehlgeschlagen ist. Dies ist ein nützliches Signal – es bedeutet, dass Ihre Einschränkungen entweder widersprüchlich sind oder ein Muster erfordern, das in der Mustersammlung noch nicht existiert.

Schritt 3: Entscheiden Sie sich explizit für Funktionen

constraints:
  features:
    caching: true       # ← löst Cache-Aside und verwandte Muster aus

Feature-Flags leben unter constraints.features, nicht unter nfr. Sie repräsentieren optionale Fähigkeiten, keine Leistungsziele.

Wenn ein Muster erkannt wird, kann der Compiler warn_nfr-Hinweise ausgeben – Warnungen, dass ein ausgewähltes Muster angesichts Ihrer aktuellen NFR-Werte unterausgelastet ist. Zum Beispiel könnte die Aktivierung von Caching ohne einen Durchsatz-NFR Folgendes erzeugen:

⚠️  cache-aside: Spitzenlese-QPS beträgt 5 req/s (<10 req/s). Der Caching-Overhead
    (Infrastruktur, Invalidierung, Serialisierung) kann den Nutzen in diesem Maßstab überwiegen.

Dies ist die Art des Compilers, Ihnen mitzuteilen, dass das Muster ausgewählt, aber wahrscheinlich nicht vorteilhaft ist – eine Aufforderung, entweder genauere NFR-Daten anzugeben oder das Feature-Flag zu überdenken.

Schritt 4: Geben Sie Durchsatzdaten an, um warn_nfr-Hinweise aufzulösen

Wenn Sie nach der Aktivierung von Caching (oder anderen durchsatzempfindlichen Mustern) einen warn_nfr-Hinweis sehen, fügen Sie Ihre tatsächlichen Spitzen-QPS hinzu:

nfr:
  throughput:
    peak_query_per_second_read: 20    # ← Compiler bewertet Caching-Nutzen neu
    peak_query_per_second_write: 10

Mit realen Durchsatzzahlen kann der Compiler eine endgültige Entscheidung treffen – entweder verschwindet der Hinweis (Caching ist gerechtfertigt) oder er bleibt mit einer spezifischeren Begründung bestehen. Beides ist nützlicher als ein im Dunkeln ausgewähltes Muster.

Schritt 5: Geben Sie Kosten und Betriebsmodell explizit an, wenn es Ihnen wichtig ist

cost:
  intent:
    priority: optimize-tco   # Standard ist minimize-opex, eine andere Option ist minimize-capex
  ceilings:
    monthly_operational_usd: 500
    one_time_setup_usd: 1000
operating_model:
  ops_team_size: 2                    # Anzahl der dedizierten Betriebsingenieure
  single_resource_monthly_ops_usd: 10000  # Voll belastete monatliche Kosten pro Ingenieur
  on_call: true                       # Fügt einen 1.5× Multiplikator zu den Betriebsteamkosten hinzu
  deploy_freq: daily                  # Beeinflusst den Betriebsaufwand (täglich = 1.0×, wöchentlich = 0.8×, auf Abruf = 1.2×)
  amortization_months: 24             # Zeitraum, über den CapEx abgeschrieben wird