# Entscheidungen mit Geschichte URL: https://www.mikebild.dev/de/blog/entscheidungen-mit-geschichte/ Sechs Monate nach einem Architekturmeeting ist die Entscheidung noch im Code sichtbar, ihre Begründung nicht. Jemand schlägt erneut eine bereits verworfene Alternative vor. In diesem konstruierten Beispiel existiert das Meeting-Protokoll, aber die entscheidende Aussage liegt zwischen vielen anderen Gesprächsnotizen. WikiKit führt Entscheidungen deshalb als eigene, geprüfte Wissensobjekte im Decision Log. Sie enthalten Kontext, getroffene Entscheidung, Begründung und verworfene Alternativen. Wissensänderungen durchlaufen als ChangeProposal eine menschliche Prüfung. Ein Claim kann den aktuell geltenden Sachverhalt festhalten; die Entscheidung dokumentiert zusätzlich, unter welchen Bedingungen und aus welchen Gründen eine Wahl getroffen wurde. Stand August 2026 beschreibt dieser Text WikiKit 0.47.1. ## Eine Entscheidung beantwortet eine andere Frage Im folgenden fiktiven Beispiel hält der Claim `wikikit-production / primary_database / PostgreSQL` den belegten aktuellen Stand fest. Die Entscheidung `use-postgresql-as-primary-store` erklärt zusätzlich, unter welchen Anforderungen diese Wahl getroffen wurde und welche Alternativen erwogen wurden. ```json { "slug": "use-postgresql-as-primary-store", "title": "Use PostgreSQL as the primary store", "context": "Proposal review requires atomic visibility and searchable revisions.", "decision": "Use PostgreSQL as the production source of truth.", "rationale": "Transactions, full-text search, and advisory locks cover the required behavior.", "alternatives": [ "Markdown files as the primary store", "SQLite per process" ] } ``` In diesem fiktiven Modellierungsbeispiel gehören Claim und Entscheidung fachlich zusammen, beantworten aber unterschiedliche Fragen. Wer nur den geltenden Konfigurationsstand benötigt, kommt möglicherweise mit dem Claim aus. Für ein Architekturreview ist zusätzlich die Entscheidung relevant, weil sonst offenbleibt, ob die damaligen Anforderungen noch gelten. Ein separater Claim ist sinnvoll, wenn neben der Begründung auch ein aktueller, separat belegbarer Sachverhalt festgehalten werden soll. ```mermaid flowchart LR S["Quelle und Herkunft"] --> P["ChangeProposal"] P --> R{"menschliche Prüfung"} R -->|freigegeben| D["Entscheidung
Kontext · Wahl · Begründung · Alternativen"] D -.-> C["im Beispiel optionaler Claim
aktueller Stand"] D --> H["Revision und Historie"] ``` ## Kontext begrenzt die Aussage Eine Entscheidung ohne Kontext wirkt universeller, als sie gemeint ist. „Use PostgreSQL“ verrät nicht, für welches System, welche Umgebung oder welche Anforderungen die Wahl gilt. Der Kontext trennt die Situation und die Anforderungen von der anschließend dokumentierten Begründung: ```text Context: The service needs atomic proposal activation, revision history, full-text search, and multiple concurrent reviewers. Decision: Use PostgreSQL as the production source of truth. ``` Die Entscheidung gilt damit nicht automatisch für jedes lokale Werkzeug. Wenn eine Variante andere Anforderungen hat, braucht sie einen eigenen Geltungsbereich und gegebenenfalls eine eigene Entscheidung. Der dokumentierte Kontext schafft eine Grundlage für spätere Neubewertungen. Fallen Anforderungen weg oder kommen neue hinzu, lässt sich prüfen, ob die vorhandene Begründung noch trägt. ## Alternativen dokumentieren die geprüften Optionen Eine Liste verworfener Alternativen dokumentiert, welche Wege ernsthaft erwogen wurden und weshalb sie nicht gewählt wurden. Eine vollständige Marktanalyse ist dafür nicht erforderlich. Das folgende Fragment zeigt eine mögliche redaktionelle Darstellung, kein zugesichertes WikiKit-Schema: ```json { "alternative": "Markdown files as the primary store", "reason_rejected": "Concurrent atomic proposal activation would require additional coordination." } ``` Gründe dürfen nur übernommen werden, wenn die Quelle sie trägt. Ein nachträglich aus allgemeinem Architekturwissen ergänzter Ablehnungsgrund würde die historische Entscheidung verfälschen. Eine verworfene Alternative kann unter geänderten Bedingungen später sinnvoll werden. Die frühere Entscheidung bleibt dennoch relevant: Sie dokumentiert die damalige Wahl und ihre Voraussetzungen. Eine spätere Revision oder neue Entscheidung muss die geänderte Grundlage nachvollziehbar machen. ## Freigegebene Entscheidungen behalten ihre Historie Eine Architekturwahl darf nicht so überschrieben werden, als habe die frühere Fassung nie existiert. WikiKit bewahrt bei freigegebenen Revisionen Herkunft und Historie. Dadurch bleibt nachvollziehbar, auf welcher Grundlage eine Wissensänderung geprüft wurde. ```mermaid flowchart LR S1["Quelle für frühere Fassung"] --> R1["freigegebene Revision"] R1 --> H["Historie"] S2["neue Quelle"] --> P["neues ChangeProposal"] R1 --> P P --> R2["später freigegebene Revision"] R2 --> H ``` Die gespeicherte Herkunft und Revisionshistorie zeigen, welche freigegebene Fassung aus welcher Wissensänderung hervorging. Weitergehende Fragen – etwa wer eine bestimmte Alternative erneut bewertete – lassen sich nur beantworten, wenn die zugehörigen Quellen diese Information tatsächlich enthalten. Ein Rollback der Software ändert den dokumentierten Wissensstand nicht von selbst. Wenn dadurch fachlich wieder eine frühere Regel gelten soll, braucht auch diese Wissensänderung eine nachvollziehbare Prüfung. ## Entscheidungen über REST und MCP lesen WikiKit bietet getrennte REST- und MCP-Lesewege für Entscheidungen. Anwendungen und Agenten können damit freigegebenes Entscheidungswissen lesen. Die menschliche Freigabe bleibt davon getrennt und ist eine eigene, auditierbare Handlung. Eine Entscheidung wird erst durch diese Freigabe verbindlich. Diese Trennung ist für Architekturarbeit wichtiger als ein bestimmter Toolname oder API-Pfad. Solche Schnittstellendetails können sich ändern, während die Verantwortungsgrenze bestehen bleibt: Lesen lässt sich automatisieren, die fachliche Freigabe nicht stillschweigend ersetzen. ## Die Prüfung konzentriert sich auf Entscheidungstreue Bei der Prüfung einer Entscheidung stellen sich andere Fragen als bei einem normalen Claim: - Wurde tatsächlich entschieden oder nur eine Möglichkeit diskutiert? - Deckt der Kontext den beabsichtigten Geltungsbereich ab? - Ist die Begründung durch die angegebenen Quellen gedeckt? - Sind die genannten Alternativen dort tatsächlich dokumentiert? - Gibt es zugehörige Claims, und widersprechen sie der Entscheidung? Eine Review-Notiz kann eine notwendige Präzisierung benennen. Das folgende Fragment ist nur ein redaktionelles Beispiel und kein zugesichertes API-Payload: ```json { "decision": "approve", "note": "Geltungsbereich anhand der angegebenen Quelle auf den Produktionsdienst begrenzt." } ``` Die Prüfnotiz darf keine neue fachliche Tatsache einführen, die weder in der Entscheidung noch in ihrer Quelle steht. Fehlt ein Beleg, muss der Änderungsvorschlag enger formuliert oder durch eine passende Quelle ergänzt werden. ## Ein Report dokumentiert noch keine Entscheidung Ein Report hält eine zeitgebundene Auswertung fest. Ein Finding beschreibt eine Beobachtung. Beides belegt noch nicht, dass eine verbindliche Wahl getroffen wurde. Die Aussage „In zwei Auswertungsfenstern fehlten Nutzungsdaten“ wäre ein Finding. „Wir ersetzen deshalb den Analyseanbieter“ wäre dagegen eine Entscheidung und dürfte nicht automatisch aus der Beobachtung abgeleitet werden. Soll der Inhalt eines Berichts oder Protokolls als Entscheidung festgehalten werden, muss er als ChangeProposal eingereicht und anschließend von einem Menschen geprüft und freigegeben werden. ## Hypothetisches Modellierungsbeispiel: öffentliche MCP-Clients Angenommen, ein Architekturteam beschließt, dass öffentliche MCP-Clients OAuth verwenden und keine langlebigen WikiKit-Schlüssel erhalten. Die zugrunde liegende Quelle nennt den Sicherheitsgrund und zwei verworfene Alternativen. Der Inhalt einer vorgeschlagenen Entscheidung könnte so aussehen: ```text source: architecture meeting notes proposed decision: public MCP clients use OAuth possible related claim: wikikit-public-mcp / authentication / OAuth 2.1 rejected alternatives: long-lived API key in the client anonymous read-only access ``` Dieses Beispiel beschreibt eine mögliche Modellierung, keine automatische Meeting-Verarbeitung. Eine prüfende Person müsste kontrollieren, ob die OAuth-Wahl tatsächlich beschlossen wurde, ob der Geltungsbereich nur öffentliche Clients betrifft und ob die genannten Alternativen in der Quelle stehen. Erst ein freigegebener ChangeProposal macht die Wissensänderung verbindlich. Danach kann die Entscheidung über den REST- oder MCP-Leseweg abgerufen werden. Im Beispiel ist der zugehörige Claim optional. Unterstützt eine neue Clientplattform später einen anderen sicheren Mechanismus, darf die frühere Begründung nicht still umgeschrieben werden. Die geänderte Wahl braucht erneut Kontext, Begründung, Quellen und menschliche Freigabe. ## Claims und Entscheidungen müssen zusammenpassen Ein Claim hält fest, was nach dem belegten Wissensstand gilt. Die Entscheidung erklärt, warum eine Wahl unter bestimmten Bedingungen getroffen wurde. In den Modellierungsbeispielen dieses Texts wird keine feste Eins-zu-eins-Zuordnung vorausgesetzt. Das ist eine redaktionelle Modellierungsannahme, keine Aussage über eine von WikiKit erzwungene Kardinalität. Wo beide Objekte zusammengehören, sollten Reviewer ihre Zuordnung prüfen. Das folgende Fragment veranschaulicht die fachliche Beziehung, ohne ein konkretes WikiKit-Schema zu behaupten: ```json { "decision": "use-oauth-for-public-mcp", "related_claim": { "subject": "wikikit-public-mcp", "predicate": "authentication", "object": "OAuth 2.1" } } ``` Bei einer späteren Änderung müssen die betroffenen Wissensobjekte inhaltlich konsistent bleiben. Andernfalls könnte ein Claim noch eine alte Regel nennen, während die neuere Entscheidung bereits andere Voraussetzungen dokumentiert. Für das Review sollten die vorgeschlagene Entscheidung und betroffene Claim-Änderungen gemeinsam betrachtet werden, sofern beides zum selben fachlichen Änderungsvorhaben gehört. Daraus folgt weder eine gemeinsame Darstellung in WikiKit noch eine atomare Aktivierung. ## Vom ADR zum Decision Log Der Artikel [ADR: Entscheidungen, die man versteht](https://www.mikebild.dev/de/blog/adr-entscheidungen-die-man-versteht/) erklärt, weshalb Architekturentscheidungen Kontext, Wahl und Konsequenzen festhalten sollten. Eine Markdown-Datei im Repository ist dafür weiterhin ein brauchbarer Speicherort und lässt sich wie Code reviewen. WikiKit behandelt Entscheidungen darüber hinaus als eigene Wissensobjekte. Sie durchlaufen als ChangeProposal eine menschliche Freigabe und sind nach der Freigabe über getrennte REST- und MCP-Lesewege zugänglich. Herkunft und Historie der freigegebenen Revisionen bleiben erhalten. Damit verschiebt sich nicht die fachliche Verantwortung. Das System strukturiert und versioniert das Entscheidungswissen; es entscheidet nicht selbst, welche Architekturwahl verbindlich sein soll. ## Der Entscheidungstext muss eine spätere Prüfung tragen Lange Meetingtranskripte oder Berichte können Quellen bleiben. Der eigentliche Entscheidungseintrag konzentriert sich auf Wahl, Kontext, Begründung und ernsthaft erwogene Alternativen. Eine vollständige Gesprächswiedergabe erschwert das Wiederfinden. Ein einzelnes Stichwort wie „PostgreSQL“ lässt dagegen die entscheidenden Gründe weg. Für den Umfang zählt deshalb eine praktische Frage: Kann eine Person anhand des Eintrags verstehen, weshalb die Wahl unter den dokumentierten Bedingungen vernünftig war und welche Änderungen eine Neubewertung auslösen würden? Wenn der Text das leistet, bewahrt er mehr als das Ergebnis. Er erhält die Grundlage, auf der spätere Architekturarbeit aufbauen oder einer früheren Entscheidung begründet widersprechen kann. ## Weiterführende Quellen - [WikiKit README, geprüfter Repository-Stand](https://github.com/MikeBild/wikikit/blob/3da2c47f482ff843f849f504257467282a7d9363/README.md) - [WikiKit Cockpit-Dokumentation, geprüfter Repository-Stand](https://github.com/MikeBild/wikikit/blob/3da2c47f482ff843f849f504257467282a7d9363/docs/COCKPIT.md) - [WikiKit LLM-Dokumentation, geprüfter Repository-Stand](https://github.com/MikeBild/wikikit/blob/3da2c47f482ff843f849f504257467282a7d9363/docs/llms.txt) - [WikiKit Coding-Agent-Integration, geprüfter Repository-Stand](https://github.com/MikeBild/wikikit/blob/3da2c47f482ff843f849f504257467282a7d9363/docs/coding-agent-integration.md) - [ADR: Entscheidungen, die man versteht](https://www.mikebild.dev/de/blog/adr-entscheidungen-die-man-versteht/) - [Documenting Architecture Decisions – Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [PostgreSQL Transaction Isolation](https://www.postgresql.org/docs/current/transaction-iso.html)