Entscheidungsprotokolle für die KI-gestützte Softwareentwicklung

Behalten Sie die Absicht nah am Code.

Inhaltsverzeichnis

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 kritisch, wenn KI-Tools Ihren Code schreiben.

Entscheidungsdokumente — ADR, PDR, DDR — verbinden Absicht mit Code

Entscheidungsdokumente sind die fehlende Speicherschicht

KI-gestütztes Programmieren verändert die Wirtschaftlichkeit der Softwareentwicklung, indem es Code günstiger zu generieren, einfacher zu refaktorisieren und schneller zu verwerfen macht. Das ist nützlich. Es ist auch gefährlich, denn wenn Code einfacher zu produzieren wird, ist die knappe Ressource nicht mehr das Tippen – die knappe Ressource ist die Urteilsfähigkeit.

Warum hat das Team PostgreSQL anstelle von DynamoDB gewählt? Warum erfordert das Produkt eine menschliche Überprüfung, bevor KI-generierte E-Mails gesendet werden? Warum zeigt die Benutzeroberfläche Vorschläge in einer Seitenleiste anstelle von deren direkter Anwendung? 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 betrachteten Alternativen und die vom Team akzeptierten Konsequenzen erfasst. In einer von KI unterstützten Codebasis werden diese Dokumente zu mehr als nur Dokumentation – sie werden zu einer dauerhaften Projektspeicherung, die sowohl von Menschen als auch von KI-Coding-Agenten gelesen werden kann, bevor zukünftige Änderungen vorgenommen werden. Die praktische Betriebsregel ist einfach: Halten Sie Entscheidungsdokumente als Markdown-Dateien im Repository, ü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 eine schriftliche Aufzeichnung einer bedeutungsvollen Entscheidung, strukturiert um vier grundlegende Fragen zu beantworten: Was haben wir entschieden, warum haben wir es entschieden, welche Alternativen haben wir betrachtet und welche Konsequenzen haben wir akzeptiert? Die häufigste Form ist das Architektur-Entscheidungsdokument (Architecture Decision Record), abgekürzt als ADR. ADRs werden weithin verwendet, um technische Entscheidungen zu dokumentieren, und dasselbe Muster kann über die Architektur hinaus auf Produkt- und Designarbeit erweitert werden.

Für das KI-gestützte Programmieren sind drei Typen besonders nützlich:

Dokumenttyp Erfasst Beispiel
ADR Architektur- und technische Entscheidungen Verwenden von PostgreSQL als primäre Datenbank
PDR Produktverhalten und Umfangsentscheidungen KI-generierte E-Mails müssen als Entwurf bleiben
DDR Design- und Interaktionsentscheidungen KI-Vorschläge in einer Seitenleiste anzeigen

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

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

Beispiele für Entscheidungen, die sich als ADRs lohnen, 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 serverseitigem 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 absichtlich klein und zeichnet eine wichtige Entscheidung zu einem bestimmten Zeitpunkt auf. Ein gutes ADR verhindert architektonische Amnesie: Ohne es können zukünftige Mitwirkende dieselben Kompromisse neu entdecken, alte Debatten wieder aufrollen oder versehentlich wichtige Einschränkungen rückgängig machen.

In der KI-gestützten Programmierung tragen ADRs noch mehr Gewicht. KI-Tools sind oft bei der lokalen Optimierung geschickt 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 geformt sein.“

Produkt-Entscheidungsdokumente

Produkt-Entscheidungsdokumente erfassen Produktverhalten, Umfang und nutzerbezogene Absichten. Dies ist weniger verbreitet als ADRs, aber oft genauso wertvoll – Produktentscheidungen sind häufig über Tickets, Roadmap-Tools, Chat-Threads, Meeting-Notizen und die Erinnerungen der Menschen verstreut, was sie für Menschen leicht vergessen und für KI-Tools fast unmöglich zuverlässig ableiten lässt.

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 nutzerbezogene Funktion sich verhalten soll. Beispiele sind:

  • KI-generierte Nachrichten müssen als Entwurf bleiben, bis sie von einem Menschen überprüft wurden
  • Benutzer der kostenlosen Stufe können bis zu drei Projekte erstellen
  • Gelöschte Arbeitsbereiche sind für 30 Tage wiederherstellbar
  • Teamabrechnung liegt außerhalb des Umfangs für Version 1
  • Benutzer können ihre Daten exportieren, ohne den Support zu kontaktieren
  • KI-Zusammenfassungen mit niedriger Konfidenz 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 ein Limit von drei Projekten für kostenlose Benutzer enthalten, und ohne ein PDR könnte ein KI-Tool diese Zahl als magische Konstante behandeln und vorschlagen, sie zu ändern. Mit einem PDR kann die KI sehen, dass das Limit mit der Preisstrategie, den Onboarding-Kosten oder der Supportauslastung verbunden ist – und dass eine Änderung eine bewusste Produktentscheidung erfordert, nicht nur eine schnelle Bearbeitung.

Design-Entscheidungsdokumente

Design-Entscheidungsdokumente erfassen Entscheidungen zur Benutzererfahrung, Interaktion, visuellen Gestaltung und Content-Design. Verwenden Sie ein DDR, wenn eine Entscheidung beeinflusst, wie Benutzer 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 sich zu dokumentieren lohnen, sind:

  • Verwendung von Inline-Validierung anstelle von Validierung nur beim Absenden
  • Platzieren von KI-Vorschlägen in einer Seitenleiste anstelle direkt im Editor
  • Verwendung von progressiver Offenlegung für erweiterte Einstellungen
  • Erfordern einer Bestätigung vor zerstörerischen Aktionen
  • Verwendung von „Entwurf“ und „Veröffentlicht“ anstelle von „Inaktiv“ und „Aktiv“
  • Halten der primären Aktionen auf mobilen Bildschirmen sichtbar

Designabsicht ist während der Implementierung leicht zu verlieren. 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 aufzeichnen: „Wir zeigen KI-Schreibvorschläge neben dem Dokument, nicht darin, weil Benutzer den generierten Text mit ihrem eigenen Entwurf vergleichen müssen, bevor sie Änderungen akzeptieren.“ Dieses Dokument gibt zukünftigen Mitwirkenden ein Prinzip zur Bewahrung, nicht nur ein Layout zum Kopieren.

Warum Entscheidungsdokumente mit KI wichtiger sind

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

KI kann geschlossene Debatten wieder aufrollen

Wenn das Team bereits entschieden hat, einen modularen Monolithen zu verwenden, kann ein KI-Agent dennoch vorschlagen, einen Service zu extrahieren, weil dies isoliert sauber aussieht. Ohne ein ADR hat die KI keine dauerhafte Möglichkeit zu wissen, dass das Team diesen Weg bereits betrachtet und abgelehnt hat, und das Ergebnis ist verschwendete Arbeit oder eine subtile Regression in 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 Komponentenkomplexität 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 Referenzrahmen, bevor sie auf eng umschriebene Signale reagiert.

KI kann Code bewahren, aber Absicht verlieren

Ein Modell kann bestehenden Mustern in der Codebase folgen, aber Muster sind nicht dasselbe wie Prinzipien. Manchmal ist bestehender Code ein Kompromiss. Manchmal ist er Übergangslösung. Manchmal existiert er wegen einer externen Einschränkung, die in der Datei nicht sichtbar ist. Entscheidungsdokumente erklären den Unterschied zwischen „So funktioniert es“ und „Warum es auf diese Weise gebaut wurde.“

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, dass es die tatsächliche Entscheidung, Alternativen und Konsequenzen genau beschreibt, bevor das Dokument zusammengeführt 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, Produkterkundung, Design-Rationale, KI-Governance und Code-Review liegt. Eine nützliche Art, den größeren Prozess zu beschreiben, ist Entscheidungsorientierte Entwicklung.

Die meisten KI-gestützten Programmierworkflows konzentrieren sich eng auf den Generieren-Überprüfen-Commit-Loop:

flowchart LR A[Prompt] --> B[Code generieren] B --> C[Testen] C --> D[Commit]

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

flowchart TB subgraph top[" "] direction LR A[Problem rahmen] --> B[Bestehende Entscheidungen identifizieren] --> C[Optionen und Kompromisse erkunden] --> D[Ausgewählte Entscheidung dokumentieren] end subgraph bottom[" "] direction LR E[Code generieren oder ändern] --> F[Code gegen Entscheidungen überprüfen] --> G[Implementierung und Speicher zusammenführen] --> H[Dokument zur Führung künftiger Arbeiten verwenden] end D --> E

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 dauerhaftes Artefakt, das mit jeder getroffenen Entscheidung an Wert gewinnt.

Entscheidungsdokumente und Docs as Code

Entscheidungsdokumente funktionieren am besten, wenn sie Docs-as-Code-Prinzipien 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 von Menschen als auch von KI-Tools durchsuchbar sein sollten. Dies ist viel zuverlässiger, als wichtige Entscheidungen in Chats, Wiki-Seiten, Präsentationen oder Meeting-Notizen zu speichern – diese Tools können für Diskussionen noch nützlich sein, aber die akzeptierte Entscheidung sollte immer in der Nähe des Codes leben.

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 ebenso 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 zu laden sein, um sie als Kontext vor der Aktion auf der Codebasis zu verwenden. 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, das docs/ als Zuhause für Architektur-Entscheidungen und API-Referenzen empfiehlt.

Eine praktische Vorlage für Entscheidungsdokumente

Eine nützliche Vorlage für Entscheidungsdokumente sollte kurz genug sein, dass Menschen sie tatsächlich verwenden. Hier ist eine praktische Markdown-Vorlage, die eine optionale, aber wertvolle KI-Leitungssektion enthält:

# Entscheidung: Kurzer Titel

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

## Kontext

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

## Entscheidung

Stellen Sie die Entscheidung klar dar.

## Betrachtete Alternativen

### Option 1

Vorteile:
- ...

Nachteile:
- ...

## Konsequenzen

Beschreiben Sie, was einfacher wird, was schwieriger wird und welche Risiken
oder Folgemaßnahmen dies schafft.

## KI-Leitlinie

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

## Links

- Verwandte Issues:
- Verwandte Pull Requests:
- Verwandte Dateien:
- Ersetzt:
- Ersetzt durch:

Die Sektion „KI-Leitlinie“ ist optional, aber für die KI-gestützte Programmierung ist sie extrem wertvoll – sie verwandelt das Entscheidungsdokument in eine dauerhafte Anweisung für zukünftige Agenten, die im selben Bereich der Codebasis arbeiten.

Was in ein Entscheidungsdokument gehört?

Nicht jede Wahl verdient ein Dokument, und wenn jedes kleine Implementierungsdetail zu einem Entscheidungsdokument wird, kollabiert der Prozess in 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 auflösen
  • Einen langfristigen Kompromitt einführen
  • 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, leichtsinnig rückgängig zu machen

Schlechte Kandidaten sind winzige Refaktorierungswahlen, offensichtliche Bug-Fixes, vorübergehende Experimente, lokale Benennungsentscheidungen und Implementierungsdetails ohne bleibende Konsequenz. Eine gute Daumenregel ist einfach: Wenn das Rückgängigmachen der Entscheidung eine Diskussion erfordern würde, dokumentieren Sie die Entscheidung.

Statuswerte und Lebenszyklus

Entscheidungsdokumente sollten einen Lebenszyklus haben, um ihre aktuelle Gültigkeit 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 Arbeiten leiten. Die meisten nützlichen Entscheidungsdokumente werden den Großteil ihres Lebens in diesem Zustand verbringen.

Ersetzt — 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, sodass die Entwicklung des Denkens sichtbar bleibt.

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

Das wichtige Prinzip ist, dass Entscheidungsdokumente anhängfreundlich 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 helfen, Entscheidungsdokumente zu erstellen, und dies ist eine der besseren Anwendungen von KI in der Softwareentwicklung – sie ist schnell darin, strukturierte Dokumente aus Kontext zu entwerfen. 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.
Inkludieren Sie Kontext, Alternativen, Konsequenzen und KI-Leitlinie.
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 Entwürfe bleiben müssen, bis sie vom Benutzer überprüft wurden.
Inkludieren Sie Benutzerimpact, außerhalb des Umfangs liegendes Verhalten, Kompromisse und KI-Leitlinie.

Das KI-generierte Dokument sollte jedoch nicht automatisch vertraut werden. Eine menschliche Überprüfung sollte verifizieren, 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-Leitlinie 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 ist die Anweisung an KI, 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 anwendbar sind.
Folgen Sie akzeptierten Entscheidungen. Wenn Ihr vorgeschlagener Konflikt mit einem Entscheidungsdokument
konfligiert, erklären Sie den Konflikt, bevor Sie Code ändern.

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

Verwenden Sie die Entscheidungsdokumente als Projektspeicher.
Machen Sie akzeptierte Entscheidungen nicht rückgängig, ohne eine neue ersetzende 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:

## Checkliste für Entscheidungsdokumente

- [ ] Dieser PR führt keine signifikante Architektur-, Produkt- oder Designentscheidung ein.
- [ ] Dieser PR führt eine signifikante Entscheidung ein und enthält ein neues Entscheidungsdokument.
- [ ] Dieser PR ändert eine vorherige Entscheidung und enthält ein ersetzendes 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 das einzige Artefakt ist, das in einem Pull Request von Bedeutung ist. Es macht es auch natürlich, festzustellen, wann eine KI-generierte Änderung stillschweigend eine frühere Entscheidung verletzt.

Entscheidungsdokumente und Architektur-Governance

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

Sie erfordern kein zentrales Architektur-Board für jede Änderung, noch blockieren sie Teams beim Lernen und Anpassen. Stattdessen schaffen sie eine Spur von Entscheidungen, die mit 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 ihr. Das Team kann alte Entscheidungen erneut betrachten, ohne neu entdecken zu müssen, warum sie getroffen wurden, was eine gesündere und ehrlichere Form der Governance ist:

  • Kleine Dokumente anstelle von riesigen Dokumenten
  • Überprüfung in der Nähe des Codes anstelle von separater Genehmigungstheater
  • Historischer Kontext anstelle von Stammwissen
  • Explizite Kompromisse anstelle von versteckten Annahmen

Entscheidungsdokumente und Produktmanagement

Produktarbeit benötigt auch 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 Benutzer 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 Kontingente, KI-Sicherheit und Überprüfungsflüsse, Onboarding-Entscheidungen, Benutzerrollendefinitionen, Kollaborationsregeln, Datenaufbewahrungspolitiken und Feature-Umfangsgrenzen. Einmal implementiert, werden Produktentscheidungen im Code unsichtbar – später sieht jemand nur den Code und fragt: „Warum funktioniert es auf diese Weise?“ Ein PDR gibt die Antwort in einer Form, die sowohl Menschen als auch KI-Tools finden und verwenden können.

Entscheidungsdokumente und Designsysteme

Designsysteme 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 Benutzer oft mit gemeinsamen Teamdaten arbeiten, und versehentliches Löschen eine hohe Wiederherstellungskosten hat.“

Diese Begründung ist wichtig über die spezifische Komponente hinaus. Sie hilft zukünftigen Designern, Entwicklern und KI-Tools, das Prinzip korrekt in neuen Situationen anzuwenden. Ohne das DDR kann 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 beabsichtigt und nicht verhandelbar ist.

Wie Entscheidungsdokumente spec-getriebene Entwicklung unterstützen

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

Eine Feature-Spezifikation kann sagen, dass KI-generierte E-Mails als Entwürfe gespeichert werden müssen. Ein Produkt-Entscheidungsdokument erklärt, warum automatisches Senden abgelehnt wurde, welche Risiken betrachtet wurden und welche zukünftigen Änderungen eine neue Entscheidung erfordern würden. Eine Design-Spezifikation kann eine Seitenleisteninteraktion beschreiben, während das entsprechende DDR erklärt, warum Inline-KI-Bearbeitungen explizit abgelehnt wurden und warum die Erhaltung der Benutzerkontrolle stärker gewichtet wurde als die Workflow-Geschwindigkeit. Eine Architektur-Spezifikation kann eine Servicegrenze definieren, und ihr ADR erklärt, warum das Team diese Grenze gegenüber einer einfacheren oder verteilten Alternative gewählt hat.

Die Spezifikation führt die Implementierung. Das Entscheidungsdokument bewahrt das Urteilsvermögen. Zusammen geben sie KI-Coding-Agenten sowohl Anweisungen als auch Kontext – das „Was“ und das „Warum“ – was die Kombination für komplexe, langlebige Systeme so effektiv macht.

Entscheidungsdokumente sind keine Spezifikationen

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

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 Entwürfe gespeichert werden müssen, während ein Produkt-Entscheidungsdokument erklärt, dass dies erforderlich ist, weil Benutzer 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 Codekommentare

Codekommentare 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. Noch besser ist es, 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 Urteilsvermögen 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

Die Konsequenzensektion ist das Herz des Dokuments. Eine Entscheidung ohne genannte Konsequenzen ist oft nur eine Präferenz anstelle einer echten Entscheidung. Gute Dokumente geben Kompromisse ehrlich zu, einschließlich dessen, was als Ergebnis der Wahl schwieriger oder risikoreicher wird.

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 ersetzt. Stilles Neuschreiben einer alten Entscheidung, um dem aktuellen Zustand zu entsprechen, zerstört den historischen Kontext, der Entscheidungsdokumente wertvoll macht. Geschichte ist nützlich, genau weil sie zeigt, wie sich das Denken entwickelt hat.

KI-generierte Dokumente ohne Überprüfung zusammenführen 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 die Konsequenzensektion widerspiegelt, was das Team tatsächlich akzeptiert hat.

Dokumente außerhalb des Repositories 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 Halten von Dokumenten im Repository ist nicht nur eine Bequemlichkeit – es ist das, was die Praxis für KI-gestützte Entwicklung funktioniert.

Ein leichtes 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 dem Bereich vornehmen.
  7. Ersetzen Sie Dokumente, 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: Wichtiges Urteilsvermögen zu bewahren, in dem Moment, in dem es entsteht, in der Nähe des Codes, wo es benötigt wird.

Beispiel ADR

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

Status: Akzeptiert
Datum: 25.06.2026
Typ: Architektur
Verantwortliche: Plattformteam

## Kontext

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

## Entscheidung

Wir werden PostgreSQL als primäre Anwendungsdatabase verwenden.

## Betrachtete 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 operatives Modell

Nachteile:
- PostgreSQL entspricht besser den Bedürfnissen des Teams hinsichtlich JSON-Unterstützung,
  Indexierungsoptionen und bestehender Expertise

## Konsequenzen

PostgreSQL wird eine zentrale operative Abhängigkeit. Das Team muss
Migrationen sorgfältig verwalten und die Abfrageleistung überwachen. Im Gegenzug
erhält die Anwendung starke relationale Modellierung, reife Indexierung und
flexible Reporting-Unterstützung.

## KI-Leitlinie

Beim Ändern von Persistenzcode bevorzugen Sie relationale Modellierung in PostgreSQL.
Führen Sie keine zweite primäre Datenbank ein, ohne ein ersetzendes ADR.

Beispiel PDR

# Entscheidung: KI-generierte E-Mails müssen als Entwürfe bleiben

Status: Akzeptiert
Datum: 25.06.2026
Typ: Produkt
Verantwortliche: Produktteam

## Kontext

Das Produkt kann E-Mail-Antworten unter Verwendung von KI generieren. Das Senden von E-Mails ist eine
hochvertrauenswürdige Aktion, weil Fehler Kunden, Partner oder
interne Teams erreichen können.

## Entscheidung

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

## Betrachtete Alternativen

### Automatisches Senden

Vorteile:
- Schnellerer Workflow
- Weniger Benutzerarbeit

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

### Nur nach Generierung nach Bestätigung fragen

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
menschliche Genehmigung umgehen, ohne ein ersetzendes PDR.

## KI-Leitlinie

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: 25.06.2026
Typ: Design
Verantwortliche: Designteam

## Kontext

Benutzer benötigen Hilfe bei der Verbesserung geschriebener Inhalte, müssen aber auch
die Kontrolle über den endgültigen Text behalten. Inline-KI-Bearbeitungen können es schwierig 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.

## Betrachtete 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
- Einfach zu implementieren

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

## Konsequenzen

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

## KI-Leitlinie

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

Vorgeslagene Prompt-Bibliothek

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

Relevante Dokumente finden, bevor an einer Funktion gearbeitet wird:

Lesen Sie docs/decisions und identifizieren Sie alle akzeptierten Entscheidungsdokumente, die
auf diese Aufgabe anwendbar sind. 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.
Inkludieren Sie Kontext, Entscheidung, Alternativen, Konsequenzen und KI-Leitlinie.
Halten Sie es prägnant und spezifisch.

Ein neues PDR entwerfen:

Entwerfen Sie ein Produkt-Entscheidungsdokument für dieses Produktverhalten.
Inkludieren Sie Benutzerimpact, Umfang, Alternativen, Konsequenzen und KI-Leitlinie.

Ein neues DDR entwerfen:

Entwerfen Sie ein Design-Entscheidungsdokument für dieses Interaktionsmuster.
Inkludieren Sie Benutzerproblem, Alternativen, Kompromisse, Konsequenzen und KI-Leitlinie.

Einen Pull Request gegen bestehende Entscheidungen überprüfen:

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

Eine Entscheidung ersetzen:

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

Verwandte Lektüre

Abonnieren

Neue Beiträge zu Systemen, Infrastruktur und KI-Engineering.