decision-graph

Английский · Tiếng Việt

Память решений для кодовых баз, над которыми работают ИИ-агенты.

Граф кода говорит вам, что делает код. decision-graph говорит вам, почему он такой — когда появилось бизнес-правило, кто его решил, какие альтернативы были отклонены и действует ли решение до сих пор.

git blame даёт вам сообщение коммита. Он не сообщает, что технический директор клиента попросил второй уровень одобрения на встрече, что отдельный модуль рассматривался и был отклонён как непригодный для слияния, или что порог был снижен шесть месяцев спустя кем-то другим.

Не зависит от языка и фреймворка. Работает в любом репозитории.

Почему

Боль острее всего, когда один базовый продукт расширяется для каждого клиента — но она проявляется везде, где накапливается бизнес-логика:

• Агент «улучшает» правило, которое было намеренно написано так для одного арендатора.

• Никто не помнит, является ли странная ветка ошибкой или требованием.

• Один и тот же отклонённый подход предлагается снова каждые несколько месяцев.

• Решения живут в тредах Slack, комментариях к тикетам и головах людей.

ИИ-агенты усугубляют это, потому что у них нет неявной памяти о последних шести месяцах встреч — но они будут следовать письменной записи, если она существует.

Related MCP server: arcane

Принципы проектирования

• Markdown — источник истины. Один .md-файл на решение, в git, проверяемый в PR.

• SQLite — только индекс. Удалите decisions/_index/ и пересоберите в любое время.

• Агенты не могут выдумывать decided_by. Агент может создать только draft; продвижение до active требует участия человека.

• Запись — побочный эффект кодирования, а не обязанность, о которой нужно помнить — хуки подсказывают в нужный момент.

• Обнаружение читает git, а не события инструментов. Правки, сделанные с помощью sed, heredoc, git apply или обычного редактора, обнаруживаются так же, как и вызовы инструментов Edit/Write.

Установка

Пока нет на PyPI — устанавливайте прямо с 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]"

Требуется Python 3.10+ и сборка SQLite с FTS5 (стандартно на macOS, Debian/Ubuntu и официальных образах Python).

Быстрый старт

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

Основная концепция: scope

scope — это ось, разделяющая контексты: клиент, линейка продуктов, команда или _base для решений, применимых везде.

Фильтрация по scope происходит до полнотекстового ранжирования, что предотвращает проникновение правил одного арендатора в ответы о другом. В репозитории, обслуживающем многих клиентов, это самое важное поле.

Структура

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

Frontmatter записи:

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]

Тело следует decisions/_template.md: Контекст / Рассмотренные альтернативы / Решение / Влияние / Открытые риски.

Рассмотренные альтернативы важнее для агентов, чем для людей — именно это мешает агенту повторно предлагать уже отклонённый подход.

supersedes связывает записи в цепочку вместо их удаления, поэтому аудиторский след сохраняется.

Поиск

Сначала фильтры по метаданным (scope, module, status, lifecycle_stage, file, tag), затем ранжирование SQLite FTS5. Диакритика сворачивается, поэтому duyet don hang соответствует 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

Интеграция с агентами

Какой триггер использовать

Установка обоих допустима; каждый замолкает, как только решение записано.

Хуки Claude Code

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

• PostToolUse(Edit|Write|MultiEdit) записывает, какие файлы затронула сессия.

• Stop проверяет git и эту запись. Если бизнес-релевантные файлы изменились и решение не было записано, он возвращает decision: "block" с инструкциями — агент должен действовать, а не завершать работу.

У агента есть ровно два способа выйти:

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

stop_hook_active учитывается, поэтому циклов не возникает.

Устанавливайте хуки там, где реально работает Claude Code, а не там, где живёт код. Если вы запускаете Claude Code на VM и только проксируете shell-команды на машину с репозиторием, .claude/settings.json этой машины никогда не читается — используйте git-хук.

Git-хук

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

Устанавливает .git/hooks/post-commit, вызывающий decision-graph remind. Он никогда не блокирует коммит. Поскольку агенты запускают git через свою оболочку и читают stdout, напоминание всё равно попадает в контекст агента.

Он остаётся молчаливым, как только решение связывается с этим коммитом.

MCP-сервер

Одна запись, объявленная один раз на уровне пользователя — сервер следует за репозиторием, открытым в сессии, поэтому нет пути, который нужно синхронизировать:

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

Он спрашивает клиента, в каком каталоге работает сессия (MCP roots), и при отсутствии ответа использует рабочий каталог. Репозитории без каталога decisions/ пропускаются, а не угадываются. Добавьте --path /path/to/repo только для привязки сервера к одному репозиторию.

Инструменты: search_decisions, get_decision, get_decision_history, get_decision_chain, get_overlay_map, list_scopes, add_decision.

См. docs/MCP.md.

Фильтрация шума

Не каждый коммит — бизнес-решение. Опечатки и чистые рефакторинги не должны создавать записи.

По умолчанию игнорируются тесты, lock-файлы, node_modules, результаты сборки, отчёты о покрытии, ассеты и i18n-файлы. Сузьте дальше для каждого репозитория:

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

Пустой watch означает, что учитывается всё, что не в ignore.

CI

decision-graph check --git

Выдаёт {"needs_decision": bool, "watched_files": [...], ...} — подключите к предупреждению в PR.

Документация

• Справочник по CLI

• Архитектура

• MCP-сервер

• Устранение неполадок

• Вклад в проект

Разработка

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

Нет зависимостей времени выполнения, кроме PyYAML; mcp — опциональный дополнительный пакет.

Аналоги

decision-graph — вариант ADR. ADR фиксируют архитектурные решения для людей; этот инструмент фиксирует бизнес-решения, для каждого арендатора, в форме, доступной для запросов агентов — с автоматическим захватом и человеческим подтверждением.

Лицензия

MIT