完整開發工作流 (Full Development Flow) · Graphify

適用情境

中型以上團隊（多人多 PR 平行）
想把 graphify 整合進 code review 流程（不只給開發看，也給 reviewer）
想把圖譜暴露成 MCP server，讓 CLI 之外的其他助理也可呼叫

⚠️ 與舊版差異：舊工作流有 Init / Validate / Deploy 等不存在的步驟，並引用 graphify 未採用的 Neo4j 後端（extract 則為真實指令）；新工作流對應 graphify v0.9.32 真實可用的功能鏈。

流程總覽

flowchart LR
    A[1. graphify install 平台註冊] --> B[2. graphify extract baseline]
    B --> C[3. graphify hook install 自動重建]
    C --> D[4. 開發: graphify query / path / explain]
    D --> E[5. PR: graphify prs --triage / --conflicts]
    E --> F[6. graphify update 補語意層]
    F --> G[7. python -m graphify.serve MCP 暴露]

步驟 1：對助理做 project-scoped 註冊

cd ~/my-monorepo

# Claude Code（含 strict 模式）
graphify claude install --project --strict

# 同時也給 Cursor
graphify cursor install --project

strict 模式讓 Claude Code 第一次 Read 原始碼前強制先 graphify query，避免助理跳過圖譜直接 grep。

步驟 2：全量 baseline 建圖

# 若有 docs/PDF，設 API key
export ANTHROPIC_API_KEY=sk-ant-...

# 深度建圖（含社群偵測自動命名）
graphify extract . --mode deep

關注 GRAPH_REPORT.md 的 god nodes 與 communities：它們就是這個專案的「局部中心」。

步驟 3：裝設 git hook 持續同步

graphify hook install
# 設 post-commit / post-checkout hook + graph.json merge driver

commit 一次確認運作：

git commit --allow-empty -m "test hook"
# 預期 hook 觸發 AST 重建

步驟 4：開發中使用 query / path / explain

場景	指令
開放式探索	`graphify query "RateLimiter 在哪裡生效？"`
兩節點連結	`graphify path "UserService" "DatabasePool"`
單一節點脈絡	`graphify explain "APIRouter"`

r助理會自動讀 GRAPH_REPORT.md + graph.json，不會 grep 所有檔案。

步驟 5：PR 影響分析

PR review queue：

# AI 排 review 優先度（高風險在前）
graphify prs --triage

# 找出共用 community 的 PR（merge 順序風險）
graphify prs --conflicts

# 單一 PR 的圖譜影響
graphify prs 42

# worktree ↔ branch ↔ PR 對應
graphify prs --worktrees

reviewer 用這個結果決定：

高 graph impact 的 PR 要更仔細看
共用 community 的 PR 要注意 merge 順序

步驟 6：補語意層（docs 變動時）

當 PR 改了 docs（ADR、RFC）：

# 增量重抓 docs 變動
graphify update ./docs --mode deep

把新的 rationale / concept 節點融入 graph.json，後續 explain 才會看到「為什麼這樣設計」的脈絡。

步驟 7：MCP server 暴露（可選）

把圖譜開成 MCP server，給 CLI 之外其他助理呼叫：

# stdio（local 預設）
python -m graphify.serve graphify-out/graph.json

# HTTP（團隊共用一個 graph，多人 connect）
python -m graphify.serve graphify-out/graph.json --transport http \
  --host 0.0.0.0 --api-key "$SECRET"

助理工具集對應：

MCP 工具	對應 CLI
`query_graph`	graphify query
`get_node`	取單節點
`get_neighbors`	graphify explain（子集）
`shortest_path`	graphify path
`list_prs`	graphify prs
`get_pr_impact`	graphify prs PR_NUMBER
`triage_prs`	graphify prs –triage

團隊工作流範例

sequenceDiagram
    participant Alice
    participant Bob
    participant Repo
    participant CI
    Alice->>Repo: PR #42: refactor auth
    Repo->>CI: CI run
    Repo->>Repo: post-commit AST rebuild
    Bob->>Repo: graphify prs --triage (理 priority)
    Bob->>Repo: graphify prs 42 (graph impact)
    Note over Bob: 看到 PR #42 觸動 god node<br/>"login"，需仔細 review
    Bob->>Repo: graphify prs --conflicts
    Note over Bob: PR #42 與 #50 共用 community，<br/>merge 順序重要
    Bob->>Repo: approve + comment
    Repo->>CI: merge trigger

何時不要用此工作流

個人 / 小專案 → 快速入門工作流
不需要 PR 分析（單人維護、自動 review） → 增量提取工作流

下一步

v0.9.54～v0.9.56：跨 Repo Review 的新版做法

如果 PR 同時牽涉應用 repo 與 shared SDK，先各自建圖，再以 merge-graphs 合併。v0.9.54 起，merge-time resolver 在 receiver type / method 唯一且不歧義時，可補出跨 repo member-call；這讓 impact review 不再只停在 same_type_as 型別對照。

Review 時仍要保守：

有多個同名候選時，不應把缺少邊解讀成「一定沒有影響」。
合併前確認兩邊 graph 都由近期 extractor 建立。
升版後若 resolver 有重大 correctness fix，先 refresh graph 再做 PR triage，避免拿舊圖回答新問題。

對大型團隊來說，graph freshness 本身就是 review evidence 的一部分。