decision-graph

Español · Tiếng Việt

Memoria de decisiones para bases de código trabajadas por agentes de IA.

Un grafo de código te dice qué hace el código. decision-graph te dice por qué es así: cuándo apareció una regla de negocio, quién la decidió, qué alternativas se rechazaron y si la decisión sigue vigente.

git blame te da un mensaje de commit. No te dice que el CTO de un cliente pidió un segundo nivel de aprobación en una reunión, que se consideró un módulo separado y se rechazó por no ser fusionable, o que el umbral se redujo seis meses después por otra persona.

Independiente del lenguaje y del framework. Funciona en cualquier repositorio.

Por qué

El dolor es más agudo cuando un producto base se extiende por cliente, pero aparece en cualquier lugar donde se acumula lógica de negocio:

• Un agente "mejora" una regla que fue escrita deliberadamente así para un inquilino.

• Nadie recuerda si una rama de aspecto extraño es un error o un requisito.

• El mismo enfoque rechazado se vuelve a proponer cada pocos meses.

• Las decisiones viven en hilos de Slack, comentarios de tickets y cabezas de personas.

Los agentes de IA empeoran esto, porque no tienen memoria implícita de los últimos seis meses de reuniones, pero seguirán un registro escrito si existe.

Related MCP server: MCP Memory Server

Principios de diseño

• Markdown es la fuente de verdad. Un archivo .md por decisión, en git, revisable en un PR.

• SQLite es solo un índice. Elimina decisions/_index/ y reconstruye en cualquier momento.

• Los agentes no pueden inventar decided_by. Un agente solo puede crear un draft; promoverlo a active requiere un humano.

• Registrar es un efecto secundario de codificar, no una tarea para recordar: los hooks avisan en el momento adecuado.

• La detección lee git, no eventos de herramientas. Las ediciones hechas con sed, heredocs, git apply o un editor simple se detectan igual que las llamadas a herramientas Edit/Write.

Instalación

Aún no está en PyPI: instala directamente desde GitHub:

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]"

Requiere Python 3.10+ y una compilación de SQLite con FTS5 (estándar en macOS, Debian/Ubuntu y las imágenes oficiales de Python).

Inicio rápido

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

Concepto central: scope

scope es el eje que separa contextos: un cliente, una línea de productos, un equipo o _base para decisiones que aplican en todas partes.

El filtrado por scope ocurre antes del ranking de texto completo, lo que evita que las reglas de un inquilino se filtren en las respuestas sobre otro. En un repositorio que sirve a muchos clientes, este es el campo más importante.

Diseño

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

El frontmatter de un registro:

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]

El cuerpo sigue decisions/_template.md: Contexto / Alternativas consideradas / Decisión / Impacto / Riesgos abiertos.

Las alternativas consideradas importan más a los agentes que a los humanos — es lo que evita que un agente vuelva a proponer el enfoque que ya fue rechazado.

supersedes encadena registros en lugar de eliminarlos, para que el rastro de auditoría sobreviva.

Búsqueda

Primero los filtros de metadatos (scope, module, status, lifecycle_stage, file, tag), luego el ranking FTS5 de SQLite. Los diacríticos se pliegan, así que duyet don hang coincide con Duyệt đơn hàng.

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

Integración con agentes

Qué desencadenante usar

Instalar ambos está bien; cada uno se silencia una vez que se registra una decisión.

Hooks de Claude Code

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

• PostToolUse(Edit|Write|MultiEdit) registra qué archivos tocó una sesión.

• Stop inspecciona git más ese registro. Si se cambiaron archivos relevantes para el negocio y no se escribió ninguna decisión, devuelve decision: "block" con instrucciones: el agente debe actuar en lugar de terminar.

El agente tiene exactamente dos salidas:

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

stop_hook_active se respeta, así que esto nunca se repite en bucle.

Instala los hooks donde realmente se ejecuta Claude Code, no donde vive el código. Si ejecutas Claude Code en una VM y solo haces proxy de comandos de shell a la máquina que tiene el repositorio, el .claude/settings.json de esa máquina nunca se lee: usa el hook de git en su lugar.

Hook de git

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

Instala .git/hooks/post-commit que llama a decision-graph remind. Nunca bloquea un commit. Como los agentes ejecutan git a través de su shell y leen stdout, el recordatorio llega al contexto del agente de todos modos.

Se silencia una vez que una decisión enlaza con ese commit.

Servidor MCP

Una entrada, declarada una vez a nivel de usuario: el servidor sigue el repositorio que la sesión tenga abierto, así que no hay ruta que mantener sincronizada:

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

Pregunta al cliente en qué directorio está trabajando la sesión (raíces MCP), con el directorio de trabajo como respaldo. Los repositorios sin un directorio decisions/ se omiten en lugar de adivinarse. Añade --path /path/to/repo solo para fijar el servidor a un repositorio.

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

Ver docs/MCP.md.

Filtrado de ruido

No cada commit es una decisión de negocio. Los errores tipográficos y las refactorizaciones puras no deberían generar registros.

Los valores predeterminados ignoran pruebas, lockfiles, node_modules, salida de compilación, informes de cobertura, activos y archivos i18n. Reduce más por repositorio:

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

Un watch vacío significa que todo lo que no esté en ignore cuenta.

CI

decision-graph check --git

Emite {"needs_decision": bool, "watched_files": [...], ...} — conéctalo a una advertencia de PR.

Documentación

• Referencia de CLI

• Arquitectura

• Servidor MCP

• Solución de problemas

• Contribución

Desarrollo

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

Sin dependencia de ejecución más allá de PyYAML; mcp es un extra opcional.

Trabajo previo

decision-graph es una variante de ADR. Los ADR registran decisiones arquitectónicas para humanos; esto registra decisiones de negocio, por inquilino, en una forma que los agentes pueden consultar, con captura automática y una puerta de confirmación humana.

Licencia

MIT