Claude Code 的完整圖形工程 (Graph Engineering) 指南

大多数人仍然像使用非常昂贵的实习生一样使用 Claude Code。

给一个任务，等一个答案，然后手动决定下一步做什么。

但实际上，那些从 AI 中獲得最大杠杆效用的团队，正在构建更接近一个小型分布式系统的架构。

一個 Agent 負責界定問題範圍。

五個較便宜的 Agent 並行搜索。

一個確定性腳本移除重複項。

三個持懷疑態度的 Agent 嘗試推翻發現。

一個頂級模型做出最終判斷。

這就是圖譜工程（Graph Engineering）。

在繼續閱讀之前：

把這份指南加入書籤，這樣當你開始構建自己的 Claude 工作流程時，就可以回頭參考這些圖譜模式。

追蹤

@Gyome1_ -

我會深入解析 Claude Code、AI agents，以及那些將單一模型轉變為可靠工程工作流程的系統。

我花了數週時間剖析真實的 agent 架構、工作流程圖和生產模式，將圖譜工程（Graph Engineering）重新整理成一本實用的操作手冊。

與其寫更長的提示詞，不如設計資訊在系統中流動的路徑：

線性 → 扇出 → 歸納 → 驗證 → 綜合

每個 Agent 變成一個節點，有明確的任務範圍。每條邊承載結構化數據。路由器決定執行哪個分支。驗證器拒絕弱輸出。循環持續進行，直到圖譜不再發現新東西。

重要的轉變是，Claude Code 不再需要像一個智慧體那樣，按照一個巨大的清單逐步工作。

它可以生成編排程式碼，生成一群專門的子 Agent，將它們的輸出路由到不同的模型，並且只有在證據通過驗證後才組合最終結果。

基本模式並非新概念。軟體工程師已經使用 DAG、管線、屏障、MapReduce 和分散式工作者數十年了。

改變的是每個節點內部現在容納了什麼。

一個節點可以搜尋儲存庫、審核遷移、挑戰架構決策、檢查測試失敗，或將五十個獨立的發現綜合成一份有引用的報告。

這份指南將整個系統從最簡單的線性 Agent 分解到鑽石圖、路由器節點、對抗性驗證器面板、收斂迴圈、模型分層，以及在 Claude Code 內部直接生成的動態工作流程。

到最後，你將能夠面對一個大型任務，不再問：

「我該寫什麼提示詞？」

1. 圖譜工程始於帳單

圖譜工程通常被描述為一種運行更多 Agent 的方式。

這個框架忽略了最昂貴的部分。

你可以啟動二十個 Claude Agent 針對同一個儲存庫，然後收到二十份重疊的報告、重複的上下文、相互矛盾的結論，以及一張更大的 API 帳單。

一個有用的圖譜控制計算發生在哪裡、哪個模型處理每個決策、以及不確定的發現如何在工作流程中移動。

想像一下，要求 Claude Code 準備一次生產環境遷移：

檢查儲存庫，找出所有依賴項，提出遷移方案，識別風險，驗證計畫，並撰寫最終摘要。

在一個提示詞內部，這變成了一個漫長而不透明的過程。Claude 搜尋程式碼庫，將發現儲存在上下文中，設計遷移，審查自己的計畫，並產生最終報告。

當報告失敗時，很難定位失敗的來源。Claude 可能漏掉了一個檔案，誤解了一個依賴項，遺失了較早的細節，或者在驗證過程中接受了一個不嚴謹的假設。

每個階段也可能都在同一個昂貴的模型上運行，即使任務的某些部分涉及簡單的提取或排序。

圖譜工程打開了這個工作流程，讓每個決策都有一個可見的位置。

檢查分支同時運行，因為它們使用相同的範圍任務，並且不依賴彼此的輸出。

它們的發現匯聚到一個歸納階段，在那裡重複項消失，證據被壓縮成一個更小的數據集。

然後，一個路由器讀取嚴重程度。常規變更通過輕量級審查。高風險的發現會經過幾個獨立審查者的深入分析，然後才到達最終模型。

結果是，一個工作流程的延遲、模型成本、上下文大小和驗證深度都透過圖譜的結構來控制。

一個節點應該做出一個決策

一個有用的節點有明確的責任範圍。

找出所有對已棄用 API 的呼叫。 將每個遷移風險分類為低、中或高。 測試回滾計畫的失敗情況。

每個節點需要清晰的輸入、定義的輸出，以及有限的決策面。

一個同時搜尋儲存庫、評估業務影響、設計修復方案並撰寫建議的節點，仍然包含幾個隱藏的階段。除錯仍然困難，因為中間推理埋藏在一個模型呼叫內部。

更小的邊界揭示了證據在何處進入系統，以及其意義在何處發生變化。

一條邊應該承載證據

一條邊代表下一個節點所需的數據。

掃描器可以返回一個可預測的物件：

1{
2  "file": "src/auth/session.ts",
3  "lines": [84, 119],
4  "dependency": "legacySessionClient",
5  "confidence": 0.94,
6  "evidence": "兩個呼叫處都依賴於已棄用的 refresh 方法。"
7}

風險分類器現在為每個發現接收相同的欄位。它可以拒絕不完整的結果，對相關檔案進行分組，並將不確定的證據路由到另一個審查。

Schema 減少了節點之間的解釋漂移。自由格式的段落迫使每個下游 Agent 重建前一個 Agent 的含義。經過幾個階段，小的歧義可能會改變最終結論。

結構化輸出在證據通過圖譜移動時保持其穩定。

有些節點是普通程式碼

假設八個搜尋 Agent 返回了八十個發現。

工作流程需要合併陣列、丟棄空回應、移除重複項，並對剩餘項目進行排序。

這些操作有確定性的答案：

1const uniqueFindings = [
2  ...new Map(
3    results
4      .flatMap(batch => batch ?? [])
5      .map(item => [`${item.file}:${item.lines.join("-")}`, item])
6  ).values()
7];

一個 JavaScript 轉換可以立即處理這個問題，並且每次運行產生相同的輸出。將相同的任務發送給另一個模型會增加 token 成本，並創造另一個證據可能消失的地方。

模型節點應該圍繞搜尋、分類、比較、審查和綜合。程式碼可以處理驗證、去重、排序、明確的路由規則以及其他可預測的轉換。

這種劃分成為圖譜的基礎。

每個模型呼叫都應該對應於一個真正需要判斷的決策。

2. 鑽石：真實 Agent 圖譜如何移動工作

大多數嚴肅的 Agent 圖譜最終都會呈現相同的形狀。

一個任務從一個共享的範圍開始，分成幾個獨立的工作者，等待它們的輸出，壓縮證據，並將結果傳遞給最終決策。

這個形狀就是鑽石。

左側是扇出。

所有分支匯聚的中間點是屏障。

右側是扇入。

一旦任務對於一個上下文視窗來說變得太大，這種模式就會隨處出現。

儲存庫審計可以按子系統拆分。市場報告可以按來源拆分。研究任務可以按假設拆分。遷移審查可以按 API 使用、資料庫變更、部署風險和測試覆蓋率拆分。

每個工作者接收相同的範圍，但任務範圍更窄。

然後，圖譜會等待，直到足夠有用的證據返回。

扇出應該創造獨立的工作

當一個分支可以從共享輸入開始，並且在不讀取其他分支輸出的情況下產生有用的結果時，它就屬於扇出。

對於安全審計，拆分可能如下所示：

Claude Code 可以使用屏障原語（例如 parallel()）並發啟動這些呼叫。

1const findings = await parallel(
2  checks.map(check => async () => {
3    return agent({
4      task: check.task,
5      context: auditScope,
6      schema: FINDING_SCHEMA
7    });
8  })
9);

編排保持在普通的 JavaScript 中。每個分支接收一個有界限的任務，並返回一個經過驗證的物件。

結果以一個輸出集合的形式到達，可以對其進行過濾、檢查，並傳遞到下一個階段。

一個大的扇出仍然需要每個分支背後的理由。

將一個模糊的任務分配給十二個幾乎相同的 Agent，通常會產生措辭略有不同的重複發現。有用的並行來自不同的來源、視角、程式碼區域或假設。

屏障創造了一個決策點

屏障會暫停下一階段，直到所需的分支完成。

這種暫停很重要，因為某些決策依賴於完整的集合。

當一半的儲存庫仍在檢查中時，排名節點無法識別最重要的漏洞。當部署審查仍在進行時，綜合模型無法撰寫完整的遷移計畫。

在屏障處，圖譜有機會檢查運行的狀態：

1const completed = findings.filter(Boolean);
2
3if (completed.length < MIN_REQUIRED_RESULTS) {
4  throw new Error("審計覆蓋率不足");
5}

這就是部分失敗變得可見的地方。

一個工作者可能超時、返回格式錯誤的數據，或沒有產生任何發現。過濾掉 null 值可以保持運行繼續，但生產工作流程通常需要更明確的策略：

• 需要多少個成功分支；
• 哪些分支是強制性的；
• 失敗的節點是否應該重試；
• 最終結果是否應標記為不完整。

因此，屏障是可靠性模型的一部分，而不僅僅是一種同步機制。

在綜合之前先歸納

扇出之後，圖譜可能包含數十個重疊的發現。

將它們全部直接發送到頂級模型會產生大量的上下文，重複相同的證據，並使重要細節更難區分。

歸納階段準備好證據。

一些歸納可以在程式碼中完成：

1const unique = deduplicateByKey(
2  completed.flatMap(result => result.findings),
3  finding => `${finding.file}:${finding.line}:${finding.type}`
4);

下一層可能需要判斷：

1const curated = await agent({
2  task: `
3    對相關發現進行分組。
4    保留所有檔案和行號引用。
5    按運營影響對每組進行排名。
6    為每個結論返回最強證據。
7  `,
8  input: unique,
9  schema: CURATED_FINDINGS_SCHEMA
10});

歸納控制著哪些內容到達最終模型。

一個好的歸納器在保留證據的同時移除重複。一個激進的歸納器可能會將幾個不同的風險壓縮成一個模糊的摘要，並抹去驗證所需的細節。

最安全的模式是保持每個歸納後的聲明與其來源項目之間的連結。

1{
2  "risk": "Session refresh 可能在遷移後失敗",
3  "severity": "high",
4  "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],
5  "evidence": [
6    "三個服務呼叫已棄用的 refresh 方法",
7    "不存在回退路徑",
8    "缺少整合測試覆蓋率"
9  ]
10}

現在，綜合節點接收到一個更小的數據集，而不會失去可追溯性。

3. 可靠性是圖譜的一部分

一個圖譜可以很快完成，但仍然產生糟糕的答案。

一旦幾個 Agent 開始搜尋、分類和審查同一個任務，主要問題就變成了控制。

系統需要規則來決定哪些發現值得深入處理，哪些輸出應該被拒絕，以及工作流程何時已經搜尋得足夠多。

按風險路由

路由器節點讀取結構化輸出，並選擇下一個分支。

分類可以來自模型，而分支本身則在程式碼中保持明確。

1const route =
2  finding.severity === "high"
3    ? runFullAudit(finding)
4    : runQuickReview(finding);

這使得昂貴的審查集中在具有重大影響的發現上。

一個有用的路由器依賴於圖譜可以檢查的欄位：嚴重程度、信心水準、受影響的系統、財務風險或缺少證據的存在。

添加獨立驗證

一個 Agent 審查自己的結論，會將相同的假設帶入兩個階段。

一個更強的圖譜會將重要的發現發送給幾個具有不同任務的審查者。

不應該指示審查者改進原始答案。他們的任務是尋找它可能不完整或錯誤的理由。

圖譜可以在發現前進之前要求達成一致：

1const accepted = votes.filter(vote => vote.approve).length >= 2;

隔離修改程式碼的 Agent

並行程式設計 Agent 在編輯同一個工作目錄時可能會相互干擾。

一個 Agent 可能在另一個 Agent 仍在讀取檔案時覆蓋它。測試可能針對混合了不相關變更的內容運行。

Git worktrees 為每個分支提供自己的儲存庫副本。

1主儲存庫
2      │
3      ├→ worktree/auth-fix
4      ├→ worktree/db-migration
5      └→ worktree/test-repair

每個 Agent 可以在自己的環境中修改檔案並運行測試。後續的節點比較補丁，檢查衝突，並選擇應該合併的內容。

這將隔離變成了圖譜的一部分，而不是一個手動清理步驟。

讓發現收斂

有些任務無法一次完成。

儲存庫審計可能發現一個指向另一個套件的依賴項。那個套件可能揭示另一個呼叫處。圖譜需要一種受控的方式來繼續搜尋，而不重複它已經看過的所有內容。

1const seen = new Set();
2let dryRounds = 0;
3
4while (dryRounds < 2) {
5  const findings = await discoverNext([...seen]);
6  const fresh = findings.filter(item => !seen.has(item.id));
7
8  fresh.forEach(item => seen.add(item.id));
9  dryRounds = fresh.length === 0 ? dryRounds + 1 : 0;
10}

重要的細節是對每個先前看過的項目進行去重。

僅對已確認的發現進行去重，會允許被拒絕或不明確的項目在下一輪返回，並消耗相同的工作量。

迴圈在幾次乾燥輪次、固定預算或最大迭代次數後停止。生產圖譜通常需要全部三個條件。

將模型匹配到節點

並非每個節點都需要最強可用的模型。

提取、基本分類和狹隘搜尋通常可以在更快的層級上運行。架構審查、對抗性驗證和最終綜合可能需要更強的模型。

模型分層成為圖譜的另一個屬性。

預算由多少個節點運行、迴圈重複的頻率、每條邊跨越多少上下文、以及哪個模型處理每個階段來決定。

一個包含二十個廉價搜尋呼叫的圖譜，仍然可能比一個強模型呼叫的成本更高。架構在需要另一個分支之前，就需要一個 token 預算。

知道何時停止繪製

小型任務很少需要路由器、投票面板、worktrees 和收斂迴圈。

圖譜開銷包括編排程式碼、schema、重試、日誌記錄、中間儲存以及更多需要除錯的失敗狀態。

當一個模型可以容納相關上下文、任務有很少的獨立分支、並且錯誤答案的成本很低時，線性工作流程通常就足夠了。

圖譜工程在任務涉及並行工作、昂貴的決策、大量的證據集或有意義的驗證要求時變得有用。

完整的工作流程最終可能看起來像這樣：

其價值來自於讓工作的移動變得可見。

每個節點都有有限的責任。每條邊都承載結構化證據。每個分支都有存在的理由。每個迴圈都有停止條件。

此時，Claude Code 不再是按照一個長長的指令工作。

它正在執行一個經過設計的系統。