Graph Engineering for AI Coding Agents: Context, Contracts and Repair

"Graph engineering" has been getting a lot of attention lately, and most explanations dwell on graphs, nodes and DAGs. Those parts matter, but they don't answer the question that actually deserves asking: why would AI coding agents suddenly need graph engineering at all?

A developer who spent months with tools like Claude Code and later Codex noticed a pattern. Most coding tasks don't fail because the model can't write code. They fail because long-running workflows slowly lose their structure. Context drifts out of sync, requirements are forgotten, outputs get hard to verify, and when something goes wrong the easy fix is often to restart the whole task.

That observation led to a small research framework called ContractGraph. The account below follows its ideas, what held up and what broke. It wasn't built to compete with existing frameworks, and it isn't tied to a particular model. The goal was narrower: could a workflow be designed so that each step has a clear objective, a well-defined contract and a deterministic way of deciding whether the step is really finished?

The outcome was a contract-driven graph that ran a research workflow through isolated tasks, explicit validation and targeted repair, in place of one giant prompt. The first implementation targeted research agents, but the underlying ideas apply just as well to coding agents, document pipelines, evaluation systems and any process where several AI-driven steps must produce results you can verify. Keep in mind that this is one practitioner's experiment, so the conclusions are experience and not measured benchmarks.

What graph engineering means

Graph engineering is the practice of splitting a complex AI workflow into small execution units and linking them with explicit rules. A graph-engineered system usually combines several execution units, explicit routing, shared state, verification and durable coordination.

One responsibility per node. Edges pick the next step. State shared across the workflow carries information along, and a verification stage rules on whether to continue, retry, repair or halt.

The two questions behind the design

Expecting to spend most of the time on nodes, edges and execution flow, the developer found those weren't the hard part. Two questions kept returning.

First: what information should an AI agent be allowed to treat as true? Second, once it finishes a task: how can you tell the output really meets what was asked?

The more long-running workflows were tested, the clearer it became that these questions outweighed the graph itself. An agent that starts from wrong information, or finishes with no reliable way to check its work, just carries mistakes from one node to the next. The two questions became Context and Contract. Context defines what an agent is allowed to believe, and the contract defines what it must produce. Everything else in the framework hangs off those two ideas.

Context and contracts as building blocks

The graph wasn't the hardest piece. The real challenge was making sure each node began with the right information and produced something verifiable before the workflow moved on.

Context. Agents shouldn't see everything. A node gets just the material it may trust, for example user requirements, project constraints, verified documents, or accepted results from earlier nodes.

Contract. Every node needs a clear definition of what it must deliver. When a result falls short of the contract, the workflow can't just march on regardless. It should check the output, fix the broken step, or halt.

Put simply, context sets what an agent may believe and contracts set what it must deliver. Once both boundaries are explicit, the graph is much easier to reason about. Every node gets one purpose, a narrow source of truth, an output that can be measured, and a deterministic gate before the next step starts.

From an idea to an executable graph

With context and contracts separated, the next question is how they become a runnable workflow. Hardcoding a separate graph for research, coding or document generation was not the aim. The workflow should instead be compiled dynamically from the problem itself, not from predefined paths. Two steps come first.

The first step builds the context. Not every file or document deserves equal trust, so the workflow assembles a canonical context: a validated source of truth that all nodes can lean on. Its raw material varies by task, such as project docs, user requirements, code, design documents or other inputs judged reliable.

The second builds the contract. Rather than describing the task in prose alone, it produces a structured contract stating what each stage must produce, how nodes depend on each other and what must be validated before execution proceeds.

With both in place, the workflow is compiled. This initialisation stage executes nothing. Its job is planning. Out of it come the execution graph, a scoped packet of context for every node, reusable manifests and shared skills, plus an execution order worked out from the contracts, with no hardcoded sequence.

Execution is then straightforward. A node receives only its scoped context, does its assigned work, goes through deterministic validation, saves the accepted result and passes control along. If validation fails, only the affected node is repaired before execution resumes, so nothing restarts from scratch.

The graph's structure therefore comes from the context and contracts supplied at the start and not from a fixed implementation. The same compilation pipeline can assemble workflows for research, coding, documentation or something else entirely, without changing the runtime.

Testing it on larger and smaller models

Designing a framework is only half the job. The tougher question is whether the architecture holds up once a workflow is large enough to expose its weaknesses.

The first experiments used a much bigger workflow running in Claude Code, with dynamically generated execution nodes, nested planning stages and long research tasks. Quality was excellent, but finishing the workflow demanded a large amount of model computation.

That raised a follow-up. Could the same graph architecture still yield reliable workflows on a much smaller, cheaper model? A second experiment used a study-plan generation workflow, executed through OpenCode with Big Pickle instead of a frontier model. The mechanics stayed the same: the workflow was compiled dynamically, specialised nodes were generated, each stage was validated deterministically, failures were repaired where needed, and the final artefact came out of the same pipeline.

The purpose wasn't to compare models or crown a winner. It was to see how much of the reliability came from the execution architecture rather than from the model's raw ability. The surprising finding was that the biggest problems weren't model failures at all. They were workflow failures, and that's where graph engineering became interesting.

Where it broke

The experiment didn't show that graph engineering prevents failures. It showed that graph engineering makes failures visible.

Along the way came all sorts of trouble: incomplete metadata, missing evidence, unresolved references, duplicated content, invalid lifecycle states, wrong trace information and even plain encoding problems. The graph didn't cause any of them. They are the failures you'd expect from long-running AI workflows.

What changed was that every failure had an exact location. Rather than treating the whole run as one failed execution, it was possible to find the specific node that broke its contract, repair only that node, run deterministic validation again and resume from there. The rest of the workflow stayed intact because every successful stage had already been verified and saved.

That changed how the developer saw the technique. It wasn't a way to make models smarter. It was a way to make failures local, observable and recoverable. The graph didn't eliminate mistakes, but it gave each mistake an address.

Why validation has to be deterministic

A model can say with total confidence that a task is complete, and that doesn't make it true. Language models reason, summarise and decide very well, but they're an unreliable judge of whether a workflow has met its own requirements.

That's why every node in ContractGraph finishes with a deterministic check. Nobody asks a second model for an opinion on the output. The workflow tests objective conditions. Does the schema have every field it needs? Have the dependencies been met? Are the required artefacts there, and do the references resolve? Did the node hand over all that its contract promised? These aren't subjective calls. Each is simply true or false.

That separation proved to be among the most valuable ideas in the framework. The model concentrates on reasoning, and deterministic validation handles verification. A model can argue that its work is finished, but only a deterministic validator can prove that a required field is missing.

Why the extra effort can pay off

Even before this experiment, the developer treated AI coding agents as a small team and not a single assistant. It wasn't unusual to have Claude Code, Codex and OpenCode working on different parts of one repository simultaneously.

That created an unexpected problem. Agents could end up needing to change the same files or rely on the same implementation, and without coordination one could overwrite another's work or invalidate assumptions made earlier.

The fix was simple: every task had an owner. If an agent was responsible for part of the codebase, the others couldn't touch those files until the owner let go. Add a validation pass after each major step, and many conflicts never reached the repository.

The trade-off was plain. This style of development uses far more tokens than asking one model to build a feature in a single conversation, because every validation, retry, repair and coordination step adds work. Yet the result felt different. Instead of repeatedly fixing regressions caused by earlier fixes, the workflow became much more predictable, and features shipped this way needed little rework because each stage was verified before the next began.

Graph engineering isn't something every prompt should use, and for small changes it's pure overhead. For larger features, long implementations or multi-agent work, the extra cost buys something more valuable than cheap inference. It buys confidence.

What it really costs

Nobody should read this as a claim that graph engineering is a silver bullet. Preparing context, generating contracts, compiling the graph, validating, repairing and aggregating each cost extra model calls and tokens. Next to a single prompt, the workflow is undeniably pricier.

The earliest experiments with frontier models gave excellent results but burned a lot of compute, which was a main reason for testing smaller, cheaper models. The lesson was that graph engineering doesn't reduce compute. It deliberately reallocates it. Rather than spending computation on recovering from regressions, restarting failed workflows or patching downstream errors over and over, the system spends it up front on planning, verification and failure isolation.

That changes the optimisation target. Graph engineering isn't built to produce the cheapest execution. It's built to produce the most predictable one. One OpenCode run chewed through a large volume of tokens. That figure shouldn't be read as proof that the approach is cheap. If anything they show the opposite, since graph engineering knowingly spends more computation to gain failure isolation, auditability, resumability and confidence. Whether that's a good trade depends entirely on the problem.

When it's worth it

Graph engineering isn't needed by every AI workflow. For a SQL query, a small function or a few UI tweaks, a well-written prompt is usually enough, and adding contracts, validation layers and execution graphs would only make things slower and more complicated.

It starts to shine when the cost of failure exceeds the cost of extra computation. That covers long-running research, large feature work, multi-agent workflows, security-sensitive systems, enterprise automation and any process whose output must be verifiable and reproducible. The more steps a workflow has, the more explicit coordination is worth.

The main lesson isn't about intelligence. Where a workflow is complicated, the structure makes it simpler to follow, check, recover and extend. The idea is also far from finished. Dependency-aware execution, smarter scheduling, resource optimisation, partial graph recompilation and richer coordination between agents all remain unexplored. A short version of the lesson: use prompts to solve tasks, and use graph engineering to build systems.

Closing thoughts

Starting out, the expectation was to learn about graphs. What the exercise really taught was boundaries, verification and coordination. The graph wasn't what mattered. What mattered was a clear purpose for every step, a limit on what an agent may believe, a definition of what it must produce, and proof of completion before anything moves on.

This isn't the only way to build AI systems, and not every workflow deserves this much structure. But for complex, long-running or multi-agent work, graph engineering offers a practical route to systems that are more predictable and easier to evolve.

If a single sentence has to be remembered, make it this chain: a prompt states the wish, the context fixes what the agent can take as fact, the contract spells out the deliverable, and the graph is the mechanism that shows the work is finished.

ContractGraph was still evolving at the time of this experiment, and its repository hadn't been published, because the architecture was due to be simplified first. For a broader introduction to the topic, search for a general graph engineering guide, since this account covers one framework and not the whole field.