Claude Code Graph工程完全指南

大多数人仍然把 Claude Code 当作一个昂贵的实习生来用。

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

但从 AI 中获得最大杠杆的团队，正在构建更接近一个小型分布式系统的东西。

• 一个智能体界定问题范围。
• 五个更便宜的智能体并行搜索。
• 一个确定性脚本去除重复项。
• 三个怀疑型智能体试图推翻发现。
• 一个顶级模型做出最终判断。

这就是Graph工程。

不是写更长的提示词，而是设计信息在系统中的路径：

线性 → 扇出 → 归约 → 验证 → 综合

每个智能体成为一个职责明确的节点。每条边携带结构化数据。路由器决定哪个分支运行。验证器拒绝弱输出。循环持续，直到图不再发现新内容。

关键转变在于，Claude Code 不再需要像一个按巨大清单工作的单一智能体。

它可以生成编排代码，创建一群专门的子智能体，将它们的输出路由到不同模型，只有在证据通过验证后才组装最终结果。

基本模式并不新鲜。软件工程师使用 DAG、流水线、屏障、MapReduce 和分布式工作者已有数十年。

改变的是现在每个节点内部的内容。

一个节点可以搜索仓库、审计迁移、挑战架构决策、检查测试失败、或综合五十个独立发现为一份带引用的报告。

本指南将整个系统从最简单的线性智能体分解到钻石图、路由器节点、对抗性验证面板、收敛循环、模型分层，以及直接在 Claude Code 内部生成的动态工作流。

到最后，你将能够审视一个大型任务，不再问： “我应该写什么提示词？”

1. Graph工程从账单开始

Graph工程常被呈现为一种运行更多智能体的方式。

这种表述忽略了最昂贵的部分。

你可以启动二十个 Claude 智能体对着同一个仓库，得到二十份重叠的报告、重复的上下文、冲突的结论，以及一张大得多的 API 账单。

一个有用的图控制计算发生的位置、每个决策由哪个模型处理、以及不确定的发现如何在工作流中移动。

想象一下让 Claude Code 准备一次生产迁移：

检查仓库，找到所有依赖，提出迁移方案，识别风险，验证计划，编写最终简报。

在一个提示词内部，这变成一个漫长且不透明的过程。Claude 搜索代码库，在上下文中存储发现，设计迁移，审查自己的计划，并生成最终报告。

当报告失败时，很难定位失败来源。Claude 可能遗漏了一个文件、误解了一个依赖、丢失了早期细节、或在验证时接受了一个薄弱的假设。

每个阶段也可能运行在同一个昂贵模型上，即使任务的部分内容只是简单的提取或排序。

Graph工程打开了那个工作流，让每个决策都有可见的位置。

检查分支同时运行，因为它们使用相同范围的任务，且不依赖彼此的输出。

它们的发现在归约阶段汇合，重复项消失，证据被压缩成更小的数据集。

然后一个路由器读取严重性。常规变更通过轻量级审查。高风险发现经过几个独立审查者的深度分析，然后到达最终模型。

结果是一个工作流，其中延迟、模型成本、上下文大小和验证深度都通过图的结构来控制。

一个节点应该做一次决策

一个有用的节点有明确的职责。

找到所有对已弃用 API 的调用。 将每个迁移风险分类为低、中、高。 测试回滚计划的失败场景。

每个节点需要清晰的输入、定义的输出和有限的决策面。

一个搜索仓库、评估业务影响、设计修复并编写建议的节点仍然包含几个隐藏阶段。调试仍然困难，因为中间推理埋在一次模型调用内部。

更小的边界揭示了证据在何处进入系统，以及其含义在何处改变。

一条边应该携带证据

一条边代表下一个节点所需的数据。

扫描器可以返回一个可预测的对象：

{
  "file": "src/auth/session.ts",
  "lines": [84, 119],
  "dependency": "legacySessionClient",
  "confidence": 0.94,
  "evidence": "两个调用点都依赖于已弃用的 refresh 方法。"
}

风险分类器现在对每个发现都接收相同的字段。它可以拒绝不完整的结果、对相关文件进行分组、并将不确定的证据路由到另一个审查。

模式减少了节点之间的解释偏差。自由形式的段落迫使每个下游智能体重建前一个智能体的含义。经过几个阶段，小的歧义可能改变最终结论。

结构化输出在证据流经图时保持其稳定。

有些节点是普通代码

假设八个搜索智能体返回了八十个发现。

工作流需要合并数组、丢弃空响应、移除重复项、并排序剩余项。

这些操作有确定性的答案：

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

一个 JavaScript 转换立即处理这个，并在每次运行时产生相同输出。将同样的任务发送给另一个模型会增加 Token 成本，并创造另一个证据可能消失的地方。

模型节点应该围绕搜索、分类、比较、审查和综合。代码可以处理验证、去重、排序、显式路由规则和其他可预测的转换。

这种划分成为图的基础。

每次模型调用应该对应一个真正需要判断的决策。

2. 钻石：真实智能体图如何流转工作

大多数严肃的智能体图最终都会采用相同的形状。

一个任务从一个共享范围开始，分裂成几个独立工作者，等待它们的输出，压缩证据，然后将结果传递给最终决策。

这个形状就是钻石。

左边是扇出。

所有分支汇合的中间点是屏障。

右边是扇入。

一旦任务对一个上下文窗口来说太大，这种模式就无处不在。

仓库审计可以按子系统拆分。市场报告可以按来源拆分。研究任务可以按假设拆分。迁移审查可以按 API 使用、数据库变更、部署风险和测试覆盖来拆分。

每个工作者接收相同的范围，但分配更窄的任务。

然后图等待，直到足够有用的证据返回。

扇出应该创建独立工作

当一个分支可以从共享输入开始，并且在不读取另一个分支输出的情况下产生有用结果时，它就应该属于扇出。

对于安全审计，拆分可能如下：

Claude Code 可以使用 parallel() 这样的屏障原语并发启动这些调用：

const findings = await parallel(
  checks.map(check => async () => {
    return agent({
      task: check.task,
      context: auditScope,
      schema: FINDING_SCHEMA
    });
  })
);

编排保持在普通 JavaScript 中。每个分支接收一个有限任务并返回一个验证过的对象。

结果作为一组输出到达，可以过滤、检查并传递到下一阶段。

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

将一个模糊的任务分成十二个几乎相同的智能体，通常会产生措辞略有不同的重复发现。有用的并行来自不同的来源、视角、代码区域或假设。

屏障创建决策点

屏障暂停下一阶段，直到所需分支完成。

这个暂停很重要，因为有些决策依赖于完整集合。

当仓库的一半仍在被检查时，排名节点无法识别最重要的漏洞。当部署审查仍在运行时，综合模型无法编写完整的迁移计划。

在屏障处，图有机会检查运行状态：

const completed = findings.filter(Boolean);

if (completed.length < MIN_REQUIRED_RESULTS) {
  throw new Error("审计覆盖不足");
}

这就是部分失败变得可见的地方。

工作者可能超时、返回格式错误的数据或没有发现结果。过滤掉空值可以让运行继续，但生产工作流通常需要更清晰的策略：

需要多少个成功分支； 哪些分支是强制性的； 失败节点是否应该重试； 最终结果是否应被标记为不完整。

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

在综合之前进行归约

扇出之后，图中可能包含几十个重叠的发现。

将它们全部直接发送到顶级模型会创建大的上下文，重复相同证据，并使重要细节更难以区分。

归约阶段准备证据。

一些归约可以在代码中完成：

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

下一层可能需要判断：

const curated = await agent({
  task: `
    将相关发现分组。
    保留所有文件和行引用。
    按操作影响对每组进行排名。
    为每个结论返回最强证据。
  `,
  input: unique,
  schema: CURATED_FINDINGS_SCHEMA
});

归约控制什么到达最终模型。

一个好的归约器移除重复同时保留证据。一个激进的归约器可能将几个不同风险压缩成一个模糊摘要，并擦除验证所需的细节。

最安全的模式是在每个归约后的声明与其源项之间保持链接。

{
  "risk": "迁移后会话刷新可能失败",
  "severity": "high",
  "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],
  "evidence": [
    "三个服务调用已弃用的 refresh 方法",
    "不存在回退路径",
    "缺少集成测试覆盖"
  ]
}

现在综合节点收到更小的数据集，同时不丢失可追溯性。

3. 可靠性是图的一部分

一个图可以快速完成，但仍然产生糟糕的答案。

一旦几个智能体开始搜索、分类和审查同一任务，主要问题就变成控制。

系统需要规则来决定哪些发现值得更深入的工作，哪些输出应该被拒绝，以及工作流何时已经搜索得足够。

按风险路由

路由器节点读取结构化输出并选择下一个分支。

分类可以来自模型，而分支本身在代码中保持显式。

const route =
  finding.severity === "high"
    ? runFullAudit(finding)
    : runQuickReview(finding);

这使得昂贵的审查集中在有重大影响的发现上。

一个有用的路由器依赖图可以检查的字段：严重性、置信度、受影响系统、财务暴露或缺失证据的存在。

添加独立验证

一个智能体审查自己的结论会将相同的假设带入两个阶段。

更强的图将重要发现发送给几个具有不同任务的审查者。

审查者不应该被指示改进原始答案。他们的任务是搜索它可能不完整或错误的原因。

图可以要求达成一致，然后才让发现继续前进：

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

隔离更改代码的智能体

并行编码智能体在编辑同一工作目录时可能会相互干扰。

一个智能体可能覆盖文件，而另一个仍在读取它。测试可能针对混合了不相关更改的代码运行。

Git 工作树为每个分支提供自己的仓库副本。

主仓库
      │
      ├→ worktree/auth-fix
      ├→ worktree/db-migration
      └→ worktree/test-repair

每个智能体可以在自己的环境中修改文件并运行测试。后面的节点比较补丁、检查冲突、并选择应该合并的内容。

这将隔离变成图的一部分，而不是手动清理步骤。

让发现收敛

有些任务无法在一次传递中完成。

仓库审计可能发现一个指向另一个包的依赖。那个包可能揭示另一个调用点。图需要一种受控的方式继续搜索，而不重复已经看过的内容。

const seen = new Set();
let dryRounds = 0;

while (dryRounds < 2) {
  const findings = await discoverNext([...seen]);
  const fresh = findings.filter(item => !seen.has(item.id));

  fresh.forEach(item => seen.add(item.id));
  dryRounds = fresh.length === 0 ? dryRounds + 1 : 0;
}

重要的细节是对每个之前看过的项去重。

仅对已确认的发现去重会使被拒绝或不确定的项在下一轮返回，并再次消耗相同的工作。

循环在若干轮无结果后停止，或者达到固定预算或最大迭代次数。生产图通常需要所有三个条件。

将模型与节点匹配

不是每个节点都需要最强可用的模型。

提取、基本分类和窄范围搜索通常可以在更快的层级上运行。架构审查、对抗性验证和最终综合可能需要更强的模型。

模型分层成为图的另一个属性。

预算由运行多少个节点、循环重复多少次、每条边携带多少上下文、以及每个阶段由哪个模型处理来决定。

一个包含二十个廉价搜索调用的图仍然可能比一个强模型调用更昂贵。架构需要 Token 预算，然后才需要另一个分支。

知道什么时候停止画图

小任务很少需要路由器、投票面板、工作树和收敛循环。

图的开销包括编排代码、模式、重试、日志记录、中间存储以及更多需要调试的失败状态。

当一个模型可以容纳相关上下文、任务几乎没有独立分支、且错误答案的成本很低时，线性工作流通常就足够了。

Graph工程随着任务获得并行工作、昂贵决策、大证据集或有意义的验证需求而变得有用。

完整的工作流最终可能看起来像这样：

价值来自于让工作的流动变得可见。

每个节点有有限的责任。每条边携带结构化证据。每个分支有存在的理由。每个循环有停止条件。

到那时，Claude Code 不再执行一条长指令。

它正在运行一个工程化的系统。

• 原文链接： x.com/Gyome1_/status/208...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～