Claude Code のためのグラフエンジニアリング完全ガイド

大多数の人は、まだ Claude Code を非常に高額なインターンのように使っています。

1 つのタスクを与え、1 つの回答を待ち、次に何が起こるかを手動で決めています。

しかし、AI から最も大きなレバレッジを得ているチームは、小さな分散システムに近いものを作り上げています。

1 つのエージェントが問題の範囲を定めます。

5 つの安価なエージェントが並行して検索します。

決定論的なスクリプトが重複を排除します。

3 つの懐疑的なエージェントが結果を検証しようと試みます。

1 つのトップクラスのモデルが最終判断を下します。

それがグラフエンジニアリングです。

読み進める前に:

このガイドをブックマークしておけば、自身の Claude Code ワークフローを構築し始める際に、グラフパターンを参照できます。

そして、フォローしてください

@Gyome1_ -

私は Claude Code、AI エージェント、そして1つのモデルを信頼性の高いエンジニアリングワークフローに変えるシステムについて解説しています。

私は数週間かけて、実際のエージェントアーキテクチャ、ワークフロー図、プロダクションパターンを分析し、グラフエンジニアリングを1つの実践的なプレイブックに再構築しました。

より長いプロンプトを書く代わりに、情報がシステムを通過する経路を設計します。

線形 → ファンアウト → リデュース → 検証 → 統合

各エージェントは、限定されたジョブを持つノードになります。各エッジは構造化データを運びます。ルーターはどのブランチを実行するかを決定します。検証器は弱い出力を拒否します。ループは、グラフが新しい発見を見つけられなくなるまで続きます。

重要な変化は、Claude Code がもはや巨大なチェックリストをこなす1つのインテリジェンスとして振る舞う必要がなくなったことです。

オーケストレーションコードを生成し、専門化されたサブエージェントの集団を起動し、それらの出力を異なるモデルにルーティングし、エビデンスが検証を通過した後にのみ最終結果を組み立てることができます。

基本的なパターンは新しいものではありません。ソフトウェアエンジニアは、DAG、パイプライン、バリア、MapReduce、分散ワーカーを何十年も使用してきました。

変わったのは、各ノードの内部に何が配置されるかです。

ノードは、リポジトリを検索したり、マイグレーションを監査したり、アーキテクチャ上の決定に異議を唱えたり、テストの失敗を調査したり、50 の独立した調査結果を1つの引用付きレポートに統合したりできます。

このガイドでは、最も単純な線形エージェントから、ダイヤモンドグラフ、ルーターノード、敵対的検証パネル、収束ループ、モデルティアリング、そして Claude Code 内で直接生成される動的ワークフロー まで、システム全体を分解します。

このガイドを読み終える頃には、大きなタスクを見て、こう問うことはなくなるでしょう。

「どんなプロンプトを書けばいいんだ？」

1. グラフエンジニアリングはコストから始まる

グラフエンジニアリングは、より多くのエージェントを実行する方法として提示されることがよくあります。

しかし、その枠組みでは高コストの部分を見落としています。

同じリポジトリに対して 20 の Claude エージェントを起動すると、重複したレポート、繰り返しのコンテキスト、矛盾する結論、そしてはるかに大きな API コストが発生する可能性があります。

有用なグラフは、計算をどこで実行するか、各決定をどのモデルが処理するか、不確実な調査結果がワークフローをどのように通過するかを制御します。

Claude Code にプロダクションマイグレーションの準備を依頼する場面を想像してみてください。

リポジトリを調査し、すべての依存関係を見つけ、マイグレーションを提案し、リスクを特定し、計画を検証し、最終的な概要を作成してください。

1 つのプロンプト内では、これは長く不透明なプロセスになります。Claude はコードベースを検索し、調査結果をコンテキストに保存し、マイグレーションを設計し、自身の計画をレビューし、最終レポートを作成します。

レポートが失敗した場合、失敗の原因を特定するのは困難です。Claude がファイルを見逃したか、依存関係を誤解したか、以前の詳細を失ったか、または検証中に弱い仮定を受け入れた可能性があります。

また、タスクの一部が単純な抽出や並べ替えである場合でも、すべての段階が同じ高価なモデルで実行される可能性があります。

グラフエンジニアリングはそのワークフローを開放し、すべての決定に可視性を与えます。

検査ブランチは、同じスコープのタスクを使用し、互いの出力に依存しないため、同時に実行されます。

それらの調査結果はリデュース段階で合流し、重複が排除され、エビデンスがより小さなデータセットに圧縮されます。

次にルーターが重大度を読み取ります。定型的な変更は軽量なレビューに進みます。リスクの高い調査結果は、最終モデルに到達する前に、複数の独立したレビュー担当者によるより深い分析を受けます。

結果として、レイテンシ、モデルコスト、コンテキストサイズ、検証の深さがグラフの構造を通じて制御されるワークフローが実現します。

ノードは1つの決定を行うべきである

有用なノードは、明確に範囲が限定された責任を持ちます。

非推奨 API へのすべての呼び出しを見つけてください。 各マイグレーションリスクを低、中、高に分類してください。 ロールバック計画を障害ケースについてテストしてください。

各ノードには、明確な入力、定義された出力、そして限定された決定範囲が必要です。

リポジトリを検索し、ビジネスへの影響を見積もり、修正を設計し、推奨事項を書くノードは、依然として複数の隠れた段階を含んでいます。中間の推論が1つのモデル呼び出しに埋もれているため、デバッグは困難なままです。

より小さな境界により、エビデンスがシステムにどこで入り、その意味がどこで変わったかが明らかになります。

エッジはエビデンスを運ぶべきである

エッジは、次のノードが必要とするデータを表します。

スキャナーは、予測可能なオブジェクトを返すことができます。

1{
2  "file": "src/auth/session.ts",
3  "lines": [84, 119],
4  "dependency": "legacySessionClient",
5  "confidence": 0.94,
6  "evidence": "Both call sites depend on the deprecated refresh method."
7}

リスク分類子は、すべての調査結果に対して同じフィールドを受け取るようになりました。不完全な結果を拒否し、関連するファイルをグループ化し、不確実なエビデンスを別のレビューにルーティングできます。

スキーマは、ノード間の解釈のずれを減らします。自由形式の段落は、下流のすべてのエージェントに前のエージェントの意味を再構築することを強制します。いくつかの段階を経ると、小さなあいまいさが最終的な結論を変える可能性があります。

構造化された出力は、エビデンスがグラフを移動する間、安定した状態を保ちます。

一部のノードは通常のコードである

8 つの検索エージェントが 80 の調査結果を返したとします。

ワークフローは、配列を結合し、空の応答を破棄し、重複を削除し、残りのアイテムを並べ替える必要があります。

これらの操作には決定論的な答えがあります。

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

JavaScript の変換はこれを瞬時に処理し、毎回同じ出力を生成します。同じタスクを別のモデルに送信すると、トークンコストが追加され、エビデンスが消失する可能性のある別の場所が生まれます。

モデルノードは、検索、分類、比較、レビュー、統合の周りに配置します。コードは、検証、重複排除、並べ替え、明示的なルーティングルール、およびその他の予測可能な変換を処理できます。

この分割がグラフの基盤となります。

すべてのモデル呼び出しは、真に判断を必要とする決定に対応する必要があります。

2. ダイヤモンド：実際のエージェントグラフがどのように作業を移動させるか

ほとんどの本格的なエージェントグラフは、最終的に同じ形状になります。

タスクは1つの共有スコープから始まり、複数の独立したワーカーに分割され、それらの出力を待ち、エビデンスを圧縮し、結果を最終決定に渡します。

その形状がダイヤモンドです。

左側は ファンアウト です。

すべてのブランチが出会う中間点は バリア です。

右側は ファンイン です。

このパターンは、タスクが1つのコンテキストウィンドウに対して大きくなりすぎると、どこにでも現れます。

リポジトリ監査はサブシステムごとに分割できます。市場レポートはソースごとに分割できます。リサーチタスクは仮説ごとに分割できます。マイグレーションレビューは、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 で行われます。各ブランチは限定されたタスクを受け取り、検証済みのオブジェクトを返します。

結果は、フィルタリング、検査、および次の段階に渡すことができる出力のコレクションとして届きます。

大規模なファンアウトであっても、各ブランチの背後には理由が必要です。

1 つのあいまいな割り当てを 12 のほぼ同一のエージェントに分割すると、多くの場合、わずかに異なる表現で繰り返しの調査結果が生成されます。有用な並列性は、異なるソース、視点、コード領域、または仮説から生まれます。

バリアが決定ポイントを作成する

バリアは、必要なブランチが完了するまで次の段階を一時停止します。

その一時停止は重要です。なぜなら、一部の決定は完全なセットに依存するからです。

ランキングノードは、リポジトリの半分がまだ検査されている間は、最も重要な脆弱性を特定できません。統合モデルは、デプロイレビューがまだ実行中である間は、完全なマイグレーションプランを作成できません。

バリアでは、グラフは実行の状態を検査する機会を得ます。

1const completed = findings.filter(Boolean);
2
3if (completed.length < MIN_REQUIRED_RESULTS) {
4  throw new Error("Insufficient audit coverage");
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つのあいまいな要約に圧縮し、検証に必要な詳細を消去する可能性があります。

最も安全なパターンは、リデュースされた各主張とそのソースアイテムとの間のリンクを維持することです。

1{
2  "risk": "Session refresh may fail after migration",
3  "severity": "high",
4  "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],
5  "evidence": [
6    "Three services call the deprecated refresh method",
7    "No fallback path exists",
8    "Integration coverage is missing"
9  ]
10}

これで、統合ノードはトレーサビリティを失うことなく、より小さなデータセットを受け取ります。

3. 信頼性はグラフの一部である

グラフは迅速に完了しても、悪い回答を生成する可能性があります。

複数のエージェントが同じタスクの検索、分類、レビューを開始すると、主な問題は制御になります。

システムには、どの調査結果がより深い作業に値するか、どの出力を拒否すべきか、いつワークフローが十分に検索したかを決定するルールが必要です。

リスクに応じてルーティングする

ルーターノードは構造化出力を読み取り、次のブランチを選択します。

分類はモデルから得られますが、ブランチ自体はコード内で明示的に保持されます。

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

これにより、高価なレビューは意味のある影響を持つ調査結果に集中します。

有用なルーターは、グラフが検査できるフィールド（重大度、信頼度、影響を受けるシステム、金銭的リスク、または欠落しているエビデンスの有無）に依存します。

独立した検証を追加する

自身の結論をレビューするエージェントは、両方の段階に同じ前提を持ち込みます。

より強力なグラフは、重要な調査結果を異なる割り当てを持つ複数のレビュー担当者に送信します。

レビュー担当者は、元の回答を改善するように指示されるべきではありません。彼らのタスクは、それが不完全または間違っている可能性がある理由を探すことです。

グラフは、調査結果が前に進む前に同意を要求できます。

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

コードを変更するエージェントを隔離する

並列コーディングエージェントは、同じ作業ディレクトリを編集すると互いに干渉する可能性があります。

あるエージェントがファイルを上書きしている間に、別のエージェントがまだファイルを読み取っている可能性があります。テストが無関係な変更の混合に対して実行される可能性があります。

Git ワークツリーは、各ブランチにリポジトリの独自のコピーを提供します。

1main repository
2      │
3      ├→ worktree/auth-fix
4      ├→ worktree/db-migration
5      └→ worktree/test-repair

各エージェントは、独自の環境内でファイルを変更し、テストを実行できます。後続のノードがパッチを比較し、競合をチェックし、マージするものを選択します。

これにより、隔離が手動のクリーンアップステップではなく、グラフの一部になります。

発見を収束させる

1 回のパスで完了できないタスクもあります。

リポジトリ監査により、別のパッケージを指す依存関係が明らかになる場合があります。そのパッケージにより、別の呼び出しサイトが明らかになる場合があります。グラフには、既に見たものをすべて繰り返すことなく、検索を続けるための制御された方法が必要です。

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}

重要な詳細は、以前に見たすべてのアイテムに対して重複排除を行うことです。

確認された調査結果に対してのみ重複排除を行うと、拒否または不確実なアイテムが次のパスで戻ってきて、同じ作業を再度消費する可能性があります。

ループは、数回の空のラウンド、固定された予算、または最大反復回数の後に停止します。プロダクショングラフでは通常、これら 3 つすべてが必要です。

モデルをノードに合わせる

すべてのノードに最強のモデルが必要なわけではありません。

抽出、基本的な分類、狭い検索は、多くの場合、より高速なティアで実行できます。アーキテクチャレビュー、敵対的検証、最終統合は、より強力なモデルを正当化する場合があります。

モデルティアリングは、グラフのもう 1 つのプロパティになります。

予算は、いくつのノードが実行されるか、ループがどのくらいの頻度で繰り返されるか、各エッジを通過するコンテキストの量、および各段階をどのモデルが処理するかによって決定されます。

20 の安価な検索呼び出しを持つグラフでも、1 つの強力な呼び出しよりもコストがかかる場合があります。別のブランチが必要になる前に、アーキテクチャにはトークン予算が必要です。

描き終えるタイミングを知る

小さなタスクに、ルーター、投票パネル、ワークツリー、収束ループが必要になることはめったにありません。

グラフのオーバーヘッドには、オーケストレーションコード、スキーマ、リトライ、ロギング、中間ストレージ、およびデバッグすべきより多くの障害状態が含まれます。

1 つのモデルが関連するコンテキストを保持でき、タスクに独立したブランチがほとんどなく、誤った回答のコストが低い場合、通常は線形ワークフローで十分です。

グラフエンジニアリングは、タスクに並列作業、高価な決定、大規模なエビデンスセット、または意味のある検証要件が伴う場合に有用になります。

完全なワークフローは、最終的に次のようになります。

価値は、作業の流れを可視化することにあります。

すべてのノードには限定された責任があります。すべてのエッジは構造化されたエビデンスを運びます。すべてのブランチには存在する理由があります。すべてのループには停止条件があります。

その時点で、Claude Code はもはや 1 つの長い指示を実行しているのではありません。

それは、エンジニアリングされたシステムを実行しているのです。