decision-graph

日本語 · Tiếng Việt

AIエージェントが作業するコードベースのための意思決定メモリ。

コードグラフはコードが何をするかを教えてくれます。decision-graphはなぜそうなっているのかを教えてくれます — ビジネスルールがいつ登場したか、誰が決定したか、どの代替案が却下されたか、そしてその決定が今も有効かどうか。

git blameはコミットメッセージを教えてくれます。しかし、顧客のCTOが会議で第二承認階層を要求したこと、別のモジュールが検討されて統合不可能として却下されたこと、または6ヶ月後に別の人物によって閾値が引き下げられたことは教えてくれません。

言語・フレームワーク非依存。どのリポジトリでも動作します。

なぜ

この痛みは、1つの基本製品を顧客ごとに拡張するときに最も顕著ですが、ビジネスロジックが蓄積される場所ならどこでも現れます：

• エージェントが、あるテナントのために意図的に書かれたルールを「改善」してしまう。

• 奇妙に見える分岐がバグなのか要件なのか、誰も覚えていない。

• 同じ却下されたアプローチが数ヶ月ごとに再提案される。

• 決定がSlackスレッド、チケットのコメント、人々の頭の中に散在している。

AIエージェントはこれを悪化させます。なぜなら、過去6ヶ月の会議の暗黙の記憶を持たないからです — しかし、書かれた記録があればそれに従います。

Related MCP server: arcane

設計原則

• Markdownが真実の源。 各決定につき1つの.mdファイルをgitに置き、PRでレビュー可能にします。

• SQLiteは単なるインデックス。 decisions/_index/を削除していつでも再構築できます。

• エージェントはdecided_byを発明してはいけません。 エージェントはdraftを作成できるだけで、activeへの昇格には人間が必要です。

• 記録はコーディングの副産物であり、覚えておくべき雑用ではありません — フックが適切なタイミングで促します。

• 検出はgitを読み取ります。 sed、ヒアドキュメント、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。

スコープによるフィルタリングは全文検索ランキングの前に行われ、あるテナントのルールが別のテナントに関する回答に混入するのを防ぎます。多くの顧客にサービスを提供するリポジトリでは、これが最も重要なフィールドです。

レイアウト

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

レコードのフロントマター：

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"と指示を返します — エージェントは終了する代わりに行動しなければなりません。

エージェントには正確に2つの脱出方法があります：

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/ディレクトリのないリポジトリは推測せずスキップされます。サーバーを1つのリポジトリに固定する場合のみ--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