decision-graph

English · Tiếng Việt

AI 에이전트가 작업하는 코드베이스를 위한 의사결정 메모리.

코드 그래프는 코드가 무엇을 하는지 알려줍니다. decision-graph는 왜 그렇게 되었는지를 알려줍니다 — 비즈니스 규칙이 언제 등장했는지, 누가 결정했는지, 어떤 대안이 거부되었는지, 그리고 그 결정이 여전히 유효한지.

git blame은 커밋 메시지를 제공합니다. 고객의 CTO가 회의에서 두 번째 승인 단계를 요청했다는 사실, 별도 모듈이 고려되었지만 병합 불가능하다고 거부되었다는 사실, 또는 몇 달 후 다른 사람이 임계값을 낮추었다는 사실은 알려주지 않습니다.

언어 및 프레임워크에 구애받지 않습니다. 모든 저장소에서 작동합니다.

왜

하나의 기본 제품을 고객별로 확장할 때 고통이 가장 큽니다 — 하지만 비즈니스 로직이 축적되는 모든 곳에서 나타납니다:

• 에이전트가 특정 테넌트를 위해 의도적으로 작성된 규칙을 "개선"합니다.

• 이상해 보이는 분기가 버그인지 요구사항인지 아무도 기억하지 못합니다.

• 거부된 접근 방식이 몇 달마다 다시 제안됩니다.

• 결정은 Slack 스레드, 티켓 댓글, 사람들의 머릿속에 존재합니다.

AI 에이전트는 지난 6개월간의 회의에 대한 암묵적 기억이 없기 때문에 상황을 악화시킵니다 — 하지만 기록이 존재한다면 에이전트는 그 기록을 따를 것입니다.

Related MCP server: MCP Memory Server

설계 원칙

• 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+ 및 FTS5가 포함된 SQLite 빌드가 필요합니다 (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가 실제로 실행되는 곳에 훅을 설치하세요. 코드가 있는 곳이 아닙니다. VM에서 Claude Code를 실행하고 저장소가 있는 머신에 셸 명령만 프록시한다면 해당 머신의 .claude/settings.json은 읽히지 않습니다 — git 훅을 사용하세요.

Git 훅

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

decision-graph remind를 호출하는 .git/hooks/post-commit을 설치합니다. 커밋을 차단하지 않습니다. 에이전트는 셸을 통해 git을 실행하고 stdout을 읽으므로 알림이 어쨌든 에이전트의 컨텍스트에 도달합니다.

결정이 해당 커밋에 연결되면 조용해집니다.

MCP 서버

사용자 수준에서 한 번 선언된 단일 항목 — 서버는 세션이 열려 있는 저장소를 따르므로 동기화할 경로가 없습니다:

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

클라이언트에게 세션이 작업 중인 디렉토리(MCP 루트)를 묻고, 작업 디렉토리로 대체합니다. 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를 참조하세요.

노이즈 필터링

모든 커밋이 비즈니스 결정은 아닙니다. 오타와 순수 리팩토링은 레코드를 생성해서는 안 됩니다.

기본값은 테스트, 잠금 파일, 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