How context, contracts, deterministic validation, and targeted repair shaped ContractGraph.
Over the past week, I've been experimenting with something that's been getting a lot of attention recently: Graph Engineering.
When I first started reading about it, almost every explanation focused on graphs, nodes, and DAGs. Those are important pieces of the puzzle, but I couldn't shake the feeling that they weren't answering the question I actually cared about.
Why do we suddenly need graph engineering for AI coding agents?
After spending months using tools like Claude Code and, more recently, Codex, I noticed something interesting. Most coding tasks don't fail because the model can't write code. They fail because long-running workflows gradually lose structure. Context becomes inconsistent, requirements get forgotten, outputs become difficult to verify, and when something goes wrong, the easiest solution is often to start the entire task again.
That observation eventually led me to build a small research framework called ContractGraph.
I didn't build it to compete with existing frameworks, and I didn't build it around a particular model. My goal was much simpler: could a workflow be designed so that every step had a clear objective, a well-defined contract, and a deterministic way to decide whether it was actually complete?
The result was a contract-driven graph that orchestrated a research workflow through isolated tasks, explicit validation, and targeted repair instead of treating the entire workflow as one giant prompt.
Although my first implementation focused on research agents, the underlying ideas are much broader. The same approach could be applied to coding agents, document pipelines, evaluation systems, or any workflow where multiple AI-driven steps need to produce reliable, verifiable results.
This article isn't a tutorial on building graph frameworks, nor is it a comparison between Claude Code, Codex, LangGraph, or any other tool. It's a walkthrough of the ideas that led me to build ContractGraph, what worked, what broke, and why I now think graph engineering is less about drawing DAGs and more about designing reliable AI workflows.
A Quick Note on Graph Engineering
Graph engineering is the practice of breaking a complex AI workflow into smaller execution units and connecting them through explicit rules.
A graph-engineered system usually contains:
- Multiple execution units + explicit routing + shared state + verification + durable coordination
Each node handles one responsibility, edges decide what happens next, shared state carries information across the workflow, and verification checks whether the system should continue, retry, repair, or stop.
The Two Questions That Kept Bothering Me
When I started exploring graph engineering, I expected to spend most of my time thinking about nodes, edges, and execution flow. Surprisingly, those weren't the hardest parts.
Two questions kept coming back.
What information should an AI agent be allowed to treat as truth?
And once it finishes a task,
How do I know the output actually satisfies what I asked for?
The more I experimented with long-running AI workflows, the more I realized these questions mattered far more than the graph itself. If an agent starts with the wrong information or finishes without a reliable way to verify its work, the graph is simply moving mistakes from one node to another.
Those two questions eventually became the foundation of everything I built.
I called them Context and Contract. One defines what an agent is allowed to believe. The other defines what it must produce.
Everything else in ContractGraph was built around those two ideas.
Context and Contracts: The Two Building Blocks
The more I worked with AI workflows, the more obvious one thing became: the graph itself was not the hardest part.
The real challenge was making sure every node started with the right information and produced something that could be verified before the workflow moved forward.
That led me to two ideas.
The first was Context.
Instead of giving every agent access to everything, each node should receive only the information it is allowed to trust. That could include user requirements, project constraints, verified documents, or accepted outputs from earlier nodes.
The second was Contract.
Every node should have a clear definition of what it must produce. If the result does not satisfy that contract, the workflow should not continue as though nothing happened. It should validate the output, repair the failed step, or stop.
In simple terms:
Context defines what an agent is allowed to believe.
Contracts define what an agent must deliver.
Once those two boundaries are explicit, the graph becomes much easier to reason about. Every node has a clear purpose, a limited source of truth, a measurable output, and a deterministic check before handing control to the next step.
From an Idea to a Graph
Once Context and Contracts were separated, the next question became:
How do these two ideas turn into an executable workflow?
I didn't want to hardcode different graphs for research, coding, document generation, or any other task. The goal was to compile a workflow dynamically from the problem itself rather than from predefined execution paths.
That process begins with two simple steps.
The first constructs the Context.
Rather than treating every file or document as equally trustworthy, the workflow builds a canonical context: a validated source of truth that every node can rely on during execution. Depending on the task, that context might be derived from project documentation, user requirements, source code, design documents, or other trusted inputs.
The second constructs the Contract.
Instead of describing the task in natural language alone, it generates a structured contract that defines what every stage must produce, how nodes depend on one another, and what must be validated before execution can continue.
With those two building blocks in place, the workflow is compiled.
The initialization stage doesn't execute anything yet. Its job is to plan. It produces the execution graph, prepares scoped context packets for each node, generates reusable manifests and shared skills, and determines the execution order directly from the contracts instead of relying on hardcoded logic.
Execution then becomes surprisingly simple.
Each node receives only its scoped context, performs its assigned work, passes through deterministic validation, persists the accepted result, and hands control to the next node. If validation fails, only the affected node is repaired before execution resumes, avoiding a full restart of the workflow.
The result is a graph whose structure is determined by the context and contracts supplied at the beginning of the workflow rather than by a fixed implementation. The same compilation pipeline can therefore assemble workflows for research, coding, documentation, or entirely different problems without changing the underlying runtime.
The diagram below illustrates the execution lifecycle I experimented with while building ContractGraph.
Putting ContractGraph to the Test
Designing the framework was only half the challenge. The more important question was whether the architecture would continue to hold once the workflow became large enough to expose its weaknesses.
My first experiments used a much larger workflow running in Claude Code. It consisted of dynamically generated execution nodes, nested planning stages, and long-running research tasks. The overall quality was excellent, but one limitation quickly became apparent: completing the workflow required a significant amount of model computation.
That naturally led to a question:
Could the same graph architecture still produce reliable workflows on a much smaller, lower-cost model?
To explore that, I designed a second experiment around a study-plan generation workflow. Instead of relying on a frontier model, I executed the compiled graph through OpenCode using Big Pickle. The underlying execution model remained the same. The workflow was compiled dynamically, generated specialized execution nodes, validated every stage deterministically, repaired failures when necessary, and assembled the final artifact through the same graph pipeline.
The objective wasn't to compare models or argue that one was better than another. It was to understand how much of the workflow's reliability came from the execution architecture itself, rather than from the capabilities of the underlying model.
The results surprised me.
The biggest challenges weren't model failures.
They were workflow failures.
And that's where graph engineering became interesting.
Where It Broke
The experiment didn't convince me that graph engineering prevents failures.
It convinced me that it makes failures visible.
During execution, I encountered all kinds of issues: incomplete metadata, missing evidence, unresolved references, duplicated content, invalid lifecycle states, incorrect trace information, and even simple encoding problems. None of these were caused by the graph itself. They were exactly the kinds of failures you'd expect to see in long-running AI workflows.
The difference was that every failure had a precise location.
Instead of treating the entire workflow as a single failed execution, I could identify the exact node that violated its contract, repair only that node, run deterministic validation again, and continue execution from that point onward. The rest of the workflow remained intact because every successful stage had already been verified and persisted.
That fundamentally changed how I thought about graph engineering.
I stopped seeing it as a way to make models smarter.
I started seeing it as a way to make failures local, observable, and recoverable.
The graph didn't eliminate mistakes.
It gave every mistake an address.
Why Deterministic Validation Matters
One thing became clear during the experiment.
An AI model can confidently tell you that a task is complete. That doesn't mean it actually is.
Large language models are excellent at reasoning, summarizing, and making decisions, but they're not a reliable way to verify whether a workflow has satisfied its own requirements.
That's why every node in ContractGraph ends with deterministic validation.
Instead of asking another model whether the output "looks good," the workflow checks objective conditions: Is the required schema complete? Are all dependencies satisfied? Is every required artifact present? Are references resolved? Has the node actually produced everything its contract promised?
These aren't subjective questions. They're either true or false.
That separation turned out to be one of the most valuable ideas in the framework.
I let the model focus on reasoning, while deterministic validation focused on verification.
In other words:
A model can argue that its work is complete. A deterministic validator can prove that a required field is missing.
Why I Still Think It's Worth It
Long before I started experimenting with graph engineering, I had already been treating AI coding agents as a small team rather than a single assistant. It wasn't unusual for me to have Claude Code, Codex, and OpenCode working on different parts of the same repository at the same time.
That introduced a problem I hadn't anticipated.
Different agents could eventually need to modify the same files or depend on the same implementation. Without coordination, one agent could unintentionally overwrite another's work or invalidate assumptions made earlier in the workflow.
My solution was surprisingly simple. Every task had ownership. If an agent was responsible for a particular part of the codebase, other agents weren't allowed to modify those files until ownership was released. Combined with validation after every significant step, that prevented many conflicts before they reached the repository.
The trade-off was obvious.
This style of development consumes significantly more tokens than asking a single model to generate a feature in one conversation. Every validation, retry, repair, and coordination step adds additional work.
But the outcome felt different.
Instead of repeatedly fixing regressions introduced by previous fixes, the workflow became much more predictable. When I shipped features using this approach, they required remarkably little rework because every stage had already been verified before the next one began.
I don't think graph engineering is something every prompt should use. For small changes, it's unnecessary overhead.
But for larger features, long-running implementations, or workflows involving multiple agents, I think the additional cost buys something much more valuable than cheaper inference.
It buys confidence.
The Actual Cost of Graph Engineering
If this article has made graph engineering sound like a silver bullet, it isn't.
Every capability comes with additional work. Context preparation, contract generation, graph compilation, deterministic validation, targeted repair, and final aggregation all require extra model calls and tokens. Compared to a single prompt, the workflow is undeniably more expensive.
I experienced that firsthand.
My earliest experiments used frontier models and produced excellent results, but they also consumed a substantial amount of model computation. That became one of the main reasons I wanted to explore whether the same architecture could run on smaller, lower-cost models.
What I learned was simple:
Graph engineering doesn't reduce compute. It deliberately reallocates it.
Instead of spending computation recovering from regressions, restarting failed workflows, or repeatedly fixing downstream mistakes, the system spends it upfront on planning, verification, and failure isolation.
That changes the optimization target.
Graph engineering isn't designed to produce the cheapest execution.
It's designed to produce the most predictable execution.
During one of my OpenCode experiments, the workflow processed approximately:
These numbers shouldn't be interpreted as "graph engineering is cheap." If anything, they demonstrate the opposite. Graph engineering intentionally spends additional computation to gain something more valuable: failure isolation, auditability, resumability, and confidence.
Whether that trade-off is worthwhile depends entirely on the problem you're solving.
When Graph Engineering Is Worth It
After spending time building and experimenting with ContractGraph, I don't think graph engineering is something that every AI workflow needs.
If you're asking an AI to generate a SQL query, write a small function, or make a few UI changes, a well-written prompt is usually enough. Adding contracts, validation layers, and execution graphs would only make the workflow more expensive and more complicated.
Where I think graph engineering starts to shine is when the cost of failure becomes higher than the cost of additional computation.
That includes long-running research tasks, large feature implementations, multi-agent workflows, security-sensitive systems, enterprise automation, or any process where the output needs to be verifiable and reproducible.
The more steps a workflow contains, the more valuable explicit coordination becomes.
For me, the biggest takeaway wasn't that graph engineering makes AI smarter.
It makes complex AI workflows easier to understand, validate, recover, and evolve.
I also don't think we've reached the end of this idea.
There are still many areas I haven't explored, such as dependency-aware execution, smarter scheduling, resource optimization, partial graph recompilation, and more advanced coordination strategies between agents. Those are experiments for another day.
For now, one thing has become clear to me:
Use prompts to solve tasks. Use graph engineering to build systems.
Final Thoughts
When I started exploring graph engineering, I thought I was going to learn about graphs.
Instead, I ended up thinking much more about boundaries, verification, and coordination.
Building ContractGraph changed the way I think about AI workflows. The graph itself wasn't the interesting part. The interesting part was giving every step a clear purpose, limiting what an agent is allowed to believe, defining what it must produce, and proving that the work is actually complete before moving forward.
I don't think this is the only way to build AI systems, and I certainly don't think every workflow needs this level of structure. But for complex, long-running, or multi-agent workflows, I believe graph engineering offers a practical way to make AI systems more predictable and easier to evolve.
If there's one idea I'd like you to take away from this article, it's this:
Prompt engineering tells an agent what you want. Context defines what it's allowed to believe. Contracts define what it must produce. Graph engineering determines how the system proves that the work is complete.
ContractGraph is still evolving, so I'm not publishing the repository just yet. Before I open-source it, I want to simplify the architecture and make sure the ideas are presented clearly rather than tied to my own experiments.
If you're working on graph engineering, agentic workflows, or reliable AI systems and would like to discuss the architecture, validation pipeline, or some of the implementation details, feel free to reach out. I'm always happy to exchange ideas with people exploring this space.
Once the framework reaches a point where I think it's genuinely useful to others, I'll publish a sanitized version of the repository along with the supporting documentation.
This article is not a complete guide to graph engineering. For a broader introduction, refer to this guide:
https://www.aibuilderclub.com/blog/graph-engineering-guide-2026
📖 Blog by Naresh B. A.
👨💻 Backend & AI Systems Engineer | Distributed Systems · Production ML
🌐 Portfolio: [Naresh B A]
📫 Let's connect on [LinkedIn] | GitHub: [Naresh B A]
Thanks for spending your precious time reading this. It's my personal take on a tech topic, and I really appreciate you being here. ❤️
Top comments (0)