In fast jedem Projekt, das ich kenne, gibt es irgendwo ein Wiki mit Diagrammen von vor drei Jahren. Niemand traut ihnen, also liest sie niemand, also pflegt sie niemand.
Die Folgen sind immer dieselben. Wer ein Projekt nur selten anfasst, weiß nicht, was das Ziel ist, was entschieden wurde und warum. Also zögert er, Code anzufassen. Und wenn etwas schiefgeht, fehlt die Grundlage für ein sachliches Gespräch: War die Entscheidung damals falsch, oder haben sich nur die Rahmenbedingungen geändert?
Mit Coding Agents verschärft sich das, denn der Code ändert sich schneller als je zuvor. In Teil 1 habe ich gezeigt, warum ich meinen eigenen Harness sparc gebaut habe. In diesem Teil geht es darum, wie er die Dokumentation aktuell hält. Anfangen möchte ich mit einer Entscheidung, die keine 24 Stunden gehalten hat.
Eine Entscheidung, die sich selbst ersetzt hat
Architecture Decision Records (ADRs) halten fest, was mit welchem Wissen entschieden wurde. Die Grundlagen habe ich vor zwei Jahren in Architecture Decision Records beschrieben. In sparc gilt dazu eine strenge Regel: Der Inhalt eines entschiedenen ADRs ändert sich nicht mehr. Ein ADR, das nachträglich still „korrigiert“ wird, verliert genau die Information, die man braucht, wenn etwas schiefgeht.
Eine Regel nützt aber nur etwas, wenn jemand sie prüft. Meine erste Lösung dafür (ADR-0004) war ein Hash über den Inhalt jedes entschiedenen ADRs, gespeichert in einem eigenen Feld locked. Das funktionierte. Aber nach jeder Entscheidung musste jemand den Hash neu setzen, und das Feld gehört nicht zum Standardformat MADR.
Am nächsten Tag kam die naheliegende Erkenntnis: Git kennt jede Version eines ADRs bereits. Also wurde ADR-0004 durch ADR-0008 ersetzt, und zwar genau so, wie die Regel es verlangt. Das neue ADR hält auch fest, was die Entscheidung kostet:
Chosen option: "Compare with the first committed version that has a decided
status", because git already holds the data. The ADR files stay in the MADR format.
- Good, because there is no `--lock` step and no field outside MADR.
- Good, because the check also protects `decision-makers`, `consulted`,
`informed` and committed amendments.
- Bad, because a project without git loses the protection. The check reports this.
- Bad, because the protection starts only with the first commit of the decision.
ADR-0004 ist dabei nicht verschwunden. Es steht weiter im Repository, mit dem Status superseded by ADR-0008. Wer wissen will, warum es keinen Lock-Hash mehr gibt, findet die ganze Geschichte. Für mich ist das der beste Beweis, dass die Regel funktioniert: Sie hat ihre eigene erste Umsetzung sauber ersetzt.
Ergänzen oder ersetzen
Was passiert, wenn sich an einer Entscheidung etwas ändert? Der Agent stellt eine einzige Frage: Ändert die Anpassung den Kontext, die Optionen, die Entscheidung oder ihre Konsequenzen? Wenn ja, entsteht ein neues ADR, und das alte wird ersetzt. Wenn nein, ist es eine Ergänzung (Amendment), die ich ausdrücklich freigeben muss:
### 2026-10-22: Warn one time for the same findings
Approved by: [@sventropy](https://github.com/sventropy), chat
A live test showed that a warning makes the agent reply one more time.
The hook keeps the digest of the last findings for each project.
Mehr Statusmodell braucht es nicht: vorgeschlagen, angenommen oder abgelehnt, später ergänzt, verworfen oder ersetzt. Und nicht jede Entscheidung braucht ein ADR. Relevant ist sie, wenn sie später schwer zu ändern ist oder mehr als einen Teil des Systems betrifft.
Am wichtigsten ist mir dabei das „Bad, because“. Jede Entscheidung hat einen Preis. Wer ihn aufschreibt, schafft Akzeptanz, denn wenn später genau dieser Preis fällig wird, war er bekannt und bewusst in Kauf genommen.
Ein Zuhause pro Fakt
ADRs sind nur ein Teil der Dokumentation. Die Grundidee für den Rest ist simpel: Jeder Fakt steht an genau einem Ort. Alle anderen Dokumente verlinken ihn. Ein Fakt, der an zwei Stellen steht, widerspricht sich früher oder später selbst. Bei Agenten, die viel und schnell schreiben, eher früher.
Jedes sparc-Projekt hat deshalb denselben festen Dokumentensatz: README, AGENTS.md, Backlog, Changelog, Specs, C4-Diagramme, Canvas und ADRs. Jedes Dokument hat eine Rolle als Eigentümer, und es ist festgelegt, wofür es das Zuhause ist. Der Architekturabschnitt im README hat zum Beispiel höchstens drei Sätze und verlinkt auf Diagramme, Canvas und ADRs, statt sie zu wiederholen.
C4-Diagramme als Text
Für die Architekturübersicht nutzt sparc zwei Ebenen des C4-Modells: Systemkontext und Container. Die Diagramme sind Mermaid-Text im Repository, damit Agenten sie ändern können, Git die Unterschiede im Review zeigt und GitHub sie ohne Zusatzwerkzeug rendert:
C4Context
title System Context: sparc
Person(dev, "Developer", "Starts changes and approves them")
System(sparc, "sparc", "Claude Code plugin for spec-driven work with agents")
System_Ext(openspec, "OpenSpec CLI", "Manages specs and changes")
Rel(sparc, openspec, "Calls")
Der Preis steht im ADR: Mermaid C4 ist weniger vollständig als Structurizr, und die beiden Diagramme teilen kein gemeinsames Modell. Damit niemand das Diagramm vergisst, muss jedes Design einer Änderung seine „C4-Auswirkung“ benennen, oder ausdrücklich „No C4 impact“ schreiben.
Der Canvas: eine Seite fürs Gespräch
C4 zeigt die Struktur. Für Menschen, die keine Diagramme lesen wollen, nutzt sparc den Architecture Communication Canvas: Ziele, Stakeholder, Qualitätsanforderungen, Kernentscheidungen und Risiken auf einer Seite, auch fürs Management verständlich. Wie man Qualitätsanforderungen messbar formuliert, habe ich in Was macht Software gut? beschrieben.
Ein Abschnitt hat eine Sonderrolle: „Core Risks and Missing Information“. Hier landet alles, was ein Agent nicht belegen kann. Aus einer versteckten Halluzination wird so eine sichtbare Frage, und der Canvas zeigt jederzeit, was das Team noch nicht weiß.
Drift finden statt auf Disziplin hoffen
Ein fester Dokumentensatz hilft nichts, wenn niemand ihn pflegt. In sparc ist die Pflege deshalb Teil jedes Schritts: Wird eine Änderung vorgeschlagen, kommt sie ins Backlog. Wird sie abgeschlossen, werden Changelog, README, Canvas und ADRs nachgezogen.
Dazu kommt ein Skript ohne LLM und ohne Abhängigkeiten. Es prüft Pflichtabschnitte, Platzhalter, zu lange Sätze, Changelog und Version und die ADR-Regeln, und es liefert jedes Mal dasselbe Ergebnis. Ein Hook in Claude Code führt es aus, sobald ein Agent fertig ist. Auch dazu gibt es eine bewusste Entscheidung: Der Hook warnt, aber er blockiert nicht. Mitten in einer Aufgabe ist die Doku oft absichtlich noch nicht synchron, und ein blockierender Hook würde den Agenten in eine Schleife zwingen. Verbindlich wird der Check erst beim Abschluss einer Änderung.
Zum Mitnehmen: ein ADR auf einer Seite
Wenn du nur eine Sache aus diesem Beitrag mitnimmst, dann diese Struktur. Sie folgt MADR, ist auf das Nötigste gekürzt und funktioniert mit oder ohne Agent:
---
status: proposed
date: YYYY-MM-DD
---
# Short title of the problem and the solution
## Context and Problem Statement
2 or 3 sentences: the situation and the question.
## Considered Options
- Option 1
- Option 2
## Decision Outcome
Chosen option: "Option 1", because <reason>.
- Good, because <consequence>
- Bad, because <consequence>
## Amendments
<!-- Only approved additions. Never change the text above after the decision. -->
Die zwei Regeln dazu: Schreib immer mindestens ein „Bad, because“. Und ändere ein entschiedenes ADR nie, sondern ergänze oder ersetze es.
Fazit
Aktuelle Architekturdokumentation ist keine Frage der Disziplin, sondern der Struktur. Wenn jeder Fakt ein Zuhause hat, die Pflege Teil jedes Arbeitsschritts ist und ein deterministischer Check Drift sofort meldet, hält die Dokumentation mit dem Code Schritt, auch wenn ein Agent den Code schreibt.
Im dritten Teil (erscheint am 8. November 2026) geht es um den Workflow dahinter, und um eine Architektur, die auf dem Papier perfekt aussah und trotzdem wieder verschwunden ist.