Archon für Einsteiger: Git Worktree-Isolation + DAG-Workflow – die Ungewissheit beim KI-Programmieren zähmen

Einsteigerfreundlich | ca. 20 Minuten | Du lernst die Kernkonzepte von Archon (Worktree-Isolation, DAG-Knotentypen, YAML-Workflow-Syntax), das Installieren und Konfigurieren sowie drei typische Workflows in der Praxis

---

Projektvorstellung

Zuerst müssen wir eine Tatsache akzeptieren: Wenn du eine KI einen Bug fixen lässt, ändert sie vielleicht nebenbei Dinge, die du gar nicht anfassen wolltest; wenn du ihr sagst, sie soll eine Funktion hinzufügen, läuft beim zweiten Mal zwar wieder alles durch – aber sie redet sich wieder zurecht, ohne am Ziel zu bleiben; und wenn du ihr einen PR schreiben lässt, unterscheidet sich jedes Mal der Beschreibungsstil.

Das ist kein „Absichtlich Ärgern“ der KI, sondern: Der gesamte Prozess hat keine „Struktur“. Die KI bekommt eine vage Anweisung, und was am Ende herauskommt, hängt stark von Laune und Kontext des jeweiligen Modells ab.

Genau dabei setzt Archon an: Es bringt Struktur in das KI-Programmieren. Mit YAML definiert es deinen Entwicklungsprozess – Planung, Validierung, Code Review, PR-Erstellung: Was in jedem Schritt passiert, welche Abhängigkeiten existieren und wann ein Schritt als abgeschlossen gilt – alles wird klar festgehalten. Anschließend wird die KI in diesen Rahmen gesetzt: Sie kann sich innerhalb der Struktur entfalten, statt planlos umherzulaufen.

Eine weitere Kernfähigkeit ist Git Worktree-Isolation: Jeder Workflow läuft in einer isolierten git-Branch und einem separaten Arbeitsverzeichnis. Selbst wenn fünf Aufgaben parallel laufen, treten sie sich nicht gegenseitig in die Quere. Wenn eine Aufgabe fertig ist, wird ins Haupt-Branch gemerged; wenn sie scheitert, wird das Worktree einfach gelöscht – sauber und unkompliziert.

---

Zielgruppe

• Entwickler, die mit Claude Code oder Codex arbeiten
• Teams, die KI-Programmierungs-Workflows standardisieren möchten
• Nutzer, die sich wiederholbare und überprüfbare KI-Ausgaben wünschen

Zentrale Abhängigkeiten und Umgebung

• Bun
• Git
• Claude Code (CLI)
• GitHub CLI (notwendig bei vollständiger Installation)

Vollständiger Projekt-Strukturbaum

.archon/                     # Projektweit (vom Setup Wizard generiert)
├── commands/                # Eigene Befehle (Markdown-Dateien)
├── workflows/               # Eigene Workflows (YAML)
│   └── defaults/            # Integrierte Workflow-Templates
└── config.yaml              # Projekteinstellungen (assistant model etc.)

~/.archon/                   # Benutzerweite globale Konfiguration
├── workspaces/owner/repo/  # Isolierte Umgebungen nach GitHub-Nutzer/Repository
│   ├── source/             # Repo-Clone oder lokaler Pfad
│   ├── worktrees/          # Verzeichnis für Git Worktree-Isolation
│   └── artifacts/          # Workflow-Ergebnisse (nicht in git)
└── config.yaml             # Globale Konfiguration

---

Schritt für Schritt

Schritt 1: Archon installieren

Es gibt zwei Installationswege – wähle je nach Situation einen aus.

Variante 1: Vollständige Installation (empfohlen, 5 Minuten)

git clone https://github.com/coleam00/Archon
cd Archon
bun install
claude

Danach sag zu Claude Code: "Set up Archon". Es startet einen interaktiven Guide, der dir hilft, GitHub-Zugangsdaten zu konfigurieren, Plattform-Integrationen auszuwählen, die Verbindung zu testen und am Ende die Archon-Fähigkeitsdateien in dein Zielprojekt zu kopieren.

Variante 2: Schnelle Installation (30 Sekunden, bei vorhandenem Claude Code)

# macOS / Linux
curl -fsSL https://archon.diy/install | bash

# Windows (PowerShell)
irm https://archon.diy/install.ps1 | iex

# oder mit Homebrew
brew install coleam00/archon/archon

Die schnelle Installation installiert nur die CLI und konfiguriert nicht automatisch Zugangsdaten sowie Workflows im Projekt – die Initialisierung musst du manuell durchführen.

Schritt 2: Setup Wizard ausführen (für Nutzer der vollständigen Installation)

Wenn du die vollständige Installation verwendet hast, führt dich der Setup Wizard durch folgende Schritte:

1. CLI-Installation — installiere das archon-Binary in den PATH
2. GitHub-Authentifizierung — gh auth login, damit Archon Zugriff erhält, um auf dein Repository zuzugreifen
3. Plattform-Auswahl — ob Telegram / Slack / Discord angebunden werden sollen (optional)
4. Zielprojekt — wähle das Verzeichnis des Projekts, das du registrieren willst; der Wizard kopiert die .archon/-Skill-Dateien hinein

Nach Abschluss sind im Zielprojekt zusätzlich diese Dinge vorhanden:

.archon/
├── commands/       # Befehlsdateien, die die KI aufrufen kann
└── workflows/      # Workflow-Definitionen

Schritt 3: Zielprojekt initialisieren

Wenn du schnell installiert hast, musst du manuell initialisieren:

cd your-project
archon init
# oder in Claude Code sagen: "Use archon to set up"

Danach einmal verifizieren:

archon workflow list
# sollte 17 integrierte Workflows ausgeben

Schritt 4: YAML-Workflow-Struktur verstehen

Die Workflows von Archon sind ein DAG (gerichteter azyklischer Graph). Jeder Knoten ist ein Ausführungsschritt. Knoten deklarieren ihre Abhängigkeiten über depends_on. Archon führt dann in topologischer Reihenfolge aus: Knoten ohne Abhängigkeiten können parallel laufen.

Ein kompletter Workflow sieht so aus:

# .archon/workflows/my-feature.yaml
nodes:
  # Knoten 1: Planung (ohne Abhängigkeiten, direkt ausführen)
  - id: plan
    prompt: "Das Code-Repository erkunden und einen Umsetzungsplan erstellen"

  # Knoten 2: Implementierung (abhängig von plan)
  - id: implement
    depends_on: [plan]
    loop:                                    # KI-Loop-Knoten
      prompt: "Plane den nächsten Schritt: lies den Plan, setze die nächste Aufgabe um, führe Validierung aus"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # In jeder Schleife wird eine neue KI-Session verwendet

  # Knoten 3: Tests ausführen (abhängig von implement; bash-Knoten, rein deterministisch)
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # Knoten 4: Code Review (abhängig davon, dass Tests erfolgreich sind)
  - id: review
    depends_on: [run-tests]
    prompt: "Alle Änderungen überprüfen und Probleme anhand des Plans reparieren"

  # Knoten 5: Manuelle Freigabe (interaktives Gate)
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Zeige die Änderung an und reagiere auf Feedback"
      until: APPROVED
    interactive: true                        # Wartet auf manuelle Eingabe

  # Knoten 6: PR erstellen
  - id: create-pr
    depends_on: [approve]
    prompt: "Code pushen und Pull Request erstellen"

Übersicht der Knotentypen:

Schritt 5: Praxis – von GitHub Issue zu PR

Das ist einer der gängigsten Workflows: Du gibst ein GitHub Issue ein und erhältst am Ende einen PR.

Sag in Claude Code direkt:

Use archon to fix issue #42

Archon macht dann automatisch:

1. Einen isolierten Worktree-Branch erstellen (archon/fix-42-xxx)
2. Den Workflow archon-fix-github-issue ausführen: Issue kategorisieren → recherchieren → planen → implementieren → validieren → PR erstellen
3. Wenn Tests fehlschlagen, automatisch in den self-fix-Loop gehen
4. Danach im Worktree arbeiten – ohne deinen lokalen Haupt-Branch zu beeinflussen

So ungefähr siehst du den Ablauf:

→ Creating isolated worktree on branch archon/fix-42-abc...
→ Planning...
→ Investigating issue #42...
→ Implementing (task 1/3)...
→ Implementing (task 2/3)...
→ Tests failing - iterating...
→ Tests passing after 2 iterations
→ Code review complete - 0 issues
→ PR ready: https://github.com/you/project/pull/47

Schritt 6: Praxis – von einer Idee zu PR

Wenn du kein fertiges Issue hast, sondern nur eine Idee:

Use archon to add dark mode to the settings page

Archon verwendet den Workflow archon-idea-to-pr:

→ Feature-Idee → plan → implement → validate → PR → 5 parallele Reviews → self-fix

Dabei macht die KI:

1. Zuerst das Code-Repository erkunden und die aktuelle Architektur verstehen
2. Einen Umsetzungsplan festlegen (du kannst dazwischen eingreifen und ihn ändern)
3. Mit dem loop-Knoten wiederholt implementieren, bis alle Aufgaben abgeschlossen sind
4. Validierung ausführen (bun run validate)
5. Parallel 5 Code-Review-Agenten laufen lassen (Stil, Sicherheit, Performance, Wartbarkeit, Dokumentation)
6. Auf Basis des Review-Feedbacks self-fix
7. Einen PR erstellen und die vollständige Review-Zusammenfassung anhängen

Schritt 7: Eigene Workflows schreiben

Die integrierten Workflows sind ein guter Startpunkt – du kannst einfach eine Kopie erstellen und anpassen:

cp .archon/workflows/defaults/archon-feature-development.yaml \
   .archon/workflows/my-feature.yaml

Bearbeite dann die YAML-Datei. Beispielsweise kannst du das manuelle Approval-Gate entfernen und direkt zusammenführen:

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "Anforderungen analysieren und einen Umsetzungsplan erstellen"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Lies den Plan, setze die nächste Aufgabe um und markiere sie als abgeschlossen"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

  - id: run-tests
    depends_on: [implement]
    bash: "bun test"

  - id: create-pr
    depends_on: [run-tests]
    prompt: "Code pushen, Pull Request erstellen, mit der folgenden Vorlage: ..."

Variablen-Ersetzung: Workflows können diese eingebauten Variablen verwenden:

- id: log-context
  bash: "echo $WORKFLOW_ID $ARTIFACTS_DIR $BASE_BRANCH"

• $1, $2, $3 — Positionsparameter
• $ARGUMENTS — alle Parameter
• $ARTIFACTS_DIR — das Ausgabeverzeichnis des aktuellen Workflow-Runs
• $WORKFLOW_ID — Workflow-Run-ID
• $BASE_BRANCH — Name der Haupt-Branch
• $LOOP_USER_INPUT — Feedback, das manuell im approval gate eingegeben wurde

Schritt 8: Web UI + Anbindung mehrerer Plattformen

Archon ist nicht nur eine CLI: Es gibt auch ein vollständiges Web Dashboard. Schneller Start:

archon serve
# lädt das Web UI herunter (beim ersten Mal), dann unter http://localhost:4000 starten

Das Web UI bietet:

• Chat-Seite — in Echtzeit mit der KI sprechen, Streaming-Ausgabe und Tool-Aufrufe beobachten
• Dashboard — alle Workflows überwachen (Status) (von allen Plattformen: CLI, Slack, Telegram usw.)
• Workflow Builder — visueller DAG-Editor zum Drag-and-Drop-Erstellen von Workflows
• Workflow Execution — den Ausführungsprozess beliebiger Workflows Schritt für Schritt ansehen

Anbindung von Chat-Plattformen (optional):

Nach der Anbindung kannst du in Slack oder Telegram Workflows direkt auslösen und die Ergebnisse werden in denselben Chat in Echtzeit gepusht.

---

Häufige Probleme beheben

1. Claude Code findet den Archon-Befehl nicht

Das passiert typischerweise, wenn nach der schnellen Installation der setup wizard nicht ausgeführt wurde:

# Setup erneut ausführen
cd your-project
claude
# sag "Set up Archon" oder "Use archon to set up"

# oder Skill-Dateien manuell aktualisieren
archon update

2. Worktree-Erstellung fehlgeschlagen

Die häufigste Ursache ist mangelnder Speicherplatz oder ein Berechtigungsproblem:

# Speicherplatz prüfen
df -h

# Git-Version prüfen (Worktree wird ab 2.23+ unterstützt)
git --version

# alte Worktrees manuell bereinigen
archon isolation cleanup

3. Workflow-Liste ist leer

# prüfen, ob das Verzeichnis .archon/workflows/ existiert
ls .archon/workflows/

# Workflows manuell erkennen lassen
archon workflow list --verbose

Wenn auch die integrierten Workflows fehlen, prüfe die Archon-Version:

archon --version

4. YAML-Knotenabhängigkeit bildet eine Schleife

Wenn depends_on einen Zyklus bildet, meldet Archon einen Fehler:

Error: Circular dependency detected in workflow

Lösung: Überprüfe die YAML-Datei und stelle sicher, dass keine Knoten gegenseitig voneinander abhängen (ein Knoten mit depends_on zeigt entweder auf sich selbst oder auf einen nachgelagerten Knoten).

5. Interaktives Approval Gate reagiert im CLI nicht

Das Approval Gate benötigt manuelle Eingriffe. Im CLI pausiert der Workflow und wartet auf eine Eingabe:

Workflow paused: awaiting approval
Type /workflow approve <run-id> [comment] to approve
Type /workflow reject <run-id> <reason> to reject

Wenn du es im Web UI ausführt, werden Knoten mit interactive: true automatisch mit entsprechenden Freigabe-Buttons angezeigt.

6. PostgreSQL vs SQLite wechseln

Archon nutzt standardmäßig SQLite (keine Konfiguration nötig). Die Daten liegen unter ~/.archon/archon.db. Wenn du auf PostgreSQL umstellen willst:

# PostgreSQL starten (Docker)
docker-compose --profile with-db up -d postgres

# Connection-String in .env setzen
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# Archon neu starten
archon serve

---

Weiterführende Lektüre / Fortgeschrittene Richtung

Detaillierte Erklärung von 17 integrierten Workflows: Archon stellt eine vollständige Toolchain bereit – von täglicher Unterstützung (archon-assist) bis zu komplexen Reviews (archon-comprehensive-pr-review). Unter anderem bringt archon-refactor-safely Type-Check-Hooks mit, archon-architect macht Scans zur Architektur-Gesundheit und archon-ralph-dag unterstützt die iterative Umsetzung von PRDs.

Eigene Node-Typen: Zusätzlich zu den integrierten Nodes kannst du auch command: nutzen, um eine eigene Command-Datei aufzurufen (Markdown), mit script: TypeScript/Python-Skripte ausführen (unterstützt deps: für Dependency-Installation und timeout: zur Timeout-Steuerung), sowie approval: eigene manuelle Freigabe-Workflows definieren.

Entwicklung von Plattform-Adaptern: Die Adapter-Schicht von Archon (IPlatformAdapter) unterstützt das Anbinden beliebiger Chat-Plattformen. Sieh dir die Implementationen unter packages/adapters/src/ für Slack, Telegram und Discord an – so lassen sich auch Unternehmens-WeChat, Feishu und andere Plattformen im DACH-/China-Umfeld anbinden.

Archon im Detail analysieren: Der Kern besteht aus dem DAG-Execution-Engine in dem Paket @archon/workflows (dag-executor.ts) plus dem Orchestrator von @archon/core (Message-Routing und Session-Management). YAML-Workflows werden über loader.ts geparst und validiert, Knoten werden per depends_on zu einem Topologie-Graphen zusammengesetzt und dann in topologischer Reihenfolge ausgeführt.

Workflow-Standardisierung im Team: Lege .archon/workflows/ im Git ab; nach jedem Clone erhalten Teammitglieder automatisch dieselbe Workflow-Definition. In Kombination mit .archon/config.yaml, die Team-Coding-Standards injiziert, folgen alle Inhalte, die die KI generiert, den Vereinbarungen des Teams.