Entscheidungsprotokolle für KI-gesteuerte Softwareentwicklung

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

Entscheidungsprotokolle sind die fehlende Speicherschicht

KI-gesteuertes Programmieren verändert die Ökonomie der Softwareentwicklung, indem Code günstiger zu generieren, leichter zu refaktorisieren und schneller verworfen wird. Das ist nützlich. Es ist auch gefährlich, denn wenn Code leichter zu produzieren ist, ist die knappe Ressource nicht mehr das Tippen – die knappe Ressource ist das Urteil.

Warum wählte das Team PostgreSQL anstelle von DynamoDB? Warum verlangt das Produkt eine menschliche Prüfung, bevor KI-generierte E-Mails gesendet werden? Warum zeigt die Schnittstelle Vorschläge in einem Seitenpanel, anstatt sie direkt anzuwenden? Warum wurde ein einfacherer Ansatz vor sechs Monaten abgelehnt? Der Code mag zeigen, was existiert, erklärt aber selten, warum es existiert.

Entscheidungsprotokolle lösen dieses Problem, indem sie ein kurzes, versionskontrolliertes Dokument bereitstellen, das eine wichtige Entscheidung, den dahinterliegenden Kontext, die erwogenen Alternativen und die vom Team akzeptierten Konsequenzen erfasst. In einer KI-gestützten Codebasis werden diese Protokolle zu mehr als nur Dokumentation – sie werden zum dauerhaften Projektgedächtnis, das sowohl von Menschen als auch von KI-Coding-Agenten gelesen werden kann, bevor sie künftige Änderungen vornehmen. Die praktische Handlungsregel ist einfach: Halten Sie Entscheidungsprotokolle als Markdown-Dateien im Repository vor, prüfen Sie sie wie Code und lassen Sie zukünftige KI-Tools sie lesen, bevor sie Änderungen vorschlagen oder implementieren.

Was sind Entscheidungsprotokolle?

Ein Entscheidungsprotokoll ist ein schriftlicher Aufzeichnungsvermerk über eine bedeutende Entscheidung, strukturiert, um vier grundlegende Fragen zu beantworten: Was haben wir beschlossen, warum haben wir es beschlossen, welche Alternativen haben wir erwogen und welche Konsequenzen haben wir akzeptiert? Die häufigste Form ist das Architektur-Entscheidungsprotokoll (Architecture Decision Record, kurz ADR). ADRs werden weitgehend verwendet, um technische Entscheidungen zu dokumentieren, und das gleiche Muster kann über die Architektur hinaus auf Produkt- und Designarbeit ausgedehnt werden.

Für KI-gesteuertes Programmieren 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 Reasoning hinter dem Benutzererlebnis. Diese Kombination ist wichtig, weil KI-Agenten Code lesen können, aber Code allein nicht genug Kontext enthält, um gute Entscheidungen zu treffen. Entscheidungsprotokolle geben KI-Systemen eine geprüfte, dauerhafte, menschlich genehmigte Quelle für Projektabsichten.

Architektur-Entscheidungsprotokolle (ADR)

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

Beispiele für Entscheidungen, die sich als ADRs aufzeichnen lassen, umfassen:

• Auswahl von PostgreSQL als primäre Datenbank
• Verwendung einer ereignisgesteuerten Architektur für Hintergrundverarbeitung
• Halten der Anwendung als modulares Monolithen-Design
• Einführung einer Nachrichtenwarteschlange (Message Queue)
• Auswahl von REST anstelle von GraphQL
• Verwendung serverseitiger Rendern (Server-Side Rendering) für die Webanwendung
• Forderung, dass alle Hintergrundjobs idempotent sein müssen
• Einführung eines bestimmten Authentifizierungs- und Autorisierungsmodells

Ein ADR ist kein vollständiges Architekturendokument – es ist bewusst klein und dokumentiert eine wichtige Entscheidung zu einem bestimmten Zeitpunkt. Ein gutes ADR verhindert architektonische Amnesie: Ohne es könnten zukünftige Mitwirkende dieselben Abwägungen neu entdecken, alte Debatten wiedereröffnen oder versehentlich wichtige Einschränkungen rückgängig machen.

Im KI-gesteuerten Programmieren tragen ADRs noch mehr Gewicht. KI-Tools sind oft in der lokalen Optimierung gut 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-Entscheidungsprotokolle (PDR)

Produkt-Entscheidungsprotokolle erfassen Produktverhalten, Umfang (Scope) und nutzerbezogene Absichten. Dies ist weniger häufig als ADRs, aber oft genauso wertvoll – Produktentscheidungen sind häufig über Tickets, Roadmap-Tools, Chat-Threads, Meeting-Notizen und die Erinnerungen der Mitarbeiter verstreut, was es für Menschen leicht macht, sie zu vergessen, und es für KI-Tools nahezu 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 ein nutzerbezogenes Feature sich verhalten sollte. Beispiele umfassen:

• KI-generierte Nachrichten müssen Entwürfe bleiben, bis sie von einem Menschen geprüft wurden
• Nutzer des kostenlosen Tarifs können bis zu drei Projekte erstellen
• Gelöschte Arbeitsbereiche sind 30 Tage wiederherstellbar
• Team-Abrechnung ist in Version 1 nicht im Scope
• Nutzer können ihre Daten exportieren, ohne den Support zu kontaktieren
• KI-Zusammenfassungen mit niedriger Konfidenz zeigen eine Warnung, anstatt verborgen zu werden

Ein PDR ist besonders nützlich, wenn eine Produktentscheidung aus dem Code heraus willkürlich wirkt. Der Code könnte eine Beschränkung von drei Projekten für kostenlose Nutzer 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 die Beschränkung mit der Preiskalkulation, den Onboarding-Kosten oder der Support-Last verknüpft ist – und dass eine Änderung eine bewusste Produktentscheidung erfordert, keine schnelle Editierung.

Design-Entscheidungsprotokolle (DDR)

Design-Entscheidungsprotokolle erfassen Entscheidungen zur Benutzererfahrung, Interaktion, visuellen Gestaltung und Inhaltsdesign. 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ünftiger Arbeit angewendet werden sollte.

Beispiele für Designentscheidungen, die sich aufzeichnen lassen, umfassen:

• Verwendung inline Validierung anstelle von Validierung nur beim Absenden
• Platzierung von KI-Vorschlägen in einem Seitenpanel anstatt direkt im Editor
• Verwendung progressive Offenlegung (Progressive Disclosure) für erweiterte Einstellungen
• Erfordernis einer Bestätigung vor zerstörerischen Aktionen
• Verwendung von „Entwurf“ und „Veröffentlicht“ anstelle von „Inaktiv“ und „Aktiv“
• Halten primärer Aktionen auf Mobilgeräten sichtbar

Designabsicht geht bei der Implementierung leicht verloren. Ein Entwickler kann einen Ablauf vereinfachen, oder ein KI-Agent kann ein 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 Nutzer generierten Text mit ihrem eigenen Entwurf vergleichen müssen, bevor sie Änderungen akzeptieren.“ Dieses Protokoll gibt zukünftigen Mitwirkenden ein Prinzip, das erhalten bleiben soll, nicht nur ein Layout, das kopiert werden soll.

Warum Entscheidungsprotokolle mit KI wichtiger sind

KI-Coding-Tools sind mächtig, aber sie sind oft zustandslos oder nur teilweise über die Projekthistorie 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 waren. Dies schafft mehrere einzelne Risiken.

KI könnte abgeschlossene Debatten wiedereröffnen

Wenn das Team bereits beschlossen hat, einen modularen Monolithen zu verwenden, könnte ein KI-Agent dennoch vorschlagen, einen Service auszugliedern, weil das isoliert sauber aussieht. Ohne ein ADR hat die KI keinen dauerhaften Weg zu wissen, dass das Team diesen Pfad bereits erwogen und abgelehnt hat, und das Ergebnis ist verschwendete Arbeit oder eine subtile Regression in der Systemkonsistenz.

KI könnte lokal optimieren und global schaden

Ein generiertes Refactoring kann eine Datei sauberer machen, während es 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. Entscheidungsprotokolle geben der KI einen größeren Referenzrahmen, bevor sie auf eng gefasste Signale reagiert.

KI könnte Code erhalten, aber Absicht verlieren

Ein Modell kann bestehende Muster in der Codebasis verfolgen, aber Muster sind nicht dasselbe wie Prinzipien. Manchmal ist bestehender Code ein Kompromiss. Manchmal ist er übergangsweise. Manchmal existiert er wegen einer externen Einschränkung, die in der Datei nicht sichtbar ist. Entscheidungsprotokolle erklären den Unterschied zwischen „so funktioniert es“ und „so wurde es gebaut“.

KI könnte plausible, aber falsche Begründungen generieren

KI kann Entscheidungsprotokolle entwerfen, aber sie kann auch überzeugend klingende Erklärungen erfinden, die nicht zur eigentlichen Entscheidung passen. Deshalb ist menschliche Überprüfung unverhandelbar: KI kann den ersten Entwurf eines Protokolls generieren, aber ein Mensch muss vor dem Merge verifizieren, dass es die tatsächliche Entscheidung, Alternativen und Konsequenzen genau beschreibt.

Entscheidungsprotokolle als Teil einer breiteren Methodik

Entscheidungsprotokolle sind keine bloße Dokumentation – sie sind Teil einer breiteren Arbeitsweise, die an der Schnittstelle von leichter Architektur-Governance, Docs as Code, KI-augmentierten Wissensmanagement-Workflows, Produktentdeckung, Design-Reasoning, KI-Governance und Code-Review liegt. Eine nützliche Art, den größeren Prozess zu beschreiben, ist Entscheidungsorientierte Entwicklung (Decision-Oriented Development).

Die meisten KI-gesteuerten Programmier-Workflows konzentrieren sich eng auf den Generate-Review-Commit-Loop:

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

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

Entscheidungsprotokolle und Docs as Code

Entscheidungsprotokolle funktionieren am besten, wenn sie Docs-as-Code-Prinzipien folgen, was bedeutet, dass sie im selben Repository wie der Code gespeichert, in einfachem Markdown geschrieben, in Pull Requests geprüft, mit Git versioniert, mit verwandten Issues und Pull Requests verknüpft und von sowohl Menschen als auch KI-Tools durchsuchbar sein sollten. Dies ist viel zuverlässiger als das Speichern wichtiger Entscheidungen in Chats, Wiki-Seiten, Folienpräsentationen oder Meeting-Notizen – diese Tools können für Diskussionen noch nützlich sein, aber die akzeptierte Entscheidung sollte immer in der Nähe des Codes leben. Spezifikationen, Tests und Code in Einklang bringen in der KI-Entwicklung erweitert dieselbe „Verknüpfung zum Protokoll“-Gewohnheit in ein volles Nachvollziehbarkeitsmodell, das Anforderungs- und Designentscheidungs-IDs mit Tests und Pull Requests verknüpft.

Eine gut organisierte Repository-Struktur für Entscheidungsprotokolle 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 exakte Ordnerstruktur ist weniger wichtig als Konsistenz – die Protokolle müssen leicht zu finden, leicht zu prüfen und leicht für KI-Tools als Kontext zu laden sein, bevor sie auf die Codebasis einwirken. 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, und docs/ als Ort für Architektur-Entscheidungen und API-Referenzen empfiehlt.

Eine praktische Vorlage für Entscheidungsprotokolle

Eine nützliche Vorlage für Entscheidungsprotokolle sollte kurz genug sein, dass sie Menschen tatsächlich nutzen. Hier ist eine praktische Markdown-Vorlage, die einen optionalen, aber wertvollen Abschnitt für KI-Leitfäden enthält:

# Entscheidung: Kurzer Titel

Status: Vorgelegt | Akzeptiert | Ersetzt | Obsolet
Datum: YYYY-MM-DD
Typ: Architektur | Produkt | Design
Verantwortlich: Team oder Namen

## Kontext

Beschreiben Sie das Problem, Einschränkungen, Ziele, Nutzerbedürfnisse,
technische Fakten und Geschäftsfaktoren, die zu dieser Entscheidung führten.

## Entscheidung

Formulieren Sie die Entscheidung klar.

## Erwogene Alternativen

### Option 1

Pro:
- ...

Contra:
- ...

## Konsequenzen

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

## KI-Leitfaden

Wenn ein KI-Assistent in diesem Bereich arbeitet, sollte es:
- ... erhalten
- ... vermeiden
- ... bevorzugen
- ... bei ... um Prüfung bitten

## Links

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

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

Was gehört in ein Entscheidungsprotokoll?

Nicht jede Wahl verdient ein Protokoll, und wenn jedes kleine Implementierungsdetail zu einem Entscheidungsprotokoll wird, kollabiert der Prozess in Lärm. Erstellen Sie ein Entscheidungsprotokoll, wenn eine Wahl bedeutend ist und später wahrscheinlich wichtig sein wird.

Gute Kandidaten sind Entscheidungen, die:

• Mehrere Teile des Systems betreffen
• Ein Produktversprechen kodieren
• Eine echte Debatte lösen
• Einen langfristigen Kompromiss einführen
• Von geschäftlichen, Compliance- oder Betriebs-Einschränkungen abhängen
• Später teuer zu wiederentdecken wären
• Von zukünftigen KI-Tools plausibel falsch gedeutet werden könnten
• Zukünftige Mitwirkende dazu verleiten könnten, sie leichtfertig rückgängig zu machen

Schlechte Kandidaten umfassen kleine Refactoring-Entscheidungen, offensichtliche Bug-Fixes, temporäre Experimente, lokale Benennungsentscheidungen und Implementierungsdetails ohne dauerhafte Konsequenz. Eine gute Faustregel ist einfach: Wenn die Rückgängigmachung der Entscheidung eine Diskussion erfordert, dokumentieren Sie die Entscheidung.

Statuswerte und Lebenszyklus

Entscheidungsprotokolle sollten einen Lebenszyklus haben, um ihre aktuelle Stellung zu signalisieren. Die einfachsten Statuswerte sind ausreichend.

Vorgelegt — 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 dazu verpflichtet.

Akzeptiert — Die Entscheidung ist aktiv und sollte zukünftige Arbeit leiten. Die nützlichsten Entscheidungsprotokolle werden den Großteil ihres Lebens in diesem Zustand verbringen.

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

Obsolet — Die Entscheidung wird nicht mehr empfohlen, kann aber 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 Entscheidungsprotokolle anhängig-freundlich (append-friendly) sein sollten. Wenn das Team die Richtung ändert, erstellen Sie ein neues Protokoll und verlinken Sie das alte, anstatt die Historie umzuschreiben, damit die Vergangenheit sauberer aussieht.

Wie KI Entscheidungsprotokolle generieren sollte

KI kann helfen, Entscheidungsprotokolle zu erstellen, und dies ist einer der besseren Einsätze von KI in der Softwareentwicklung – sie ist schnell im Entwerfen strukturierter Dokumente aus dem Kontext. Nach einer Diskussion, Architekturprüfung oder einem Pull Request können Sie einen KI-Assistenten bitten, ein Protokoll zu entwerfen:

Entwirf ein Architektur-Entscheidungsprotokoll für die Entscheidung in diesem Pull Request.
Einschließen Kontext, Alternativen, Konsequenzen und KI-Leitfaden.
Speichere es als Markdown unter docs/decisions/architecture.

Für Produktarbeit:

Entwirf ein Produkt-Entscheidungsprotokoll, das erklärt, warum KI-generierte Nachrichten
Entwürfe bleiben müssen, bis sie von dem Nutzer geprüft wurden.
Einschließen Nutzereinfluss, Scope-Verhalten, Abwägungen und KI-Leitfaden.

Das KI-generierte Protokoll sollte jedoch nicht automatisch vertraut werden. Menschliche Prüfung sollte verifizieren, dass der Kontext genau ist, dass die KI keine Begründung erfunden hat, dass die aufgeführten Alternativen real sind, dass die Konsequenzen ehrlich sind und dass der KI-Leitfaden der tatsächlichen Absicht des Teams entspricht. KI ist ein Entwurfsassistent – sie ist nicht die Eigentümerin der Entscheidung.

Wie KI Entscheidungsprotokolle lesen sollte

Die andere Hälfte der Praxis ist, die KI zu beauftragen, die Protokolle 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 Funktionalität ändern, lesen Sie docs/decisions.
Identifizieren Sie alle Architektur-, Produkt- oder Design-Entscheidungsprotokolle, die sich anwenden.
Folgen Sie akzeptierten Entscheidungen. Wenn Ihr vorgeschlagener Konflikt mit einem
Entscheidungsprotokoll kollidiert, erklären Sie den Konflikt, bevor Sie Code ändern.

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

Verwenden Sie die Entscheidungsprotokolle als Projektgedächtnis.
Machen Sie keine akzeptierten Entscheidungen rückgängig, ohne eine neue ersetzende Entscheidung vorzuschlagen.
Wenn Sie Code generieren, erklären Sie, welche Entscheidungsprotokolle die Implementierung beeinflusst haben.

Dies ändert die Rolle der KI von „plausiblen Code vorhersagen“ zu „in einem dokumentierten System von Einschränkungen operieren“ – eine signifikante Verbesserung der Zuverlässigkeit für komplexe oder lang lebende Projekte.

Entscheidungsprotokolle in Pull Requests

Entscheidungsprotokolle sollten Teil der normalen Pull-Request-Prüfung sein, nicht ein separater Prozess. Ein einfacher PR-Checklisten-Eintrag macht die Gewohnheit sichtbar:

## Entscheidungsprotokoll-Checkliste

- [ ] Dieser PR führt keine signifikante Architektur-, Produkt- oder Designentscheidung ein.
- [ ] Dieser PR führt eine signifikante Entscheidung ein und enthält ein neues Entscheidungsprotokoll.
- [ ] Dieser PR ändert eine frühere Entscheidung und enthält ein ersetzendes Protokoll.
- [ ] Relevante bestehende Entscheidungsprotokolle wurden berücksichtigt.
- [ ] KI-generierter Code folgt den akzeptierten Entscheidungsprotokollen.
- [ ] KI-generierte Entscheidungsprotokolle wurden von einem Menschen geprüft.

Diese Checkliste ist einfach, aber sie verändert das Verhalten, indem sie das Team daran erinnert, dass Code nicht das einzige Artefakt ist, das in einem Pull Request wichtig ist. Sie macht es auch natürlich, festzustellen, wenn eine KI-generierte Änderung unauffällig eine frühere Entscheidung verletzt.

Entscheidungsprotokolle und Architektur-Governance

Traditionelle Architektur-Governance scheitert oft, weil sie zu schwer, zu langsam oder zu disconnected von der Implementierung ist – zentrale Genehmigungsgremien, große Vorab-Dokumente und Gatekeeping-Prozesse, die blockieren statt leiten. Entscheidungsprotokolle bieten eine leichtere Alternative, die sich direkt in den Entwicklungs-Workflow integriert.

Sie erfordern kein zentrales Architektur-Gremium für jede Änderung, noch blockieren sie Teams davon, zu lernen und sich anzupassen. Stattdessen schaffen sie eine Spur von Entscheidungen, die über die Zeit geprüft, referenziert und weitergebaut werden kann. Dies unterstützt evolutionäre Architektur: Die Architektur kann sich ändern, aber sie ändert sich mit Gedächtnis, nicht trotz davon. Das Team kann alte Entscheidungen wieder aufgreifen, ohne neu entdecken zu müssen, warum sie getroffen wurden, was eine gesündere und ehrlichere Form der Governance ist:

• Kleine Protokolle anstelle von riesigen Dokumenten
• Prüfung nahe am Code anstelle von separater Genehmigungstheater
• Historischer Kontext anstelle von tribalem Wissen
• Explizite Abwägungen anstelle von versteckten Annahmen

Entscheidungsprotokolle und Produktmanagement

Produktarbeit benötigt auch Entscheidungs-Gedächtnis, und dies ist ein Bereich, in dem der Wert von Entscheidungsprotokollen oft unterschätzt wird. Eine Roadmap sagt, was passieren könnte. Ein Ticket sagt, was als Nächstes gebaut wird. Analytics sagen, was Nutzer getan haben. Keines davon erklärt vollständig, warum ein Produktverhalten existiert.

Produkt-Entscheidungsprotokolle füllen diese Lücke und sind besonders nützlich für Preis- und Paketierungsentscheidungen, Berechtigungsmodelle, Limits und Quotas, KI-Sicherheit und Review-Flows, Onboarding-Wahlen, Definitionen von Nutzerrollen, Kollaborationsregeln, Daten-Retention-Politiken und Feature-Scope-Grenzen. 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 nutzen können.

Entscheidungsprotokolle und Design-Systeme

Design-Systeme dokumentieren oft Komponenten, Tokens und Nutzungsregeln, aber selten, warum das System so funktioniert. Design-Entscheidungsprotokolle 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 geteilten Teamedaten arbeiten, und versehentliches Löschen eine 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 Bestätigung überspringt, weil sie effizienter erscheint. Mit dem DDR kann der Agent erkennen, dass das Erhalten der Sicherheitseigenschaft absichtlich und unverhandelbar ist.

Wie Entscheidungsprotokolle spec-gesteuerte Entwicklung unterstützen

Spec-gesteuerte Entwicklung erklärt, was das System tun sollte. Entscheidungsprotokolle erklären, warum das Team diese Richtung wählte, und die Unterscheidung ist für KI-gestützte Arbeit signifikant.

Eine Featurespezifikation kann sagen, dass KI-generierte E-Mails als Entwürfe gespeichert werden müssen. Ein Produkt-Entscheidungsprotokoll erklärt, warum automatisches Senden abgelehnt wurde, welche Risiken erwogen wurden und welche zukünftigen Änderungen eine neue Entscheidung erfordern würden. Eine Design-Spezifikation kann eine Side-Panel-Interaktion beschreiben, während das entsprechende DDR erklärt, warum Inline-KI-Edits explizit abgelehnt wurden und warum die Erhaltung der Nutzerkontrolle höher gewichtet wurde als Workflow-Geschwindigkeit. Eine Architektur-Spezifikation kann eine Servicegrenze definieren, und ihr ADR erklärt, warum das Team diese Grenze einem einfacheren oder verteilten Alternativen vorzog.

Die Spezifikation leitet die Implementierung. Das Entscheidungsprotokoll erhält das Urteil. Zusammen geben sie KI-Coding-Agenten sowohl Anweisungen als auch Kontext – das „Was“ und das „Warum“ – was die Kombination für komplexe, lang lebende Systeme so effektiv macht. Wenn Sie einen spec-gesteuerten Toolchain adoptieren, vergleichen Sie, wie jede Option diesen Kontext darstellt; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows bricht Portabilität, Review-Gates und Repository-Verankerung über die Hauptsetups auf. Für den tool-neutralen Fünf-Phasen-Prozess, den diese Tools implementieren, sehen Sie Spec-Driven Development Workflow Von Anforderungen bis Code. Die meisten SDD-Tools behandeln nur die „gelieferte“ Hälfte dieses Loops sauber; OpenSpec Abgelehnte Vorschläge: Eine Entscheidungs-Gedächtnis-Konvention deckt die andere Hälfte ab – das dauerhafte Aufzeichnen einer abgelehnten Entscheidung, damit ein Agent sie prüft, bevor er denselben Gedanken erneut vorschlägt.

Entscheidungsprotokolle sind keine Spezifikationen

Entscheidungsprotokolle sind mit Spezifikationen verwandt, dienen aber einem anderen Zweck. Eine Spezifikation sagt „das System soll X tun“, während ein Entscheidungsprotokoll sagt „wir wählten X anstelle von Y wegen dieser Einschränkungen und Abwägungen.“ Das „anstelle von Y“ ist der wertvolle Teil. KI-Tools generieren oft Lösungen, indem sie einen plausiblen Pfad zum gewünschten Ergebnis finden, aber Entscheidungsprotokolle sagen ihnen, welche plausiblen Pfade bereits erkundet, bewertet und abgelehnt wurden – was Reibungsverluste reduziert und die Qualität der KI-gestützten Arbeit verbessert.

Entscheidungsprotokolle sind kein Ersatz für Tests

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

Entscheidungsprotokolle sind kein Ersatz für Code-Kommentare

Code-Kommentare erklären lokale Implementierungsdetails, während Entscheidungsprotokolle breitere Entscheidungen erklären. Verwenden Sie Kommentare für überraschende Zeilen, Edge Cases, Workarounds und Funktionen, die nicht vereinfacht werden können. Verwenden Sie Entscheidungsprotokolle dafür, warum eine Architektur existiert, warum ein Produktverhalten existiert, warum ein Interaktionsmuster existiert und warum das Team eine Richtung der anderen vorzog. Wenn die Erklärung nur ein paar Zeilen betrifft, ist ein Kommentar das richtige Werkzeug. Wenn sie die Richtung des Systems betrifft, ist ein Entscheidungsprotokoll das richtige Werkzeug.

Häufige Fehler

Protokolle zu spät schreiben

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

Protokolle zu lang machen

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

Entscheidungen ohne Konsequenzen aufzeichnen

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

Alte Protokolle bearbeiten, als ob die Historie sich änderte

Wenn sich eine Entscheidung ändert, erstellen Sie ein neues Protokoll und markieren Sie das alte als ersetzt. Stilles Umschreiben einer alten Entscheidung, um den aktuellen Zustand zu spiegeln, zerstört den historischen Kontext, der Entscheidungsprotokolle wertvoll macht. Historie ist nützlich, gerade weil sie zeigt, wie sich das Denken entwickelt hat. Kompilierte Wissensbasen haben dasselbe Problem unter einem anderen Namen – LLM Wiki Wartung: Drift, Widersprüche und Review nennt es Entscheidungsdrift und wendet die gleiche „ersetzen statt überschreiben“-Regel auf Wiki-Seiten an.

KI-generierte Protokolle mergen lassen, ohne Prüfung

KI kann ein poliertes, gut strukturiertes Protokoll erzeugen, das subtile Fehler enthält. Behandle KI-generierte Entscheidungsprotokolle genau wie KI-generierten Code – prüfe sie sorgfältig, verifiziere, dass die Begründung genau ist, und stelle sicher, dass der Konsequenzen-Abschnitt widerspiegelt, was das Team tatsächlich akzeptiert hat.

Protokolle außerhalb des Repository verstecken

Wenn Entscheidungsprotokolle in einem separaten Wiki oder Dokumentationssystem leben, werden sie seltener neben Codeänderungen aktualisiert und viel seltener von KI-Coding-Tools gelesen, die Kontext für eine Aufgabe laden. Sie im Repository zu halten ist nicht nur eine Bequemlichkeit – es ist das, was die Praxis für KI-gestützte Entwicklung funktionieren lässt.

Ein leichtes Betriebsmodell

Ein praktischer Teamprozess, der minimale Overhead erzeugt, sieht so aus:

1. Identifizieren Sie während der Planung oder Implementierung, ob eine bedeutende Entscheidung getroffen wird.
2. Bitten Sie einen KI-Assistenten, ein ADR, PDR oder DDR basierend auf der Diskussion zu entwerfen.
3. Prüfen Sie den Entwurf als Team, indem Sie Kontext, Alternativen und Konsequenzen verifizieren.
4. Committen Sie das Protokoll als Markdown im Repository.
5. Verlinken Sie es vom verwandten Issue oder Pull Request.
6. Weisen Sie KI-Coding-Tools an, relevante Protokolle zu lesen, bevor sie zukünftige Änderungen in dem Bereich vornehmen.
7. Ersetzen Sie Protokolle, wenn sich Entscheidungen ändern, und behalten Sie das alte Protokoll für die Historie.

Dies erfordert keine neue Bürokratie oder eine dedizierte Dokumentationsrolle. Es erfordert eine kleine Gewohnheit: Wichtiges Urteil im Moment seiner Entstehung zu erhalten, nahe am Code, wo es benötigt wird.

Beispiel ADR

# Entscheidung: Verwendung von PostgreSQL für primäre Anwendungsstorage

Status: Akzeptiert
Datum: 25.06.2026
Typ: Architektur
Verantwortlich: Plattform-Team

## Kontext

Die Anwendung benötigt dauerhaften relationalen Speicher für Konten, Projekte,
Berechtigungen und Audit-Events. Das Team erwartet häufige Reportabfragen
und strenge Konsistenzanforderungen für Berechtigungsprüfungen.

## Entscheidung

Wir werden PostgreSQL als primäre Anwendungsdatenbank verwenden.

## Erwogene Alternativen

### DynamoDB

Pro:
- Betriebsskalierbar
- Gute Passform für vorhersehbare Key-Value-Zugriffsmuster

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

### MySQL

Pro:
- Reife relationale Datenbank
- Vertrautes Betriebsmodell

Contra:
- PostgreSQL passt besser zu den Bedürfnissen des Teams für JSON-Unterstützung,
  Indexierungsoptionen und bestehende Expertise

## Konsequenzen

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

## KI-Leitfaden

Wenn Sie Persistenzcode ändern, 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 Entwürfe bleiben

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

## Kontext

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

## Entscheidung

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

## Erwogene Alternativen

### Automatisches Senden

Pro:
- Schnellerer Workflow
- Weniger Nutzeranstrengung

Contra:
- Hohes Risiko für unkorrekte oder unangemessene Nachrichten
- Niedrigeres Nutzervertrauen
- Schwerer, sich von Fehlern zu erholen

### Nur Bestätigung nach Generierung anfragen

Pro:
- Hält den Workflow einfach
- Bietet einige Nutzerkontrolle

Contra:
- Ermutigt immer noch flache Prüfung
- Passt nicht so gut zum bestehenden E-Mail-Client-Verhalten wie Entwürfe

## Konsequenzen

Der Workflow ist etwas langsamer, aber sicherer und vertrauenswürdiger.
Zukünftige Automatisierung kann die Prüfgeschwindigkeit verbessern, aber
muss menschliche Genehmigung nicht umgehen, ohne ein ersetzendes PDR.

## KI-Leitfaden

Wenn Sie E-Mail-Generierungsfeatures bauen, erstellen Sie Standardmäßig Entwürfe.
Fügen Sie kein automatisches Senden hinzu, außer ein neues akzeptiertes PDR erlaubt es explizit.

Beispiel DDR

# Entscheidung: Anzeige von KI-Schreibvorschlägen in einem Seitenpanel

Status: Akzeptiert
Datum: 25.06.2026
Typ: Design
Verantwortlich: Designteam

## Kontext

Nutzer brauchen Hilfe, schriftliche Inhalte zu verbessern, aber sie müssen auch
die Kontrolle über den finalen Text behalten. Inline-KI-Edits können es schwer
machen, zwischen nutzergeschriebenem Inhalt und generierten Vorschlägen zu
unterscheiden.

## Entscheidung

KI-Schreibvorschläge werden in einem Seitenpanel angezeigt. Nutzer können
Vorschläge akzeptieren, ablehnen oder in den Haupteditor kopieren.

## Erwogene Alternativen

### Vorschläge inline anwenden

Pro:
- Schnell
- Fühlt sich integriert an

Contra:
- Verwischt die Autorenschaft
- Macht die Prüfung schwerer
- Kann Nutzer überraschen

### Vorschläge in einem Modal anzeigen

Pro:
- Fokussiertes Erlebnis
- Leicht zu implementieren

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

## Konsequenzen

Das Seitenpanel benötigt mehr Bildschirmplatz, besonders auf kleinen Bildschirmen.
Allerdings erhält es die Nutzerkontrolle und macht die Prüfung klarer.

## KI-Leitfaden

Wenn Sie Schreibassistenz-Features hinzufügen, erhalten Sie die Trennung zwischen
Nutzertext und KI-Vorschlägen. Wenden Sie generierten Text nicht direkt
in das Dokument an, ohne explizite Nutzeraktion.

Empfohlene Prompt-Bibliothek

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

Relevante Protokolle identifizieren, bevor man an einem Feature arbeitet:

Lesen Sie docs/decisions und identifizieren Sie alle akzeptierten Entscheidungsprotokolle,
die sich auf diese Aufgabe anwenden. Fassen Sie die Einschränkungen zusammen,
bevor Sie Codeänderungen vorschlagen.

Ein neues ADR entwerfen:

Entwirf ein Architektur-Entscheidungsprotokoll für diese technische Entscheidung.
Einschließen Kontext, Entscheidung, Alternativen, Konsequenzen und KI-Leitfaden.
Halte es konzise und spezifisch.

Ein neues PDR entwerfen:

Entwirf ein Produkt-Entscheidungsprotokoll für dieses Produktverhalten.
Einschließen Nutzereinfluss, Scope, Alternativen, Konsequenzen und KI-Leitfaden.

Ein neues DDR entwerfen:

Entwirf ein Design-Entscheidungsprotokoll für dieses Interaktionsmuster.
Einschließen Nutzerproblem, Alternativen, Abwägungen, Konsequenzen und KI-Leitfaden.

Einen Pull Request gegen bestehende Entscheidungen prüfen:

Prüfe diesen Pull Request gegen die akzeptierten Entscheidungsprotokolle in docs/decisions.
Identifiziere alle Konflikte, fehlende Entscheidungsprotokolle oder Entscheidungen,
die ersetzt werden sollten.

Eine Entscheidung ersetzen:

Erstelle ein neues Entscheidungsprotokoll, das das bestehende ersetzt.
Erhalte die historische Begründung, erkläre, was sich geändert hat, und verlinke beide Protokolle.

Verwandte Lektüre

• Michael Nygards ursprüngliches ADR-Format — der grundlegenden Post, der die ADR-Bewegung startete
• ADR GitHub Organisation — Tooling, Vorlagen und Community-Ressourcen für die Verwaltung von Entscheidungsprotokollen
• Was ist Spec-Driven Development? Die Spezifikation als Quelle der Wahrheit — die kanonische SDD-Definition, die erklärt, wie Featurespezifikationen Entscheidungsprotokolle ergänzen: Beide machen Absicht dauerhaft, auf verschiedenen Systemebenen
• Spec-Driven Development vs Vibe Coding: Wasserfall? — wann man SDD verwendet und wann man bei schnelleren, lockereren Workflows bleibt
• App Architektur in Produktion: Integrationsmuster, Code-Design und Datenzugriff — der Cluster-Heimatbereich, der Integration, Testing, Datenzugriff und Software-Dokumentationsmuster abdeckt
• OpenSpec Abgelehnte Vorschläge: Eine Entscheidungs-Gedächtnis-Konvention — das Anwenden dieses Entscheidungsprotokoll-Musters spezifisch innerhalb des OpenSpec-Änderungsarchivs
• KI für Wissensmanagement: Echte Workflows, die halten — praktische KI-augmentierte Wissens-Workflows, die die Entscheidungsprotokoll-Praxis ergänzen