Graph engineering: stop giving AI agents a to-do list

There is a specific moment on every build where I know the day has gone wrong. I have given Claude Code or Codex a long, careful instruction to do one thing after another and wire it all together. Around step six the agent starts rewriting something it finished at step two. The code is fine, but the agent has lost the plan. The plan, the code, the errors and my corrections all compete in one enormous context window.

A better model does not fix that failure, because the problem is the shape of the instruction. I handed the agent a to-do list when I should have handed it a map. The name that has stuck to the fix is graph engineering, and it has changed how I quote work, because it changes how much of the work gets thrown away.

What graph engineering means

Express the job as a graph rather than a sequence. Nodes are units of work, each small enough to hand to one competent person with one brief. Edges are dependencies: an arrow from A to B means B cannot start until A has produced something. Nodes with no arrow between them are independent, so they run at the same time. Where branches come back together you put a join node, which integrates the parallel results and checks they fit.

That is the whole idea. The lineage is worth knowing, because it explains why it works. Chain-of-thought prompting is a line: one thought after another. Tree-of-thought branches into alternatives but the branches never rejoin. The 2023 Graph of Thoughts paper made the jump explicit. Model the work as an arbitrary graph so results can merge, and you can get better answers for less compute. On a coding agent in 2026, the same shape is the difference between a build that lands and a build that gets rewritten twice.

One honest note on the label, because it matters if you are going to go and read about it. ‘Graph engineering’ is a new phrase, and it means at least three different things depending on who is writing. Some people mean orchestration frameworks, some mean agent memory stored as a graph, and some mean what I am describing here. It also collides head-on with knowledge graphs, a data-modelling idea that is completely unrelated. The underlying practice is decades older than the label: decompose, run the independent parts in parallel and verify at the joins.

What one long prompt does to a real project

Three specific failures, all of which I have caused myself and all of which end up on someone’s invoice as hours.

• It loses the thread. Everything the agent has read, tried, broken and fixed sits in one window. By step eight the original brief is thousands of lines back and competing with a stack trace from step three. Quality falls off a cliff long before the window is technically full.
• It redoes finished work. Nothing marked step two as done and not to be touched. A linear instruction has no such concept, so the agent is free to revisit it, and it will.
• One bad step poisons everything after it. If step four made a wrong assumption about your database schema, steps five through ten are all built on it. You do not find out until the end, and the fix then covers everything downstream of step four.

Anyone who has bought software knows the pattern. Most of the build arrives quickly, and the last stretch drags on for weeks. The cause is compounding rework in a linear plan, and the model is rarely to blame.

The same job, as a graph

Take a build I ship often: an internal quoting tool. A database schema, an API layer, a UI, an integration into the accounting system, and a test suite. Linear, it is one prompt with five stages and every stage inheriting the mess of the last one. As a graph it looks like this.

The schema node runs alone, because everything else needs its answer. Then the API, UI and integration nodes run at once, each in a fresh context holding only the contract and its own brief. The UI agent never reads the integration agent’s half-finished work, because it cannot see it. Then one join node takes the finished branches and does the only job that needs the whole picture: wire them together and prove it works.

Two rules make that hold up in practice, and both are learned the hard way:

• Every node owns a disjoint set of files. That is a hard boundary. Two agents editing the same file in parallel is how you get a merge conflict written by two things that cannot talk to each other.
• A node hands over evidence. That means the files changed, the command that verifies them, the exit code and what is still risky. A bare ‘done’ is worthless, because the next node should check rather than trust.

The same shape holds once the software is running. In Nora, the AI platform I run, one brain reads each WhatsApp or email message and hands it to whichever agent owns that job. The result goes back to the channel it came from. It is the same decomposition, at runtime instead of build time, and it is animated on the Nora home page if you want to watch a job travel through it.

Why this matters if you are paying for the build

What you are paying for is a working system on a date. Here is what the technique means for that.

• Calendar time compresses. Three independent branches running in parallel take about as long as the slowest one. On a multi-week build that saving is measured in days.
• Rework drops. In my experience the biggest source of wasted hours in AI-assisted development is an agent undoing its own finished work. Nodes with owned files and a done condition remove the opportunity.
• Failure stays local. When the accounting integration hits an undocumented API quirk, as it will, that node retries and the finished UI branch stays untouched. In a linear run the same problem invalidates everything after it.
• Progress becomes legible. ‘Three of five nodes green, integration blocked on their sandbox credentials’ is a status report you can act on. ‘It’s nearly there’ is a guess.
• It is why a fixed price is possible. Every project I take on is a fixed price, quoted after a short scoping chat, and I can only do that because I can bound the work. You cannot bound work whose failure mode is unbounded rework.

The software is no smarter for any of this, and the model is the same model. The structure around it is what stops good work being thrown away.

A graph is only as good as what its nodes can reach

Everything above depends on one thing I glossed over: each node starts in a fresh context. Fresh means clean, and it also means ignorant. A node that knows nothing about your business asks the questions the last node asked and repeats its wrong assumptions. It rediscovers in the afternoon what another agent found that morning. Parallelism multiplies that waste.

The fix is a place the work can write things down. In April 2026 Andrej Karpathy published a short idea file called llm-wiki, and the framing in it is the useful part: stop treating an LLM as something that answers questions from documents, and start treating it as something that compiles documents into knowledge. Retrieval re-derives an answer from scratch every single time you ask. Compilation writes the answer down once and keeps it current, so the knowledge compounds.

The setup people have converged on is deliberately boring, which is why it works. Three parts, all plain files:

• Raw sources, never edited. Transcripts, specs, exported tickets, the PDF of their accounting API docs. Dropped in as-is so every later claim has something to point back to.
• Generated pages. Markdown the agent writes and rewrites, with one page per entity, decision or system. Each page summarises the raw material and cites it.
• A rules file that governs both, in practice a CLAUDE.md. It sets what gets a page, how pages are named, what must be cited and when something is marked stale. Without it you get a chatbot with a folder.

Three operations run against it: ingest a new source, query it with citations, and lint it. Linting, the one everyone skips, means the agent hunts for contradictions, stale claims and pages nothing points at. Karpathy’s file has been re-implemented on GitHub more times than I can count and there are decent step-by-step write-ups of it in MindStudio’s guide and elsewhere. The commonly-shared version pairs it with an Obsidian vault, purely so a human can read and edit the same files the agent is writing. Obsidian is optional. The three parts are not.

What I keep in there for a client build is unglamorous. It records the schema decisions and why the alternatives lost, the quirks of third-party APIs and who signs off on what. It also holds the constraint someone mentioned once on a call in week one, which is exactly what gets asked twice.

It is the same idea running inside Nora, the AI platform I run. Its home page block is headed ‘your channels, your tools, one AI brain’. Messages arrive from WhatsApp, email and the web, different agents handle different jobs, and they all read and write one shared store. That is the only reason a WhatsApp reply can know what was agreed in an email three weeks earlier.

The buyer’s version of this is about the second invoice. If your second project with the same developer costs the same as the first, nothing was retained. Mine get cheaper, because the discovery work is written down where the next build’s agents can read it.

‘Why is it built like that’ also gets an answer with a date on it. And it answers the bus-factor worry: the knowledge sits in files you own, outside any one person’s head or chat history.

The links matter more than the notes

Here is where most people building one of these stop too early. They generate hundreds of tidy pages, feel productive, and end up with a filing cabinet. A pile of notes answers the questions you already knew to ask, which are the cheap ones.

The expensive question is the one where you do not know what you are missing. That only gets answered when the entries point at each other.

A concrete version, from my own workspace. There is a page for a client. It links to a page for the quoting tool I built them. That links to a page recording that their accounting sandbox rate-limits at sixty calls a minute and silently drops the rest. Nobody filed those three facts together; each was written on a different day for a different reason. So when someone asks to add a nightly invoice sync for that client, the answer comes back with the rate limit attached. Nobody had to remember it, because it was one hop from the client page. Unlinked, that fact is discovered again the hard way, in production, on a Friday.

That is the spine of this piece: in both halves, nodes are cheap and edges carry the value. Writing the units, a work node or a wiki page, is the easy part, and it looks like progress.

The dependency between two nodes and the reference between two pages carry the real information. They get skipped because they feel like admin. A graph with no edges is a to-do list, and a wiki with no links is a folder.

Two honest caveats, because this is easy to oversell.

• Links have to be made at write time, and they rot. An agent that files a new page without connecting it to anything has just added noise. That is what the lint pass is for, and skipping it is how these things quietly die a few months in.
• A wrong link is worse than no link. A confidently connected page that is out of date will be pulled into an answer as if it were true. Everything needs a date and a source, and anything that cannot be traced back to a raw file gets treated as a rumour.

One clarification, since the words collide badly in this field. A knowledge graph in the database sense has formal entities and typed relationships you query. That is a separate tool with its own reasons to exist. What I am describing is markdown files with links in them, maintained by an agent. Far less rigorous, far cheaper, and enough for most of what an SMB build needs.

Where it does not help

The technique is fashionable right now, and fashion makes people apply it everywhere.

Small tasks should stay linear. Fixing a bug, adding a field or changing some copy takes one agent, one context and a few minutes. Wrapping that in a dependency graph adds planning and handover overhead to a job that had none. I do those linearly every day.

Genuinely sequential work stays sequential. The test is simple: can at least two pieces of work progress without reading each other’s unfinished output? If every step edits the same file, schema or migration, a graph is a straight line drawn with more ceremony. A data migration where each step reworks the last one’s output is a queue.

And a graph of agents can agree with itself all the way to a wrong answer. This is the failure mode I watch for hardest. Several agents on the same model, reading the same flawed assumption, will validate each other very confidently and produce something beautifully organised and wrong. The only defence is evidence from outside the system: real tests that execute, a real staging environment, and a human who looks at it. A verification node that just asks another agent ‘does this look right?’ is decoration.

So every node in my graphs ends with a check a machine can run, such as a passing test suite or a clean build.

Three questions to ask whoever is building for you

1. How is this work broken up, and what runs in parallel? You are checking there is a plan with structure. If the answer describes one long continuous session, expect the final stretch to run long.
2. What proves each piece is finished? The good answer names a command and an outcome, such as the tests passing or the sandbox call returning. The weak answer is a description of what was written.
3. What happens when one part fails? You want to hear that it is retried in place while everything else stands. If failure means starting the run again, the plan was a line.

None of these need you to know anything about AI. They are the same questions you would ask a builder about a house, and the answers tell you the same thing about whether the person has done this before. More in that vein in questions to ask before hiring an AI developer.

The short version

Prompting an agent linearly on a real project makes it hold the entire problem in one head, forever. Structure the same job as a graph, with small nodes, explicit dependencies, owned files and verified handovers. Then each part of the work only ever holds what it needs.

The effect on the finished software is nil. The effect on how much work gets thrown away on the way there is large, and that is the part you pay for.

Related reading

• How to spec a custom AI system: the one-page brief that becomes the graph
• How to estimate cost and time: the five-step framework behind the number
• Why AI projects fail: the non-technical reasons, which are most of them
• How custom AI development works: the six-stage method