Claude Code Graph Engineering: Orchestrate Agent Teams Safely

Graph engineering is a workflow pattern, not a Claude Code command. You turn a large goal into a dependency graph, run only the independent nodes in parallel, and unlock integration or verification nodes after their prerequisites pass.

Claude Code agent teams can execute this pattern because teammates share a task list and tasks can depend on other tasks. The safe setup is small: one lead, two or three independent workers, explicit file ownership, and a final verification node. Do not start dozens of agents on one codebase and hope the graph appears by itself.

Loop Engineering vs Graph Engineering

A loop gives one agent a goal, feedback, and another turn. A graph coordinates several bounded loops.

Use a graph only when at least two tasks can progress without reading each other's unfinished output. If every step edits the same file, schema, lockfile, or migration, keep the work sequential.

Prerequisites

You need:

• Claude Code 2.1.32 or later;

• a Git repository with a clean starting state;

• targeted validation commands for each task;

• a task that can be partitioned by outcome and file ownership.

Check the version and repository state:

claude --version
git status --short
git branch --show-current

Expected result: Claude Code meets the minimum version, git status --short is empty, and you recognize the current branch.

Agent teams are experimental and disabled by default. They also use more tokens than one session, and Anthropic documents current limitations around session resumption, coordination, and shutdown. Start with one disposable trial before using a team on production work.

Step 1: Draw the Dependency Graph Before Spawning Agents

Write the graph as a table. Each row needs one outcome, its prerequisites, owned files, and proof of completion.

The first node fans out to api and ui. Those nodes fan in at integrate. verify is a separate node so the agent that wrote the code is not the only one judging it.

Do not use vague nodes such as "work on backend." A node should produce an observable artifact or result that a dependent node can consume.

Step 2: Enable Agent Teams

Add the experimental flag to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

If the file already contains an env object, merge the new key instead of replacing the object. Restart Claude Code after saving it.

Start a normal session from the repository root:

claude

Expected result: Claude starts in the intended repository and can create an agent team when you explicitly approve one.

Step 3: Give the Lead the Whole Graph

Use a prompt that names the graph, ownership boundaries, and gates:

Create an agent team for this change with one lead and three teammates.

First create a shared task list with these nodes and dependencies:
1. contract has no dependency and writes only docs/plan.md.
2. api depends on contract and owns src/api/** plus focused API tests.
3. ui depends on contract and owns src/ui/** plus focused UI tests.
4. integrate depends on api and ui and owns only the integration boundary.
5. verify depends on integrate and must not edit feature code.

Do not start a blocked node. Do not let two teammates edit the same file.
Every completed node must report changed files, exact commands, exit codes,
test counts, and unresolved risks. Stop the team if the repository is dirty
before work starts or if the ownership boundaries cannot be kept.

Replace the sample paths and checks with real ones from your repository. Expected result: the lead creates a shared task list, api and ui remain blocked until contract completes, and integrate remains blocked until both worker nodes complete.

Claude Code manages task dependencies automatically. When all prerequisites of a pending task are complete, the task becomes available. That dependency behavior is the useful mechanism behind the graph.

Step 4: Partition Files, Services, and Permissions

Agent teams coordinate work, but Anthropic's current agent-team implementation does not isolate every teammate in a separate Git worktree. File ownership is therefore a hard boundary, not a suggestion.

Give each node:

• a disjoint set of files;

• a distinct local port if it starts a service;

• a separate test database or fixture namespace when supported;

• the minimum tools and permissions it needs;

• one validation command it can run without modifying another node's output.

If two nodes must edit the same shared type, migration, lockfile, generated client, or route registry, assign that file to the integrate node. Workers can describe the required change in their handoff instead of racing to write it.

For stronger filesystem isolation, use separate Claude Code worktree sessions instead of agent-team teammates. The detailed setup is in How to Run Parallel Claude Code Agents With Git Worktrees.

Step 5: Make Every Edge Carry Evidence

A graph edge should carry a small, reviewable handoff. Require this format from every worker:

Node:
Outcome:
Changed files:
Validation command:
Exit code:
Tests passed:
Artifacts or IDs produced:
Known risks:

The dependent node should verify the artifact instead of trusting "done." For code, that means inspecting the diff and rerunning a focused check. For an external operation, it means re-reading the object by its stable provider ID.

This avoids a common failure mode: one worker declares success, the lead marks the node complete, and downstream work starts against an output that was never created or tested. See How to Verify AI Coding Agent Tests Actually Pass for a deeper verification contract.

Step 6: Monitor the Frontier, Not Every Token

In the agent-team interface:

• press Ctrl+T to show or hide the shared task list;

• use Shift+Down to move between the lead and teammates;

• interrupt a worker that crosses its ownership boundary;

• check why a node is blocked before creating another worker.

The useful status is the graph frontier: tasks whose prerequisites are complete and which can safely start now. More active agents are not automatically more progress.

Pause the team when:

• two workers need the same file;

• a worker discovers a missing prerequisite;

• a validation command mutates shared state;

• the combined change no longer matches the original contract;

• token or rate limits make the parallel run slower than a single session.

Update the task dependencies or return the work to one owner. Do not hide a real dependency by telling agents to "coordinate."

Step 7: Add External Work as a Bounded Node

External systems fit a graph when the node has a stable input, a scoped Action, and a verifiable output. Keep provider credentials out of prompts and repositories.

If Aident Loadout is not installed, tell Claude Code:

Follow https://aident.ai/SETUP.md

Then add a read-only external node:

Add a research-evidence node with no write access. Confirm Aident Loadout
account and Vault status, find one connected read-only Action, inspect its
current schema, and execute it with a harmless input. Record the canonical
Action name, normalized input, returned provider object ID or URL, and execution
result. The verify node must re-read or otherwise validate that evidence

Expected result: one schema-inspected Action succeeds without a provider key in the prompt. If the workflow later needs a write, create a separate approval-gated node and verify the provider state before unlocking downstream work.

Step 8: Fan In Once, Then Verify

The integrate node should be the only owner of shared glue:

1. inspect each worker handoff;

2. review the combined diff;

3. resolve shared types and generated artifacts once;

4. run the integration checks;

5. hand the combined state to verify.

The verify node should run from the final combined state and report exact commands and results. It should not quietly repair feature code. A failed check sends work back to the node that owns the failure.

Expected result: every changed file has one owner, every dependency is satisfied before its consumer starts, and the final evidence is reproducible from the combined diff.

Common Graph Engineering Failures

The Lead Spawns Too Many Teammates

Start with two or three workers. Agent teams add context, messaging, and token overhead. Expand only when the task graph contains more independent ready nodes than the current team can use.

Two Teammates Edit the Same File

Stop one worker. Move the shared file to an integration node or switch to isolated worktree sessions. A merge conflict is evidence that the ownership graph was wrong.

A Dependent Task Starts Early

Inspect the shared task list and correct the dependency. A verbal instruction such as "wait for the API" is weaker than an explicit task dependency.

One Worker Says "Done" Without Proof

Keep the node incomplete until its handoff includes the diff, exact validation command, exit code, and observable result. Completion is a state transition, not a sentence.

The Team Burns Tokens Without Converging

Reduce the graph. Keep research branches independent, limit peer discussion, and give one lead authority over fan-in decisions. Sequential work is better when dependencies dominate.

Shutdown Leaves Teammates Running

Ask the lead to shut down every teammate and confirm the shared task list has no in-progress node before exiting. Agent-team shutdown is still experimental, so inspect running sessions rather than assuming cleanup succeeded.

Why This Works

A dependency graph makes concurrency explicit. Independent nodes can run together, blocked nodes cannot start early, and fan-in happens at a named integration boundary. File ownership limits collisions, while evidence-carrying handoffs keep downstream work from trusting an unverified claim.

The pattern applies the structure that continues to work for Aident's Ollama networking guide: name the exact problem, give a direct answer, provide reproducible steps and expected results, cover failure modes, and explain the mechanism.

Test One Five-Node Graph

Connect one read-only integration through Aident Loadout, then run the five-node sample with two independent implementation nodes, one integration node, and one verification node. Success means no file has two owners, blocked work never starts early, all five nodes carry evidence, and the external Action succeeds without a provider credential in the prompt.

Sources

• Orchestrate teams of Claude Code sessions, Anthropic, accessed July 30, 2026

• Run agents in parallel, Anthropic, accessed July 30, 2026

• Run parallel sessions with worktrees, Anthropic, accessed July 30, 2026

• Create custom subagents, Anthropic, accessed July 30, 2026

• Loop & Graph Engineering, Reddit, published July 24, 2026

• Graph Engineering with Claude, Reddit, published July 25, 2026

• Graph Engineering explained in 8min, YouTube, published July 30, 2026

Refresh this guide when Anthropic changes agent-team availability, task dependencies, teammate isolation, task-list controls, version requirements, permissions, or shutdown behavior.