Entscheidungsprotokolle für die KI-gestützte Softwareentwicklung

Entscheidungsdokumente sind die fehlende Speicherschicht in der KI-gestützten Softwareentwicklung. Sie erfassen nicht nur, was gebaut wurde, sondern auch warum – und diese Unterscheidung wird entscheidend, wenn KI-Tools Ihren Code schreiben.

Entscheidungsdokumente sind die fehlende Speicherschicht

KI-gesteuerte Programmierung verändert die Wirtschaftlichkeit der Softwareentwicklung, indem sie Code günstiger zu generieren, einfacher zu refaktorisieren und schneller zu verwerfen macht. Das ist nützlich. Es ist aber auch gefährlich, denn wenn Code einfacher zu produzieren wird, ist die knappe Ressource nicht mehr das Tippen – die knappe Ressource ist das Urteil.

Warum hat das Team PostgreSQL anstelle von DynamoDB gewählt? Warum erfordert das Produkt eine menschliche Prüfung, bevor KI-generierte E-Mails gesendet werden? Warum zeigt die Benutzeroberfläche Vorschläge in einer Seitenleiste an, statt sie direkt anzuwenden? Warum wurde ein einfacherer Ansatz vor sechs Monaten abgelehnt? Der Code mag zeigen, was existiert, aber er erklärt selten, warum es existiert.

Entscheidungsdokumente lösen dieses Problem, indem sie ein kurzes, versionskontrolliertes Dokument bereitstellen, das eine wichtige Entscheidung, den dahinterliegenden Kontext, die in Betracht gezogenen Alternativen und die vom Team akzeptierten Konsequenzen festhält. In einer KI-gestützten Codebasis werden diese Dokumente zu mehr als nur Dokumentation – sie werden zu einem dauerhaften Projektgedächtnis, das sowohl Menschen als auch KI-Coding-Agenten lesen können, bevor sie zukünftige Änderungen vornehmen. Die praktische Betriebsregel ist einfach: Halten Sie Entscheidungsdokumente als Markdown-Dateien im Repository vor, überprüfen Sie sie wie Code und lassen Sie zukünftige KI-Tools sie lesen, bevor sie Änderungen vorschlagen oder implementieren.

Was sind Entscheidungsdokumente?

Ein Entscheidungsdokument ist ein schriftlicher Nachweis einer bedeutungsvollen Entscheidung, strukturiert um vier grundlegende Fragen zu beantworten: Was haben wir entschieden? Warum haben wir es entschieden? Welche Alternativen haben wir in Betracht gezogen? Und welche Konsequenzen haben wir akzeptiert? Die häufigste Form ist das Architektur-Entscheidungsdokument (Architecture Decision Record), abgekürzt ADR. ADRs werden weit verbreitet verwendet, um technische Entscheidungen zu dokumentieren, und dasselbe Muster kann über die Architektur hinaus auf Produkt- und Designarbeit erweitert werden.

Für die KI-gesteuerte Programmierung sind drei Typen besonders nützlich:

Zusammen beschreiben ADRs, PDRs und DDRs nicht nur die Struktur des Systems, sondern auch die Absicht des Produkts und die Begründung hinter der Benutzererfahrung. Diese Kombination ist wichtig, weil KI-Agenten Code lesen können, aber Code allein nicht genug Kontext enthält, um gute Entscheidungen zu treffen. Entscheidungsdokumente geben KI-Systemen eine überprüfte, dauerhafte, von Menschen genehmigte Quelle für Projektabsichten.

Architektur-Entscheidungsdokumente (ADR)

Architektur-Entscheidungsdokumente erfassen technische und strukturelle Entscheidungen. Verwenden Sie ein ADR, wenn eine Entscheidung die Form des Systems betrifft – seine Grenzen, Abhängigkeiten, das Betriebsmodell oder die langfristige Wartbarkeit.

Beispiele für Entscheidungen, die als ADRs dokumentiert werden sollten, sind:

• Auswahl von PostgreSQL als primäre Datenbank
• Verwendung einer ereignisgesteuerten Architektur für die Hintergrundverarbeitung
• Beibehaltung der Anwendung als modularer Monolith
• Einführung einer Nachrichtenwarteschlange
• Wahl von REST anstelle von GraphQL
• Verwendung von Server-Side-Rendering für die Webanwendung
• Anforderung, dass alle Hintergrundjobs idempotent sein müssen
• Annahme eines spezifischen Authentifizierungs- und Autorisierungsmodells

Ein ADR ist kein vollständiges Architektur-Dokument – es ist bewusst klein und hält eine wichtige Entscheidung zu einem bestimmten Zeitpunkt fest. Ein gutes ADR verhindert architektonische Amnesie: Ohne es könnten zukünftige Mitwirkende dieselben Kompromisse neu entdecken, alte Debatten wieder eröffnen oder wichtige Einschränkungen versehentlich aufheben.

In der KI-gesteuerten Programmierung haben ADRs noch mehr Gewicht. KI-Tools sind oft gut in der lokalen Optimierung und können eine technisch plausible Änderung vorschlagen, die eine größere architektonische Einschränkung verletzt. Ein ADR gibt der KI eine klare Grenze: „So soll dieses System aufgebaut sein.“

Produkt-Entscheidungsdokumente (PDR)

Produkt-Entscheidungsdokumente erfassen Produktverhalten, Umfang und benutzerbezogene Absichten. Dies ist seltener als ADRs, aber oft genauso wertvoll – Produktentscheidungen sind häufig über Tickets, Roadmap-Tools, Chatverläufe, Meeting-Notizen und die Erinnerungen der Menschen verstreut, was sie für Menschen leicht zu vergessen und für KI-Tools fast unmöglich macht, sie zuverlässig abzuleiten.

Verwenden Sie ein PDR, wenn eine Entscheidung beeinflusst, was das Produkt tut, wen es bedient, was absichtlich außerhalb des Umfangs liegt oder wie eine benutzerseitige Funktion funktionieren sollte. Beispiele sind:

• KI-generierte Nachrichten müssen als Entwurf verbleiben, bis sie von einem Menschen überprüft wurden
• Nutzer des Free-Tiers können bis zu drei Projekte erstellen
• Gelöschte Arbeitsbereiche sind für 30 Tage wiederherstellbar
• Team-Abrechnung liegt außerhalb des Umfangs für Version 1
• Nutzer können ihre Daten exportieren, ohne den Support zu kontaktieren
• KI-Zusammenfassungen mit niedriger Zuverlässigkeit zeigen eine Warnung an, anstatt versteckt zu werden

Ein PDR ist besonders nützlich, wenn eine Produktentscheidung aus dem Code heraus willkürlich wirkt. Der Code könnte eine Begrenzung von drei Projekten für Free-Tier-Nutzer enthalten, und ohne ein PDR könnte ein KI-Tool diese Zahl als magische Konstante betrachten und vorschlagen, sie zu ändern. Mit einem PDR kann die KI sehen, dass die Begrenzung mit der Preisstrategie, den Onboarding-Kosten oder der Supportauslastung verbunden ist – und dass eine Änderung eine bewusste Produktentscheidung erfordert, nicht eine schnelle Bearbeitung.

Design-Entscheidungsdokumente (DDR)

Design-Entscheidungsdokumente erfassen Entscheidungen zur Benutzererfahrung, Interaktion, Visualisierung und Content-Designs. Verwenden Sie ein DDR, wenn eine Entscheidung beeinflusst, wie Nutzer mit dem Produkt interagieren, wie Informationen präsentiert werden oder wie ein Designprinzip in zukünftigen Arbeiten angewendet werden soll.

Beispiele für Designentscheidungen, die dokumentiert werden sollten, sind:

• Verwendung von Inline-Validierung anstelle von Validierung nur beim Absenden
• Platzierung von KI-Vorschlägen in einer Seitenleiste anstelle direkt im Editor
• Verwendung von progressiver Offenlegung für erweiterte Einstellungen
• Anforderung einer Bestätigung vor zerstörerischen Aktionen
• Verwendung von „Entwurf“ und „Veröffentlicht“ anstelle von „Inaktiv“ und „Aktiv“
• Primäre Aktionen auf Mobilbildschirmen sichtbar halten

Designabsichten gehen während der Implementierung leicht verloren. Ein Entwickler kann einen Fluss vereinfachen, oder ein KI-Agent kann eine Komponente generieren, die technisch funktioniert, aber das beabsichtigte Interaktionsmodell bricht. Zum Beispiel könnte ein DDR festhalten: „Wir zeigen KI-Schreibvorschläge neben dem Dokument, nicht darin, weil Nutzer den generierten Text mit ihrem eigenen Entwurf vergleichen müssen, bevor sie Änderungen akzeptieren.“ Dieses Dokument gibt zukünftigen Mitwirkenden ein Prinzip zur Erhaltung, nicht nur ein Layout zum Kopieren.

Warum Entscheidungsdokumente mit KI wichtiger sind

KI-Coding-Tools sind leistungsstark, aber sie sind oft zustandslos oder nur teilweise über die Projektgeschichte informiert. Sie können Dateien inspizieren, Muster ableiten und Änderungen generieren – aber sie wissen nicht automatisch, welche Entscheidungen absichtlich, welche zufällig und welche bereits diskutiert und gelöst wurden. Dies schafft mehrere spezifische Risiken.

KI kann geschlossene Debatten wieder eröffnen

Wenn das Team bereits entschieden hat, einen modularen Monolithen zu verwenden, kann ein KI-Agent immer noch vorschlagen, einen Dienst zu extrahieren, weil das isoliert sauber aussieht. Ohne ein ADR hat die KI keine dauerhafte Möglichkeit zu wissen, dass das Team diesen Weg bereits in Betracht gezogen und abgelehnt hat, und das Ergebnis ist verschwendete Arbeit oder eine subtile Regression der Systemkohärenz.

KI kann lokal optimieren und global schaden

Eine generierte Refaktorierung kann eine Datei sauberer machen, während sie Systemgrenzen verletzt. Eine UI-Änderung kann die Komplexität der Komponente reduzieren, während sie die beabsichtigte Benutzererfahrung schwächt. Eine Produktänderung kann die Implementierung vereinfachen, während sie Preis- oder Compliance-Voraussetzungen bricht. Entscheidungsdokumente geben der KI einen größeren Bezugsrahmen, bevor sie auf eng umfasste Signale reagiert.

KI kann Code bewahren, aber die Absicht verlieren

Ein Modell kann bestehende Muster in der Codebasis folgen, aber Muster sind nicht dasselbe wie Prinzipien. Manchmal ist bestehender Code ein Kompromiss. Manchmal ist er transient. Manchmal existiert er aufgrund einer externen Einschränkung, die in der Datei nicht sichtbar ist. Entscheidungsdokumente erklären den Unterschied zwischen „So funktioniert es“ und „So wurde es aus diesem Grund gebaut.“

KI kann plausible, aber falsche Begründungen generieren

KI kann Entscheidungsdokumente entwerfen, aber sie kann auch überzeugend klingende Erklärungen erfinden, die nicht mit der tatsächlichen Entscheidung übereinstimmen. Deshalb ist menschliche Überprüfung unverzichtbar: KI kann den ersten Entwurf eines Dokuments generieren, aber ein Mensch muss überprüfen, ob es die tatsächliche Entscheidung, Alternativen und Konsequenzen genau beschreibt, bevor das Dokument gemerged wird.

Entscheidungsdokumente als Teil einer breiteren Methodik

Entscheidungsdokumente sind nicht nur Dokumentation – sie sind Teil einer breiteren Arbeitsweise, die an der Schnittstelle von leichtgewichtiger Architektur-Governance, Docs as Code, KI-augmentierten Wissensmanagement-Workflows, Produktentdeckung, Design-Begründung, KI-Governance und Code-Review liegt. Eine nützliche Möglichkeit, den größeren Prozess zu beschreiben, ist Entscheidungsorientierte Entwicklung (Decision-Oriented Development).

Die meisten KI-gesteuerten Programmierungs-Workflows konzentrieren sich eng auf den Generieren-Überprüfen-Commit-Loop:

Dieser Zyklus ist zu dünn für ernsthafte Systemarbeit. Ein stärkerer Workflow behandelt das Repository als Speicher für Code und Absicht – die Diagramme hier verwenden Mermaid, ein leichtgewichtiges Format, das auch gut innerhalb von Markdown-Entscheidungsdokumenten funktioniert:

Dieser Prozess verwandelt das Repository in mehr als nur einen Code-Speicher. Es wird zur Single Source of Truth für Implementierung, Absicht und Begründung – ein dauerhafter Artefakt, der mit jeder getroffenen Entscheidung an Wert gewinnt.

Entscheidungsdokumente und Docs as Code

Entscheidungsdokumente funktionieren am besten, wenn sie den Prinzipien von Docs as Code folgen, was bedeutet, dass sie im selben Repository wie der Code gespeichert, in reinem Markdown geschrieben, in Pull Requests überprüft, mit Git versioniert, mit verwandten Issues und Pull Requests verknüpft und sowohl für Menschen als auch für KI-Tools durchsuchbar sein sollten. Dies ist viel zuverlässiger als das Speichern wichtiger Entscheidungen in Chats, Wiki-Seiten, Präsentationen oder Meeting-Notizen – diese Tools können für Diskussionen immer noch nützlich sein, aber die akzeptierte Entscheidung sollte immer nah am Code leben. Specs, Tests und Code in der KI-Entwicklung synchron halten erweitert diese Gewohnheit, „es zurück zum Dokument zu verlinken“, zu einem vollständigen Nachverfolgungsmodell, das Anforderungs- und Design-Entscheidungs-IDs mit Tests und Pull Requests verknüpft.

Eine gut organisierte Repository-Struktur für Entscheidungsdokumente könnte so aussehen:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Für kleinere Projekte funktioniert eine flachere Struktur genauso gut. Die genaue Ordnerorganisation ist weniger wichtig als die Konsistenz – die Dokumente müssen leicht zu finden, leicht zu überprüfen und leicht für KI-Tools als Kontext zu laden sein, bevor sie auf der Codebasis handeln. Für Go-Teams passt diese docs/decisions/-Struktur natürlich neben das cmd/, internal/ und api/-Layout, das in Go Projektstruktur: Praktiken & Muster beschrieben wird, welches docs/ als Zuhause für Architektur-Entscheidungen und API-Referenzen empfiehlt.

Ein praktisches Template für Entscheidungsdokumente

Ein nützliches Template für Entscheidungsdokumente sollte kurz genug sein, dass es Menschen tatsächlich verwenden. Hier ist ein praktisches Markdown-Template, das einen optionalen, aber wertvollen Abschnitt für KI-Anleitungen enthält:

# Entscheidung: Kurzer Titel

Status: Vorgeschlagen | Akzeptiert | Abgelöst | Veraltet
Datum: JJJJ-MM-TT
Typ: Architektur | Produkt | Design
Verantwortliche: Team oder Namen

## Kontext

Beschreiben Sie das Problem, die Einschränkungen, Ziele, Benutzerbedürfnisse, technische Fakten
und geschäftliche Faktoren, die zu dieser Entscheidung geführt haben.

## Entscheidung

Stellen Sie die Entscheidung klar dar.

## In Betracht gezogene Alternativen

### Option 1

Vorteile:
- ...

Nachteile:
- ...

## Konsequenzen

Beschreiben Sie, was einfacher wird, was schwieriger wird und welche Risiken
oder Folgearbeiten dies erzeugt.

## KI-Anleitung

Wenn ein KI-Assistent in diesem Bereich arbeitet, sollte er:
- Bewahren Sie ...
- Vermeiden Sie ...
- Bevorzugen Sie ...
- Bitten Sie um Überprüfung, wenn ...

## Links

- Verwandte Issues:
- Verwandte Pull Requests:
- Verwandte Dateien:
- Löst ab:
- Abgelest durch:

Der Abschnitt „KI-Anleitung“ ist optional, aber für die KI-gesteuerte Programmierung extrem wertvoll – er verwandelt das Entscheidungsdokument in eine dauerhafte Anweisung für zukünftige Agenten, die im selben Bereich der Codebasis arbeiten.

Was gehört in ein Entscheidungsdokument?

Nicht jede Wahl verdient ein Dokument, und wenn jeder kleine Implementierungsdetail zu einem Entscheidungsdokument wird, kollabiert der Prozess im Lärm. Erstellen Sie ein Entscheidungsdokument, wenn eine Wahl bedeutungsvoll ist und später wahrscheinlich von Bedeutung sein wird.

Gute Kandidaten sind Entscheidungen, die:

• Mehrere Teile des Systems beeinflussen
• Ein Produktversprechen kodieren
• Eine echte Debatte lösen
• Einen langfristigen Kompromintroduce
• Von geschäftlichen, Compliance- oder operativen Einschränkungen abhängen
• Später teuer neu zu entdecken wären
• Zukünftige KI-Tools plausibel falsch interpretieren könnten
• Zukünftige Mitwirkende versucht sein könnten, leichtfertig umzukehren

Schlechte Kandidaten sind kleine Refaktorisierungsentscheidungen, offensichtliche Bugfixes, temporäre Experimente, lokale Namensentscheidungen und Implementierungsdetails ohne bleibende Konsequenzen. Eine gute Daumenregel ist einfach: Wenn das Umkehren der Entscheidung eine Diskussion erfordern würde, dokumentieren Sie die Entscheidung.

Statuswerte und Lebenszyklus

Entscheidungsdokumente sollten einen Lebenszyklus haben, um ihren aktuellen Stand zu signalisieren. Die einfachsten Statuswerte sind ausreichend.

Vorgeschlagen — Die Entscheidung wird erwogen, aber noch nicht akzeptiert. Verwenden Sie dies, wenn das Team eine Entscheidung in einem Pull Request diskutieren möchte, bevor es sich dafür entscheidet.

Akzeptiert — Die Entscheidung ist aktiv und sollte zukünftige Arbeit leiten. Die meisten nützlichen Entscheidungsdokumente werden den größten Teil ihres Lebens in diesem Zustand verbringen.

Abgelöst — Die Entscheidung wurde durch ein neueres Dokument ersetzt. Löschen Sie alte Dokumente nicht; behalten Sie sie für die Historie und verlinken Sie sie mit der neueren Entscheidung, damit die Entwicklung des Denkens sichtbar bleibt.

Veraltet — Die Entscheidung wird nicht mehr empfohlen, kann aber immer noch bestehende Teile des Systems beschreiben. Dies ist insbesondere während Migrationen nützlich, wenn alte Muster im Codebestand neben neueren Ansätzen existieren.

Das wichtige Prinzip ist, dass Entscheidungsdokumente anhängbar sein sollten. Wenn das Team die Richtung ändert, erstellen Sie ein neues Dokument und verlinken Sie das alte, anstatt die Geschichte neu zu schreiben, um die Vergangenheit sauberer aussehen zu lassen.

Wie KI Entscheidungsdokumente generieren sollte

KI kann bei der Erstellung von Entscheidungsdokumenten helfen, und dies ist eine der besseren Verwendungen von KI in der Softwareentwicklung – sie ist schnell beim Entwerfen strukturierter Dokumente aus Kontext. Nach einer Diskussion, Architektur-Review oder einem Pull Request können Sie einen KI-Assistenten bitten, ein Dokument zu entwerfen:

Entwerfen Sie ein Architektur-Entscheidungsdokument für die Entscheidung in diesem Pull Request.
Schließen Sie Kontext, Alternativen, Konsequenzen und KI-Anleitung ein.
Speichern Sie es als Markdown unter docs/decisions/architecture.

Für Produktarbeit:

Entwerfen Sie ein Produkt-Entscheidungsdokument, das erklärt, warum KI-generierte Nachrichten
als Entwurf verbleiben müssen, bis sie vom Benutzer überprüft wurden.
Schließen Sie Benutzerwirkung, außerhalb des Umfangs liegendes Verhalten, Kompromisse und KI-Anleitung ein.

Das KI-generierte Dokument sollte jedoch nicht automatisch vertraut werden. Die menschliche Überprüfung sollte sicherstellen, dass der Kontext korrekt ist, dass die KI keine Begründung erfunden hat, dass die aufgelisteten Alternativen real sind, dass die Konsequenzen ehrlich sind und dass die KI-Anleitung der tatsächlichen Absicht des Teams entspricht. KI ist ein Entwurfsassistent – sie ist nicht der Eigentümer der Entscheidung.

Wie KI Entscheidungsdokumente lesen sollte

Die andere Hälfte der Praxis besteht darin, die KI anzuweisen, die Dokumente zu lesen, bevor sie handelt. Bevor Sie einen KI-Assistenten bitten, eine Änderung zu implementieren, schließen Sie eine Anweisung wie diese ein:

Bevor Sie diese Funktion ändern, lesen Sie docs/decisions.
Identifizieren Sie alle Architektur-, Produkt- oder Design-Entscheidungsdokumente, die zutreffen.
Folgen Sie akzeptierten Entscheidungen. Wenn Ihr vorgeschlagener Änderung mit einem
Entscheidungsdokument in Konflikt steht, erklären Sie den Konflikt, bevor Sie Code ändern.

Für größere Aufgaben verstärken Sie die Rolle der Dokumente als Projektgedächtnis:

Verwenden Sie die Entscheidungsdokumente als Projektgedächtnis.
Kehren Sie akzeptierte Entscheidungen nicht um, ohne eine neue ablösende Entscheidung vorzuschlagen.
Wenn Sie Code generieren, erklären Sie, welche Entscheidungsdokumente die Implementierung beeinflusst haben.

Dies ändert die Rolle der KI von „plausiblen Code vorhersagen“ zu „innerhalb eines dokumentierten Systems von Einschränkungen operieren“ – eine signifikante Verbesserung der Zuverlässigkeit für komplexe oder langlebige Projekte.

Entscheidungsdokumente in Pull Requests

Entscheidungsdokumente sollten Teil der normalen Pull Request-Überprüfung sein, anstatt ein separater Prozess. Ein einfacher Eintrag in der PR-Checkliste macht die Gewohnheit sichtbar:

## Entscheidungsdokument-Checkliste

- [ ] Diese PR führt keine signifikante Architektur-, Produkt- oder Designentscheidung ein.
- [ ] Diese PR führt eine signifikante Entscheidung ein und enthält ein neues Entscheidungsdokument.
- [ ] Diese PR ändert eine frühere Entscheidung und enthält ein ablösendes Dokument.
- [ ] Relevante bestehende Entscheidungsdokumente wurden berücksichtigt.
- [ ] KI-generierter Code folgt den akzeptierten Entscheidungsdokumenten.
- [ ] KI-generierte Entscheidungsdokumente wurden von einem Menschen überprüft.

Diese Checkliste ist einfach, aber sie ändert das Verhalten, indem sie das Team daran erinnert, dass Code nicht der einzige Artefakt ist, der in einem Pull Request wichtig ist. Sie macht es auch natürlich, zu erkennen, wann eine KI-generierte Änderung stillschweigend gegen eine frühere Entscheidung verstößt.

Entscheidungsdokumente und Architektur-Governance

Traditionelle Architektur-Governance scheitert oft, weil sie zu schwerfällig, zu langsam oder zu sehr von der Implementierung getrennt ist – zentrale Genehmigungsboards, große vorbereitende Dokumente und Gatekeeping-Prozesse, die blockieren statt leiten. Entscheidungsdokumente bieten eine leichtere Alternative, die direkt in den Entwicklungsworkflow integriert wird.

Sie erfordern kein zentrales Architektur-Board für jede Änderung, noch blockieren sie Teams dabei, zu lernen und sich anzupassen. Stattdessen schaffen sie eine Spur von Entscheidungen, die im Laufe der Zeit überprüft, referenziert und darauf aufgebaut werden können. Dies unterstützt evolutionäre Architektur: Die Architektur kann sich ändern, aber sie ändert sich mit Gedächtnis, nicht trotz ihm. Das Team kann alte Entscheidungen überprüfen, ohne neu entdecken zu müssen, warum sie getroffen wurden, was eine gesündere und ehrlichere Form der Governance ist:

• Kleine Dokumente statt riesiger Dokumente
• Überprüfung nah am Code statt separater Genehmigungstheater
• Historischer Kontext statt Stammwissen
• Explizite Kompromisse statt versteckter Annahmen

Entscheidungsdokumente und Produktmanagement

Produktarbeit benötigt ebenfalls Entscheidungsgedächtnis, und dies ist ein Bereich, in dem der Wert von Entscheidungsdokumenten oft unterschätzt wird. Eine Roadmap sagt, was passieren könnte. Ein Ticket sagt, was als nächstes gebaut werden soll. Analysen sagen, was Nutzer getan haben. Keines davon erklärt vollständig, warum ein Produktverhalten existiert.

Produkt-Entscheidungsdokumente füllen diese Lücke und sind besonders nützlich für Preis- und Verpackungsentscheidungen, Berechtigungsmodelle, Limits und Quoten, KI-Sicherheit und Review-Flows, Onboarding-Entscheidungen, Benutzerrollendefinitionen, Kollaborationsregeln, Datenretentionsrichtlinien und Funktionsumfangsgrenzen. Sobald implementiert, werden Produktentscheidungen im Code unsichtbar – später sieht jemand nur den Code und fragt: „Warum funktioniert es so?“ Ein PDR gibt die Antwort in einer Form, die sowohl Menschen als auch KI-Tools finden und verwenden können.

Entscheidungsdokumente und Design-Systeme

Design-Systeme dokumentieren oft Komponenten, Tokens und Nutzungsregeln, aber sie dokumentieren selten, warum das System so funktioniert. Design-Entscheidungsdokumente füllen diese Lücke. Eine Komponentenbibliothek könnte sagen: „Verwenden Sie den Bestätigungsdialog für zerstörerische Aktionen“, während ein DDR die Begründung erklärt: „Wir erfordern Bestätigung für zerstörerische Aktionen, weil Nutzer oft mit gemeinsamen Teamdaten arbeiten, und versehentliches Löschen hohe Wiederherstellungskosten hat.“

Diese Begründung ist über die spezifische Komponente hinaus wichtig. Sie hilft zukünftigen Designern, Entwicklern und KI-Tools, das Prinzip korrekt in neuen Situationen anzuwenden. Ohne das DDR könnte ein KI-Agent eine schnellere Interaktion generieren, die die Bestätigung überspringt, weil sie effizienter erscheint. Mit dem DDR kann der Agent erkennen, dass die Erhaltung der Sicherheitseigenschaft absichtlich und nicht verhandelbar ist.

Wie Entscheidungsdokumente spec-getriebene Entwicklung unterstützen

Spec-getriebene Entwicklung erklärt, was das System tun soll. Entscheidungsdokumente erklären, warum das Team diese Richtung gewählt hat, und die Unterscheidung ist für KI-gestützte Arbeit von großer Bedeutung.

Eine Feature-Spezifikation kann sagen, dass KI-generierte E-Mails als Entwurf gespeichert werden müssen. Ein Produkt-Entscheidungsdokument erklärt, warum automatisches Senden abgelehnt wurde, welche Risiken in Betracht gezogen wurden und welche zukünftigen Änderungen eine neue Entscheidung erfordern würden. Eine Design-Spezifikation kann eine Seitenleisten-Interaktion beschreiben, während das entsprechende DDR erklärt, warum Inline-KI-Redaktionen explizit abgelehnt wurden und warum die Erhaltung der Benutzerkontrolle schwerer gewogen wurde als die Workflow-Geschwindigkeit. Eine Architektur-Spezifikation kann eine Dienstgrenze definieren, und ihr ADR erklärt, warum das Team diese Grenze gegenüber einer einfacheren oder verteilten Alternative gewählt hat.

Die Spezifikation leitet die Implementierung. Das Entscheidungsdokument bewahrt das Urteil. Zusammen geben sie KI-Coding-Agenten sowohl Anweisungen als auch Kontext – das „Was“ und das „Warum“ – was die Kombination so effektiv für komplexe, langlebige Systeme macht. Wenn Sie eine spec-getriebene Toolchain adoptieren, vergleichen Sie, wie jede Option diesen Kontext darstellt; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows durchbricht Portabilität, Review-Gates und Repository-Grundlage über die Hauptsetups. Für den tool-neutralen Fünf-Phasen-Prozess, den diese Tools implementieren, siehe Spec-Driven Development Workflow Von Anforderungen zu Code.

Entscheidungsdokumente sind keine Spezifikationen

Entscheidungsdokumente sind mit Spezifikationen verwandt, dienen aber einem anderen Zweck. Eine Spezifikation sagt „Das System soll X tun“, während ein Entscheidungsdokument sagt „Wir haben X anstelle von Y gewählt, aufgrund dieser Einschränkungen und Kompromisse.“ Dieses „anstelle von Y“ ist der wertvolle Teil. KI-Tools generieren oft Lösungen, indem sie einen plausiblen Weg zum angeforderten Ergebnis finden, aber Entscheidungsdokumente sagen ihnen, welche plausiblen Wege bereits erkundet, bewertet und abgelehnt wurden – was Churn reduziert und die Qualität der KI-gestützten Arbeit verbessert.

Entscheidungsdokumente sind kein Ersatz für Tests

Tests verifizieren Verhalten; Entscheidungsdokumente erklären Absicht. Beide sind notwendig und sie arbeiten zusammen. Ein Test kann durchsetzen, dass KI-generierte E-Mails als Entwurf gespeichert werden müssen, während ein Produkt-Entscheidungsdokument erklärt, dass dies erforderlich ist, weil Nutzer KI-generierte Kommunikation überprüfen müssen, bevor sie das System verlässt. Der Test schützt das Verhalten. Das Entscheidungsdokument schützt die Bedeutung. Zusammen machen sie zukünftige Änderungen sicherer und vorhersehbarer.

Entscheidungsdokumente sind kein Ersatz für Code-Kommentare

Code-Kommentare erklären lokale Implementierungsdetails, während Entscheidungsdokumente breitere Entscheidungen erklären. Verwenden Sie Kommentare für überraschende Zeilen, Randfälle, Workarounds und Funktionen, die nicht vereinfacht werden können. Verwenden Sie Entscheidungsdokumente dafür, warum eine Architektur existiert, warum ein Produktverhalten existiert, warum ein Interaktionsmuster existiert und warum das Team eine Richtung gegenüber einer anderen gewählt hat. Wenn die Erklärung nur wenige Zeilen betrifft, ist ein Kommentar das richtige Werkzeug. Wenn sie die Richtung des Systems betrifft, ist ein Entscheidungsdokument das richtige Werkzeug.

Häufige Fehler

Dokumente zu spät schreiben

Ein Entscheidungsdokument sollte geschrieben werden, wenn die Entscheidung getroffen wird, nicht Monate später, wenn alle die Kompromisse vergessen haben. Es ist in Ordnung, einen Entwurf während eines Pull Requests zu erstellen. Es ist sogar besser, ihn vor der Implementierung zu entwerfen, während die Entscheidung noch aktiv diskutiert wird und die Alternativen frisch sind.

Dokumente zu lang machen

Ein Entscheidungsdokument ist kein Essay. Es sollte detailliert genug sein, um Urteil zu bewahren, aber kurz genug, dass Menschen es tatsächlich lesen werden. Bevorzugen Sie Klarheit gegenüber Vollständigkeit – ein prägnantes Dokument, das gelesen wird, ist viel wertvoller als ein umfassendes, das übersprungen wird.

Entscheidungen ohne Konsequenzen dokumentieren

Der Abschnitt Konsequenzen ist das Herz des Dokuments. Eine Entscheidung ohne statede Konsequenzen ist oft nur eine Präferenz, keine echte Entscheidung. Gute Dokumente geben Kompromisse ehrlich zu, einschließlich dessen, was schwieriger oder riskanter wird als Ergebnis der Wahl.

Alte Dokumente bearbeiten, als ob sich die Geschichte geändert hätte

Wenn sich eine Entscheidung ändert, erstellen Sie ein neues Dokument und markieren Sie das alte als abgelöst. Stilles Umschreiben einer alten Entscheidung, um sie dem aktuellen Zustand anzupassen, zerstört den historischen Kontext, der Entscheidungsdokumente wertvoll macht. Geschichte ist nützlich, genau weil sie zeigt, wie sich das Denken entwickelt hat. Kompilierte Wissensdatenbanken haben dasselbe Problem unter einem anderen Namen – LLM Wiki Wartung: Drift, Widersprüche und Überprüfung nennt es Entscheidungsdrift und wendet dieselbe Regel der Ablösung statt Überschreibung auf Wiki-Seiten an.

KI-generierte Dokumente ohne Überprüfung mergen lassen

KI kann ein poliertes, gut strukturiertes Dokument produzieren, das subtil falsch ist. Behandeln Sie KI-generierte Entscheidungsdokumente genau wie KI-generierten Code – überprüfen Sie sie sorgfältig, verifizieren Sie, dass die Begründung korrekt ist, und stellen Sie sicher, dass der Abschnitt Konsequenzen widerspiegelt, was das Team tatsächlich akzeptiert hat.

Dokumente außerhalb des Repositorys verstecken

Wenn Entscheidungsdokumente in einem separaten Wiki oder Dokumentationssystem leben, ist es weniger wahrscheinlich, dass sie zusammen mit Codeänderungen aktualisiert werden, und viel weniger wahrscheinlich, dass sie von KI-Coding-Tools gelesen werden, die Kontext für eine Aufgabe laden. Das Aufbewahren im Repository ist nicht nur eine Bequemlichkeit – es ist das, was die Praxis für KI-gestützte Entwicklung funktioniert.

Ein leichtgewichtiges Betriebsmodell

Ein praktischer Teamprozess, der minimalen Overhead hinzufügt, sieht so aus:

1. Während der Planung oder Implementierung identifizieren Sie, ob eine bedeutungsvolle Entscheidung getroffen wird.
2. Bitten Sie einen KI-Assistenten, ein ADR, PDR oder DDR basierend auf der Diskussion zu entwerfen.
3. Überprüfen Sie den Entwurf als Team und verifizieren Sie Kontext, Alternativen und Konsequenzen.
4. Commiten Sie das Dokument als Markdown im Repository.
5. Verlinken Sie es vom verwandten Issue oder Pull Request.
6. Weisen Sie KI-Coding-Tools an, relevante Dokumente zu lesen, bevor sie zukünftige Änderungen in diesem Bereich vornehmen.
7. Lösen Sie Dokumente ab, wenn sich Entscheidungen ändern, und bewahren Sie das alte Dokument für die Historie auf.

Dies erfordert keine neue Bürokratie oder eine dedizierte Dokumentationsrolle. Es erfordert eine kleine Gewohnheit: Wichtige Urteile in dem Moment zu bewahren, in dem sie erstellt werden, nah am Code, wo sie benötigt werden.

Beispiel ADR

# Entscheidung: Verwenden Sie PostgreSQL für die primäre Anwendungsspeicherung

Status: Akzeptiert
Datum: 2026-06-25
Typ: Architektur
Verantwortliche: Plattform-Team

## Kontext

Die Anwendung benötigt eine dauerhafte relationale Speicherung für Konten, Projekte,
Berechtigungen und Audit-Events. Das Team erwartet häufige Reporting-Abfragen
und starke Konsistenzanforderungen für Berechtigungsprüfungen.

## Entscheidung

Wir werden PostgreSQL als primäre Anwendungsdatabase verwenden.

## In Betracht gezogene Alternativen

### DynamoDB

Vorteile:
- Operativ skalierbar
- Gut geeignet für vorhersehbare Key-Value-Zugriffsmuster

Nachteile:
- Komplexer für relationale Abfragen
- Schwerer für ad-hoc Reporting
- Weniger vertraut für das aktuelle Team

### MySQL

Vorteile:
- Reife relationale Datenbank
- Vertrautes Betriebsmodell

Nachteile:
- PostgreSQL entspricht besser den Bedürfnissen des Teams bezüglich JSON-Support,
  Indexierungsoptionen und vorhandener Expertise

## Konsequenzen

PostgreSQL wird eine zentrale operative Abhängigkeit. Das Team muss
Migrationen sorgfältig verwalten und die Abfrageleistung überwachen. Im Gegenzug
bekommt die Anwendung starkes relationales Modellieren, reife Indexierung und
flexiblen Reporting-Support.

## KI-Anleitung

Beim Modifizieren von Persistenzcode, bevorzugen Sie relationales Modellieren in PostgreSQL.
Führen Sie keine zweite primäre Datenbank ein, ohne ein ablösendes ADR.

Beispiel PDR

# Entscheidung: KI-generierte E-Mails müssen als Entwurf verbleiben

Status: Akzeptiert
Datum: 2026-06-25
Typ: Produkt
Verantwortliche: Produkt-Team

## Kontext

Das Produkt kann E-Mail-Antworten unter Verwendung von KI generieren. Das Senden von E-Mails ist eine
Action mit hohem Vertrauen, da Fehler Kunden, Partner oder
interne Teams erreichen können.

## Entscheidung

KI-generierte E-Mails müssen als Entwurf erstellt werden. Ein menschlicher Benutzer muss
sie überprüfen und senden.

## In Betracht gezogene Alternativen

### Automatisch senden

Vorteile:
- Schnellerer Workflow
- Weniger Benutzeranstrengung

Nachteile:
- Höheres Risiko für falsche oder unangemessene Nachrichten
- Niedrigeres Benutzervertrauen
- Schwerer, Fehler zu beheben

### Nur nach Generierung um Bestätigung bitten

Vorteile:
- Hält den Workflow einfach
- Bietet einige Benutzerkontrolle

Nachteile:
- Ermutigt immer noch zu oberflächlicher Überprüfung
- Passt nicht so gut zum Verhalten bestehender E-Mail-Clients wie Entwürfe

## Konsequenzen

Der Workflow ist etwas langsamer, aber sicherer und vertrauenswürdiger.
Zukünftige Automatisierung kann die Überprüfungsgeschwindigkeit verbessern, darf aber nicht
die menschliche Genehmigung umgehen, ohne ein ablösendes PDR.

## KI-Anleitung

Beim Erstellen von E-Mail-Generierungsfunktionen, erstellen Sie standardmäßig Entwürfe.
Fügen Sie kein automatisches Senden hinzu, es sei denn, ein neues akzeptiertes PDR erlaubt es explizit.

Beispiel DDR

# Entscheidung: KI-Schreibvorschläge in einer Seitenleiste anzeigen

Status: Akzeptiert
Datum: 2026-06-25
Typ: Design
Verantwortliche: Design-Team

## Kontext

Benutzer benötigen Hilfe bei der Verbesserung von geschriebenen Inhalten, aber sie müssen auch die
Kontrolle über den endgültigen Text behalten. Inline-KI-Redaktionen können es schwer machen,
benutzergeschriebene Inhalte von generierten Vorschlägen zu unterscheiden.

## Entscheidung

KI-Schreibvorschläge werden in einer Seitenleiste erscheinen. Benutzer können Vorschläge akzeptieren,
ablehnen oder in den Haupteditor kopieren.

## In Betracht gezogene Alternativen

### Vorschläge inline anwenden

Vorteile:
- Schnell
- Fühlt sich integriert an

Nachteile:
- Vermischt Autorenschaft
- Macht Überprüfung schwieriger
- Kann Benutzer überraschen

### Vorschläge in einem Modal anzeigen

Vorteile:
- Fokussierte Erfahrung
- Leicht zu implementieren

Nachteile:
- Unterbricht den Schreibfluss
- Schwerer, Vorschlag und Originaltext zu vergleichen

## Konsequenzen

Die Seitenleiste nimmt mehr Bildschirmaufwand ein, insbesondere auf kleinen Bildschirmen.
Sie bewahrt jedoch die Benutzerkontrolle und macht die Überprüfung klarer.

## KI-Anleitung

Beim Hinzufügen von Schreibassistenzfunktionen, bewahren Sie die Trennung zwischen
Benutzertext und KI-Vorschlägen auf. Wenden Sie generierten Text nicht direkt
in das Dokument an, ohne explizite Benutzeraktion.

Vorgeschlagene Prompt-Bibliothek

Verwenden Sie diese Prompts, um Entscheidungsdokumente Teil der täglichen KI-gestützten Entwicklung zu machen.

Relevante Dokumente finden, bevor man an einer Funktion arbeitet:

Lesen Sie docs/decisions und identifizieren Sie alle akzeptierten Entscheidungsdokumente, die
für diese Aufgabe gelten. Fassen Sie die Einschränkungen zusammen, bevor Sie Codeänderungen vorschlagen.

Ein neues ADR entwerfen:

Entwerfen Sie ein Architektur-Entscheidungsdokument für diese technische Entscheidung.
Schließen Sie Kontext, Entscheidung, Alternativen, Konsequenzen und KI-Anleitung ein.
Halten Sie es prägnant und spezifisch.

Ein neues PDR entwerfen:

Entwerfen Sie ein Produkt-Entscheidungsdokument für dieses Produktverhalten.
Schließen Sie Benutzerwirkung, Umfang, Alternativen, Konsequenzen und KI-Anleitung ein.

Ein neues DDR entwerfen:

Entwerfen Sie ein Design-Entscheidungsdokument für dieses Interaktionsmuster.
Schließen Sie Benutzerproblem, Alternativen, Kompromisse, Konsequenzen und KI-Anleitung ein.

Einen Pull Request gegen bestehende Entscheidungen überprüfen:

Überprüfen Sie diesen Pull Request gegen die akzeptierten Entscheidungsdokumente in docs/decisions.
Identifizieren Sie Konflikt, fehlende Entscheidungsdokumente oder Entscheidungen, die
abgelöst werden sollten.

Eine Entscheidung ablösen:

Erstellen Sie ein neues Entscheidungsdokument, das das bestehende ablöst.
Bewahren Sie die historische Begründung auf, erklären Sie, was sich geändert hat, und verlinken Sie beide Dokumente.

Verwandtes Lesen

• Michael Nygard’s ursprüngliches ADR-Format — der grundlegende Post, der die ADR-Bewegung startete
• ADR GitHub Organisation — Tooling, Templates und Community-Ressourcen zur Verwaltung von Entscheidungsdokumenten
• Was ist Spec-Driven Development? Die Spezifikation als Single Source of Truth — die kanonische SDD-Definition, die erklärt, wie Feature-Specs Entscheidungsdokumente ergänzen: Beide machen Absicht dauerhaft, auf unterschiedlichen Ebenen des Systems
• Spec-Driven Development vs Vibe Coding: Wasserfall? — wann man SDD verwendet und wann man bei schnelleren, lockereren Workflows bleibt
• App-Architektur in der Produktion: Integrationsmuster, Code-Design und Datenzugriff — das Cluster-Home, das Integration, Testing, Datenzugriff und Software-Dokumentationsmuster abdeckt
• KI für Wissensmanagement: Reale Workflows, die standhalten — praktische KI-augmentierte Wissensmanagement-Workflows, die die Praxis der Entscheidungsdokumente ergänzen