Ein agentenbasiertes System für arc42-Architekturdokumentation, das in verschiedenen Tools/IDEs genutzt werden kann (z. B. via APM oder in VS Code/GitHub Copilot) — zum Reviewen und Schreiben. Das System prüft arc42-Dokumente formal und inhaltlich gegen die arc42-Anforderungen und unterstützt beim Erstellen neuer Dokumentation — automatisiert, strukturiert und sektionsübergreifend.
Das Agentensystem besteht aus 24 spezialisierten Agenten in fünf Kategorien:
- 3 Review-Orchestratoren — steuern den Review-Ablauf
- 12 Sektions-Review-Agenten — prüfen jeweils eine arc42-Sektion
- 7 Konflikt-Agenten — analysieren sektionsübergreifende Widersprüche
- 2 Write-Agenten — erstellen arc42-Dokumentation interaktiv oder aus Code
Drei Skills stellen gemeinsam genutzte Querschnittsfunktionalität bereit:
arc42-review-format— Review-Modi, Befund-Templates und allgemeine Regeln, die von allen Review-Agenten referenziert werden.arc42-orchestrator-format— Gemeinsames Ausgabeformat für die drei Orchestrator-Agenten: Ampellogik, Übersichtstabellen, Konfliktkarte und konsolidierte Berichts-Templates.arc42-doc-layout— Struktur-Erkennung für verschiedene arc42-Dokumentationslayouts (Multi-Folder, Flat-Files, Single-File) und Delegations-Protokoll für Orchestratoren.
13 Skills stelllen Funktionalität für des Schreiben von Dokumentation bereit:
arc42-write-doc-layout— Verzeichnisstruktur und Dateikonventionen für das Schreiben von arc42-Dokumentationen.arc42-write-s01bisarc42-write-s12— 12 sektionsspezifische Write-Skills mit Anleitungen, Fragestellungen und Templates für jede arc42-Sektion.
| Modus | Orchestrator | Beschreibung |
|---|---|---|
| Vollständiges Review | arc42-review |
Prüft alle Sektionen und führt Konfliktanalyse durch |
| Branch-Review | arc42-review-branch |
Reviewt nur die geänderten Dateien eines Git-Branches |
| Nur Konfliktanalyse | arc42-review-conflict |
Führt nur die sektionsübergreifende Konsistenzprüfung durch |
Das System erkennt automatisch drei verschiedene Layouts einer arc42-Dokumentation — gesteuert durch den Skill arc42-doc-layout:
| Typ | Erkennungsmerkmal | Typisches Beispiel |
|---|---|---|
| Multi-Folder | Unterordner mit nummerierten Namen | 01-Einfuehrung-und-Ziele/, 02-Randbedingungen/ |
| Flat-Files | Nur .md-Dateien im Verzeichnis, nummeriert oder mit Schlüsselwörtern |
chap-01-Anforderungen.md, chap-02-Randbedingungen.md |
| Single-File | Eine (oder wenige) .md-Datei(en) mit allen Kapiteln als ##-Überschriften |
architecture.md, biking2-architecture.md |
Der Orchestrator erkennt den Typ automatisch, erstellt ein Sektion-zu-Datei-Mapping und übergibt jedem Sektions-Agenten die zugehörigen Dateipfade oder (bei Single-File) den extrahierten Inline-Content. Kein Sektions-Agent muss das Dokumentationslayout selbst kennen — das übernimmt der Skill.
Installiere die Pakete aus matthiasnissen/arc42agentic-packages:
apm install matthiasnissen/arc42agentic-packages/arc42agenticreview
apm install matthiasnissen/arc42agentic-packages/arc42agenticwriteAPM funktioniert in Terminal, Zed, Cursor, VS Code und anderen APM-kompatiblen Tools. Einstieg: APM Quick Start.
Voraussetzung: VS Code mit GitHub Copilot.
Die Agent-Dateien unter .agents/ werden von VS Code/Copilot nicht automatisch erkannt. In diesem Repository sind die Agenten daher bereits zusätzlich unter .github/agents/ enthalten.
Falls du nur .agents/ in ein anderes Repository übernimmst, kannst du .agents/ nach .github/agents/ verlinken (macOS/Linux, aus dem Repo-Root):
mkdir -p .github
ln -s .agents .github/agents
Wähle den jewiligen Agenten in GitHub Copilot aus. Verwende keine Delegation über @arc42-review da Copilot aktuell nur eine ebene der Delegation unterstützt, die Subagenten würden sonst sequentiell im gleichen Context ausgeführt.
Rufe in Copilot den Agenten arc42-review auf (z. B. über den Copilot-Chat). Er:
- Identifiziert alle vorhandenen Sektionen unter
arc-doc/ - Delegiert an die 12 Sektions-Agenten
- Startet die sektionsübergreifende Konfliktanalyse
- Erstellt einen konsolidierten Prüfbericht mit Ampel-Bewertung
Ein Reviewesultat befindet sich hier: FullReviewResultOpus46.md. Je nach verwendetem Modell unterscheiden sich die Resultate leicht.
Identifiziert alle vorhandenen Sektionen unter arc-doc/
Delegiert an die 12 Sektions-Agenten:
Starten der sektionsübergreifenden Konfliktanalyse
Rufe den Agenten arc42-review-branch auf. Er:
- Ermittelt geänderte Dateien via
git diff - Identifiziert betroffene arc42-Sektionen
- Delegiert nur an die zuständigen Sektions-Agenten im Delta-Modus
- Löst relevante Konfliktanalysen basierend auf den geänderten Sektionen aus
- Erstellt einen fokussierten Änderungs-Review-Bericht
Ein Reviewresultat des Branches Konflikt/ADR befindet sich hier: BranchReviewConflicADROpus46.md
Rufe den Agenten arc42-review-conflict auf. Er führt alle 7 Konfliktdimensionen durch und liefert eine Konfliktkarte der Dokumentation.
Ein Reviewresultat befindet sich hier: ConflictReviewResultOpus46.md
Neben dem Review bietet das System zwei Agenten zum Erstellen von arc42-Dokumentation:
Rufe den Agenten arc42-write auf. Er führt dich systematisch durch alle 12 arc42-Sektionen:
- Klärt Zielpfad und prüft auf bestehende Dokumentation
- Sammelt pro Sektion gezielt Informationen über Rückfragen
- Erstellt strukturierte Markdown-Dateien im arc42-Format
- Führt abschließend eine Konsistenzprüfung über alle Sektionen durch
Der Agent lädt für jede Sektion den passenden Write-Skill (arc42-write-s01 bis arc42-write-s12), der sektionsspezifische Fragen, Templates und Qualitätskriterien enthält.
Rufe den Agenten arc42-write-from-code auf. Er analysiert eine bestehende Codebase und leitet daraus eine arc42-Dokumentation ab:
- Scannt Projektstruktur, Build-System, Dependencies und APIs
- Analysiert Quellcode-Module, Konfiguration und Deployment
- Generiert Dokumentation mit Kennzeichnung (aus Code abgeleitet vs. Annahmen)
- Stellt gezielte Rückfragen für nicht aus dem Code ableitbare Informationen (Business-Ziele, Stakeholder, strategische Gründe)
Inhalte, die der User noch ergänzen muss, werden mit <!-- TODO: Bitte ergänzen --> markiert, aus dem Code abgeleitete Annahmen mit <!-- ABGELEITET: Aus Code erkannt, bitte verifizieren -->.
| Agent | Beschreibung | Link |
|---|---|---|
arc42-review |
Hauptorchestrator: Vollständiges Review aller Sektionen + Konfliktanalyse | arc42-review |
arc42-review-branch |
Branch-Review: Ermittelt geänderte Dateien per Git-Diff, delegiert gezielt im Delta-Modus | arc42-review-branch |
arc42-review-conflict |
Konfliktanalyse-Orchestrator: Koordiniert alle 7 Konfliktdimensionen | arc42-review-conflict |
Jeder Sektions-Agent prüft eine arc42-Sektion gegen die offiziellen Kriterien. Alle unterstützen den Vollständig-Modus (prüft alles) und den Delta-Modus (prüft nur Änderungen).
| Agent | Sektion | Prüfgegenstand | Link |
|---|---|---|---|
arc42-review-s01-introduction |
1 — Einführung und Ziele | Anforderungsüberblick, Qualitätsziele, Stakeholder | arc42-review-s01-introduction |
arc42-review-s02-constraints |
2 — Randbedingungen | Technische, organisatorische und politische Constraints, Konventionen | arc42-review-s02-constraints |
arc42-review-s03-context |
3 — Kontextabgrenzung | Fachlicher Kontext, technischer Kontext, externe Schnittstellen | arc42-review-s03-context |
arc42-review-s04-solution-strategy |
4 — Lösungsstrategie | Grundlegende Entscheidungen und Lösungsansätze | arc42-review-s04-solution-strategy |
arc42-review-s05-building-blocks |
5 — Bausteinsicht | Statische Zerlegung, Blackbox/Whitebox, Hierarchieebenen | arc42-review-s05-building-blocks |
arc42-review-s06-runtime |
6 — Laufzeitsicht | Laufzeitszenarien, Interaktionen zwischen Bausteinen | arc42-review-s06-runtime |
arc42-review-s07-deployment |
7 — Verteilungssicht | Technische Infrastruktur, Deployment, Software-Hardware-Mapping | arc42-review-s07-deployment |
arc42-review-s08-concepts |
8 — Querschnittliche Konzepte | Übergreifende Lösungsansätze, Muster, Domänenmodelle | arc42-review-s08-concepts |
arc42-review-s09-decisions |
9 — Architekturentscheidungen | ADRs, Entscheidungsdokumentation (Nygard-Format) | arc42-review-s09-decisions |
arc42-review-s10-quality |
10 — Qualitätsanforderungen | Qualitätsbaum, Qualitätsszenarien | arc42-review-s10-quality |
arc42-review-s11-risks |
11 — Risiken und technische Schulden | Risikoliste, technische Schulden, Maßnahmen | arc42-review-s11-risks |
arc42-review-s12-glossary |
12 — Glossar | Begriffsdefinitionen, Terminologie-Konsistenz | arc42-review-s12-glossary |
Die Konflikt-Agenten prüfen die sektionsübergreifende Konsistenz und decken Widersprüche zwischen zusammenhängenden Sektionen auf. Alle unterstützen Vollständig- und Delta-Modus.
| Agent | Dimension | Sektionen | Prüfgegenstand | Link |
|---|---|---|---|---|
arc42-review-conflict-quality-strategy |
Qualitätsstrang | S1 ↔ S4 ↔ S10 | Konsistenz von Qualitätszielen, Strategie und Qualitätsszenarien | arc42-review-conflict-quality-strategy |
arc42-review-conflict-strategy-decisions |
Strategie ↔ Entscheidungen | S4 ↔ S9 | Alignment und Redundanzen zwischen Strategie und ADRs | arc42-review-conflict-strategy-decisions |
arc42-review-conflict-constraints-compliance |
Constraint-Compliance | S2 ↔ S4/S8/S9 | Verletzung von Randbedingungen durch Strategie, Konzepte oder Entscheidungen | arc42-review-conflict-constraints-compliance |
arc42-review-conflict-context-building-blocks |
Kontext ↔ Bausteine | S3 ↔ S5 | Schnittstellen-Konsistenz zwischen Kontextdiagramm und Bausteinsicht | arc42-review-conflict-context-building-blocks |
arc42-review-conflict-views-consistency |
Sichten-Konsistenz | S5 ↔ S6 ↔ S7 | Baustein-Konsistenz über Baustein-, Laufzeit- und Verteilungssicht | arc42-review-conflict-views-consistency |
arc42-review-conflict-concepts-decisions |
Konzepte ↔ Entscheidungen | S8 ↔ S9 | Trennung und Konsistenz zwischen Konzepten und Entscheidungen | arc42-review-conflict-concepts-decisions |
arc42-review-conflict-risks-quality |
Risiken ↔ Qualität | S11 ↔ S1/S10 | Ob Risiken Qualitätsziele bedrohen und Gegenmaßnahmen existieren | arc42-review-conflict-risks-quality |
| Agent | Beschreibung | Link |
|---|---|---|
arc42-write |
Interaktive Erstellung einer arc42-Dokumentation im Dialog mit dem User | arc42-write |
arc42-write-from-code |
Generiert arc42-Dokumentation aus bestehender Codebase per Reverse-Engineering | arc42-write-from-code |
Vollständiges Review:
arc42-review
├── arc42-review-s01-introduction (Vollständig-Modus)
├── arc42-review-s02-constraints ...
├── ...
├── arc42-review-s12-glossary
| arc42-review-conflict
├── arc42-review-conflict-quality-strategy
├── arc42-review-conflict-strategy-decisions
├── arc42-review-conflict-constraints-compliance
├── arc42-review-conflict-context-building-blocks
├── arc42-review-conflict-views-consistency
├── arc42-review-conflict-concepts-decisions
└── arc42-review-conflict-risks-quality
Branch-Review:
arc42-review-branch
├── git diff → betroffene Sektionen ermitteln
├── arc42-review-s04-solution-strategy (Delta-Modus, nur Änderungen)
├── arc42-review-s09-decisions (Delta-Modus, nur Änderungen)
├── ...nur betroffene Agenten...
├── arc42-review-conflict-strategy-decisions (Delta-Modus)
└── ...nur relevante Konflikt-Agenten...
Interaktiv schreiben:
arc42-write
├── Zielpfad klären, Bestandsaufnahme
├── Pro Sektion: Write-Skill laden → Fragen → Entwurf → Feedback → Datei
└── Konsistenzprüfung über alle Sektionen
Aus Code generieren:
arc42-write-from-code
├── Codebase-Analyse (Struktur, Build, Dependencies, APIs, Deployment)
├── Pro Sektion: Write-Skill laden → aus Code ableiten → Rückfragen
└── Dokumentation mit TODO/ABGELEITET-Markern
Das Verzeichnis arc-doc/ enthält eine vollständige arc42-Architekturdokumentation des Schach-Programms DokChess als Referenzbeispiel. Die Dokumentation stammt von Stefan Zörner und ist unter dokchess.de im Detail beschrieben.
Die Dokumentation von Stefan wurde automatisch heruntergeladen und in Markdown überführt. Von mir wurden die dokumentierten Entscheidungen in das ADR Format von Michael Nygard überführt.
Die Struktur folgt dem arc42-Template mit 12 Sektionen:
arc-doc/
├── 00-Ueberblick/ Überblick
├── 01-Einfuehrung-und-Ziele/ Aufgabenstellung, Qualitätsziele, Stakeholder
├── 02-Randbedingungen/ Technisch, Organisatorisch, Konventionen
├── 03-Kontextabgrenzung/ Fachlicher und technischer Kontext
├── 04-Loesungsstrategie/ Aufbau, Spielstrategie, Anbindung
├── 05-Bausteinsicht/ Ebene 1 & 2, XBoard, Engine, Spielregeln
├── 06-Laufzeitsicht/ Zugermittlung
├── 07-Verteilungssicht/ Infrastruktur Windows
├── 08-Konzepte/ Domänenmodell, Validierung, Logging, Testbarkeit
├── 09-Entscheidungen/ Anbindung, Stellungsobjekte
├── 10-Qualitaetsanforderungen/ Qualitätsbaum, Qualitätsszenarien
├── 11-Risiken/ Frontend, Aufwand, Spielstärke
├── 12-Glossar/ Begriffe
└── images/ Diagramme und Abbildungen
Die Beispiel-Dokumentation steht unter der Lizenz CC BY-NC-SA 4.0 von Stefan Zörner / dokchess.de. Siehe arc-doc/LICENSE.md.
Das Repository enthält Branches, in denen gezielt Änderungen an der arc42-Dokumentation vorgenommen wurden. Diese dienen dazu, die Branch-Review-Funktionalität (arc42-review-branch) zu testen:
- Wechsle zu einem Test-Branch:
git checkout <branch-name> - Starte den Branch-Review:
arc42-review-branch - Der Agent erkennt automatisch die Änderungen gegenüber
mainund reviewt nur die betroffenen Dateien
So lässt sich das Delta-Review in der Praxis ausprobieren und überprüfen, ob die Agenten korrekt im Delta-Modus arbeiten.
Dieses Repository steht unter der CC BY-SA 4.0 Lizenz.
| Komponente | Pfad | Lizenz |
|---|---|---|
| arc42agentic | .agents/ |
CC BY-SA 4.0 |
| DokChess-Beispieldokumentation | arc-doc/ |
CC BY-NC-SA 4.0 von Stefan Zörner / dokchess.de |
arc42agentic/
├── README.md ← Diese Datei
├── LICENSE CC BY-SA 4.0
├── .agents/ 24 Agent-Definitionen (.agent.md) + 16 Skills
│ ├── arc42-review.agent.md
│ ├── arc42-review-branch.agent.md
│ ├── arc42-review-conflict.agent.md
│ ├── arc42-review-s01-introduction.agent.md
│ ├── ...
│ ├── arc42-review-s12-glossary.agent.md
│ ├── arc42-review-conflict-quality-strategy.agent.md
│ ├── ...
│ ├── arc42-review-conflict-risks-quality.agent.md
│ ├── arc42-write.agent.md
│ ├── arc42-write-from-code.agent.md
│ └── skills/
│ ├── arc42-doc-layout/ Struktur-Erkennung, Delegations-Protokoll
│ ├── arc42-review-format/ Befund-Formate, Review-Modi
│ ├── arc42-orchestrator-format/ Ampellogik, Ausgabe-Templates, Konfliktkarte
│ ├── arc42-write-doc-layout/ Verzeichnisstruktur beim Schreiben
│ └── arc42-write-s01..s12/ 12 sektionsspezifische Write-Skills
└── arc-doc/ Beispiel-Dokumentation (DokChess, CC BY-NC-SA 4.0)
├── LICENSE.md CC BY-NC-SA 4.0 Lizenz
├── 01-Einfuehrung-und-Ziele/
├── ...
├── 12-Glossar/
└── images/