Claude Code Graph Engineering Masterclass: Build AI Systems That Think in Graphs

Welcome back to the Claude Code Masterclass. Special thanks to all new members who have joined to support the newsletter.

In the last issue, we covered loop engineering from first principles: what a loop is, the four phases every loop runs through, and the three things that make one work in production.

We also showed all three Claude Code loop commands, /goal, /loop, and /schedule, running on real projects.

By the end of that issue, one question was left unanswered: what happens when a single loop is not enough?.

Some tasks cannot be done well by only one agent.

When your loop starts reviewing its own work, running tasks sequentially that could run in parallel, or producing control flow that you cannot audit, that loop has hit the ceiling.

In this issue, we will cover graph engineering and testing in a real project that proves the difference between a loop and a graph.

One of the most common misconceptions is that loops are replacing graphs. It’s not true that you throw away the loops when you build graphs.

The best way to understand how the two work together is one line:

A loop is a node in a graph

Each node inside a graph is still running a loop.

The graph is the structure that connects those loops, routes work between them, and manages what they pass to each other.

Not every loop should become a graph. Most should stay as loops, but there are reasons to consider turning a loop into a graph.

1. Same agent is reviewing its own work

If the loop writes a report and then reviews in the same context, the reviewer already knows why every decision was made. You will see this as outputs that pass review but contain errors that an outside reader would immediately catch.

2. Two things could run simultaneously but must run one after the other

If the loop checks security vulnerabilities, then checks logic errors, then checks test coverage, those three checks are independent.

3. You cannot explain what the loop did without reading the entire transcript

In a graph, you can point to the diagram and explain every routing decision.

Graph engineering is building multiple specialized agents (nodes) connected by edges, with shared structured state flowing between them, where the routing logic between nodes is explicit and readable as a diagram.

The three words: specialized, explicit, and readable.

• Specialized: each node has one job and its own clean context

• Explicit: every routing decision is defined in code or in the graph structure

• Readable: you can explain the control flow by pointing to the diagram

• Node: The unit of work that gets clean input, does one thing, produces structured output. If you cannot describe a node’s job in five words or fewer, it is doing too much.

• Edge: What is allowed to happen next. A fixed edge means Node A always goes to Node B. The question every edge answers: what is allowed to run after this?

• Conditional Edge: The decision point. When the output of Node A determines which node runs next, that is a conditional edge. The routing decision can be made by code (deterministic rules) or by an LLM (uncertain decisions that require reasoning).

• State Machine: The complete shape of the graph. Every node is a state the work can be in. A check at each node decides the next hop. When you draw the graph on paper, you are drawing the state machine.

• Shared State: The structured object that flows between nodes. Every node reads from it, writes its findings to it, and passes it to the next node. This is the backbone of the graph. What belongs in shared state: brief, evidence, node status, retry counts, severity, findings.

• Agent Loops: The loop engine running inside each node. Each node is not a single call. It is a small loop that discovers, plans, executes, and verifies until the node’s specific job is done. The internal loop stop condition is different from the graph routing condition.

It helps to understand the layers of AI engineering that position the graph as the outermost layer.

Graph engineering has been evolving for the last two years.

LangGraph shipped the StateGraph pattern in 2024.

AutoGen, Google ADK, and the A2A protocol were building graph orchestration before "graph engineering" became a trend.

But what’s new :

• Parallel specialized nodes with clean contexts

• Fan-out then fan-in as a first-class architectural move

• Control flow you can draw as a diagram before writing the first prompt

A graph is the right tool when a loop fails at one of three things. Here is each problem with its visual and its graph solution

Context Pollution

Solution

Sequential vs Parallel Execution

Invisible Control Flow

I thought about a real graph running in Claude Code to solve one of the most common engineering problems.

Suppose it’s 2 AM, five microservices are down, and you have 1000 lines of error logs from five different services all firing at once.

A basic approach is to paste everything into Claude Code and ask it to find the root cause.

The loop version can’t handle this mess; this is the sequence

• All five service logs in one context. Service A errors mix with Service B errors

• The database errors look most severe and appear most frequently

• The loop identifies database connection pool exhaustion as the root cause.

When you fix the database, nothing improves because the database was not the problem.

What happened was this:

To build the best graph solution, you should design the graph before writing any code.

Every node reads from and writes to one structured object:

The key rule: each node owns one section of state.

• Parser writes raw_logs

• Analyzers write service_findings[service_name]

• Correlator writes correlations and cascade_chain

I ran the same codebase through two loop vs graph agents , the project is our test project.

Claude Code Tracker a FastAPI application with JWT authentication, SQLAlchemy database layer, and a pytest test suite.

The codebase has bugs, security gaps, and code quality problems scattered across four files.

The goal for both architectures: find everything wrong with this codebase.

We can test the loop version in Claude Code by running one loop to review the code which we obviously know its the same that wrote the code and it cant be objective

It produced a detailed report bit this cannot be fully trusted since it’s a self agent review.

In the loop version, one Claude Code session reads the entire codebase, identifies bugs, writes the report, and then reviews its own report.

This is how most developers use Claude Code for code review today. It is the natural single-session approach but has a fundamental problem

By the time the agent reaches the review step, it has already processed every file.

The agent knows why it included each finding and reasoning behind every severity rating. It cannot evaluate the report the way an independent reviewer agent can.

A better approach is to use the graph engineering concept of three agents working together towards a common goal and each handling one task in a clean context.

The graph approach is to spawn three agents each with clean content and agent 3 reviews the report without ever seeing the code one the findings which gives it an independent review.

1. Open Claude Code

2. Navigate to your project

3. Confirm agent teams are enabled in your settings.json: “CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS”: “1”

4. Set effort to high: /effort high

Wait until you see AGENT 1 COMPLETE in the output.

Open a NEW Claude Code session or spawn a sub-agent. Navigate to the same project folder. Use this prompt:

Wait for AGENT 2 COMPLETE.

Open another NEW Claude Code session or spawn another sub-agent. Navigate to the same project folder. Use this prompt:

After all three finish, your project root should have:

• agent1_context.json — codebase map

• agent2_findings.json — bug/security findings

• agent3_review.json — independent audit of those findings

The graph version ran as three separate Claude Code sessions. Each agent saw only what it needed to see.

• Agent 1: Context Gatherer Reads every file in the codebase. Produces a structured JSON map of the architecture, endpoints, authentication system, database layer, and file inventory. Output: agent1_context.json is a precise architectural summary of the project.

• Agent 2: Bug Hunter Receives only agent1_context.json. Never sees the raw source files. Uses the architecture map to guide a fresh read of the codebase and produces structured findings

  It found 12 issues:

• Agent 3: Independent Reviewer Receives only agent2_findings.json. Never saw the codebase, architecture map and Agent 2's reasoning process.

In comparison graph approach is more independent, reliable and ideal for large codebases.

Graph engineering shows us that the benefit of using more than one agent is real.

While loops are reliable at small tasks, they cannot be relied on when you are building something that requires independent evaluation.

The Claude Code example we ran was a small demo to show what is possible. In a large production project with hundreds of files and multiple services, this approach becomes very useful.

The four missing categories Agent 3 caught in a small codebase would be multiplied in a large codebase.

The next step is to see how this works in LangGraph, because that is where graph engineering shows its true production benefits.

You define the nodes, edges, and shared state in code and the graph becomes something you can version, test, and deploy.

We will build the graph engineering demo in LangGraph in the next issue

For this issue, these are the resources available:

• Testing Repo

• Tested Loop Templates Prompt (Members Resource Library)

The next issues in this Masterclass Series will cover:

• Claude Code Subagents Masterclass — Building your AI team

• Claude Code MCP Masterclass — Extending Claude’s capabilities

If you found this useful, do not forget to like share and subscribe for more insights. Let me know your thoughts and questions in the comments below.

Let’s Build It Together

— Joe Njenga