decision-graph

Englisch · Tiếng Việt

Entscheidungsgedächtnis für Codebasen, an denen KI-Agenten arbeiten.

Ein Codegraph sagt dir, was der Code tut. decision-graph sagt dir, warum er so ist — wann eine Geschäftsregel auftauchte, wer sie entschieden hat, welche Alternativen verworfen wurden und ob die Entscheidung noch gilt.

git blame liefert eine Commit-Nachricht. Es sagt dir nicht, dass der CTO eines Kunden in einem Meeting eine zweite Genehmigungsstufe verlangt hat, dass ein separates Modul erwogen und als nicht zusammenführbar verworfen wurde oder dass der Schwellenwert sechs Monate später von jemand anderem gesenkt wurde.

Sprach- und frameworkunabhängig. Funktioniert in jedem Repository.

Warum

Der Schmerz ist am größten, wenn ein Basisprodukt pro Kunde erweitert wird – aber er zeigt sich überall dort, wo sich Geschäftslogik ansammelt:

• Ein Agent „verbessert“ eine Regel, die für einen Mandanten absichtlich so geschrieben wurde.

• Niemand erinnert sich, ob ein seltsam aussehender Zweig ein Fehler oder eine Anforderung ist.

• Derselbe verworfene Ansatz wird alle paar Monate erneut vorgeschlagen.

• Entscheidungen leben in Slack-Threads, Ticket-Kommentaren und in den Köpfen der Menschen.

KI-Agenten machen das schlimmer, weil sie kein implizites Gedächtnis für die letzten sechs Monate an Besprechungen haben – aber sie werden einem schriftlichen Protokoll folgen, wenn eines existiert.

Related MCP server: MCP Memory Server

Designprinzipien

• Markdown ist die Quelle der Wahrheit. Eine .md-Datei pro Entscheidung, in git, in einem PR überprüfbar.

• SQLite ist nur ein Index. Lösche decisions/_index/ und baue es jederzeit neu auf.

• Agenten dürfen decided_by nicht erfinden. Ein Agent kann nur einen draft erstellen; das Hochstufen auf active erfordert einen Menschen.

• Aufzeichnen ist ein Nebeneffekt des Codierens, keine lästige Pflicht – Hooks erinnern im richtigen Moment.

• Erkennung liest git, nicht Tool-Ereignisse. Mit sed, Heredocs, git apply oder einem einfachen Editor vorgenommene Änderungen werden genauso erkannt wie Edit/Write-Toolaufrufe.

Installation

Noch nicht auf PyPI – direkt von GitHub installieren:

uv tool install "decision-graph[mcp] @ git+https://github.com/vietqtran/decision-graph"

# pipx
pipx install "decision-graph[mcp] @ git+https://github.com/vietqtran/decision-graph"

# one-off, no install
uvx --from "git+https://github.com/vietqtran/decision-graph" decision-graph --help

# local development
git clone https://github.com/vietqtran/decision-graph && cd decision-graph
uv venv && uv pip install -e ".[mcp]"

Erfordert Python 3.10+ und einen SQLite-Build mit FTS5 (Standard auf macOS, Debian/Ubuntu und den offiziellen Python-Images).

Schnellstart

cd /path/to/your/repo
decision-graph init

decision-graph add --scope acme --module deals/approval \
  --title "Second approval tier for deals over 500M" \
  --file src/approval.py --tag override-base --stdin < body.md

# a human confirms who decided — the agent cannot do this step
decision-graph confirm acme-2026-08-26-second-approval-tier --by "Jane Doe (CTO, Acme)"

decision-graph search "two-tier approval" --scope acme
decision-graph history src/approval.py   # every decision that touched this file
decision-graph overlay acme              # how acme differs from base, and why

Kernkonzept: scope

scope ist die Achse, die Kontexte trennt – einen Kunden, eine Produktlinie, ein Team oder _base für Entscheidungen, die überall gelten.

Die Filterung nach scope erfolgt vor der Volltextsuche, was verhindert, dass die Regeln eines Mandanten in Antworten zu einem anderen einfließen. In einem Repository, das viele Kunden bedient, ist dies das mit Abstand wichtigste Feld.

Layout

decisions/
  _template.md
  _base/                          # applies to every scope
  acme/2026-08-26-approval.md
  viettel/2026-05-20-inventory.md
  _index/decisions.db             # generated — gitignored
.decision-graph.yml               # per-repo watch/ignore patterns

Die Frontmatter eines Datensatzes:

id: acme-2026-08-26-second-approval-tier
scope: acme
module: deals/approval
title: "Second approval tier for deals over 500M"
status: active                 # draft | active | superseded | deprecated
lifecycle_stage: maintenance   # design | dev | uat | golive | maintenance
supersedes: acme-2026-03-12-single-tier
decided_by: "Jane Doe (CTO, Acme)"
requested_by: "John Smith (PM)"
decided_at: 2026-08-26
linked_files: [src/approval.py]
linked_commit: 8f3a2c1
session_id: abc-123            # agent session that produced the change
ticket: JIRA-482
tags: [approval, override-base]

Der Text folgt decisions/_template.md: Kontext / Alternativen erwogen / Entscheidung / Auswirkung / Offene Risiken.

Alternativen erwogen ist für Agenten wichtiger als für Menschen – es verhindert, dass ein Agent den bereits verworfenen Ansatz erneut vorschlägt.

supersedes verkettet Datensätze, anstatt sie zu löschen, sodass der Prüfpfad erhalten bleibt.

Suche

Zuerst Metadatenfilter (scope, module, status, lifecycle_stage, file, tag), dann SQLite-FTS5-Ranking. Diakritika werden gefaltet, sodass duyet don hang mit Duyệt đơn hàng übereinstimmt.

decision-graph search "approval"                    # active decisions only, by default
decision-graph search --scope acme --status any
decision-graph search --file src/approval.py
decision-graph search "pricing" --tag override-base --json

Agentenintegration

Welcher Trigger verwendet werden soll

Beides zu installieren ist in Ordnung; jeder wird still, sobald eine Entscheidung aufgezeichnet ist.

Claude-Code-Hooks

decision-graph hooks install --target /path/to/repo

• PostToolUse(Edit|Write|MultiEdit) zeichnet auf, welche Dateien eine Sitzung berührt hat.

• Stop prüft git plus diesen Datensatz. Wenn geschäftsrelevante Dateien geändert wurden und keine Entscheidung geschrieben wurde, gibt es decision: "block" mit Anweisungen zurück – der Agent muss handeln, statt abzuschließen.

Der Agent hat genau zwei Auswege:

decision-graph skip --session <id> --reason "renamed variables only"
decision-graph add ... --session <id>   # then ask the human, then confirm

stop_hook_active wird beachtet, sodass dies nie in einer Schleife endet.

Installiere Hooks dort, wo Claude Code tatsächlich läuft, nicht dort, wo der Code liegt. Wenn du Claude Code auf einer VM ausführst und nur Shell-Befehle an die Maschine mit dem Repo weiterleitest, wird deren .claude/settings.json nie gelesen – verwende stattdessen den Git-Hook.

Git-Hook

decision-graph hooks install --git --target /path/to/repo

Installiert .git/hooks/post-commit, das decision-graph remind aufruft. Es blockiert niemals einen Commit. Da Agenten git über ihre Shell ausführen und stdout lesen, landet die Erinnerung ohnehin im Kontext des Agenten.

Es bleibt still, sobald eine Entscheidung mit diesem Commit verknüpft ist.

MCP-Server

Ein Eintrag, einmal auf Benutzerebene deklariert – der Server folgt dem Repo, das die Sitzung geöffnet hat, sodass kein Pfad synchron gehalten werden muss:

{
  "mcpServers": {
    "decision-graph": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vietqtran/decision-graph",
               "decision-graph-mcp"]
    }
  }
}

Er fragt den Client, in welchem Verzeichnis die Sitzung arbeitet (MCP-Roots), und fällt auf das Arbeitsverzeichnis zurück. Repos ohne decisions/-Verzeichnis werden übersprungen, statt geraten zu werden. Füge --path /pfad/zum/repo nur hinzu, um den Server auf ein Repo festzulegen.

Werkzeuge: search_decisions, get_decision, get_decision_history, get_decision_chain, get_overlay_map, list_scopes, add_decision.

Siehe docs/MCP.md.

Rauschen filtern

Nicht jeder Commit ist eine Geschäftsentscheidung. Tippfehler und reine Refactorings sollten keine Datensätze erzeugen.

Standardmäßig werden Tests, Lockfiles, node_modules, Build-Ausgaben, Coverage-Berichte, Assets und i18n-Dateien ignoriert. Pro Repo weiter einschränken:

# .decision-graph.yml
watch:
  - "src/domain/**"
  - "app/services/**"

Ein leeres watch bedeutet, dass alles zählt, was nicht in ignore steht.

CI

decision-graph check --git

Gibt {"needs_decision": bool, "watched_files": [...], ...} aus – verdrahte es mit einer PR-Warnung.

Dokumentation

• CLI-Referenz

• Architektur

• MCP-Server

• Fehlerbehebung

• Mitwirken

Entwicklung

uv venv && uv pip install -e ".[mcp]"
.venv/bin/python -m unittest discover -s tests

Keine Laufzeitabhängigkeit außer PyYAML; mcp ist ein optionales Extra.

Vorherige Arbeiten

decision-graph ist eine ADR-Variante. ADRs zeichnen architektonische Entscheidungen für Menschen auf; dieses zeichnet geschäftliche Entscheidungen pro Mandant in einer Form auf, die Agenten abfragen können – mit automatischer Erfassung und einem menschlichen Bestätigungsgate.

Lizenz

MIT