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 — do this, then this, then this, then wire it together — and around step six the agent starts rewriting something it finished at step two. It is not confused about the code. It is confused about the plan, because by then the plan and the code and the errors and my corrections are all sitting in one enormous context window, competing.

That failure is not a model problem and it does not get fixed by a better model. It is a shape problem: 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 actually means

Express the job as a graph rather than a sequence. Nodes are units of work — each one small enough that you would hand it to a single competent person with a single 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: something integrates the parallel results and verifies they actually 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” only became a phrase in July 2026, 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, which are a data-modelling idea and completely unrelated. The underlying practice — decompose, run the independent parts in parallel, verify at the joins — is decades older than the label and is the part worth caring about.

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 is not step four — it is everything downstream of step four.

Add those up and the pattern is familiar to anyone who has bought software: the first 70% arrives in two days and the last 30% takes three weeks. That is not the model being weak. That is compounding rework in a linear plan.

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 three nodes run at once — API, UI, integration — each in a fresh context that contains the contract and its own brief and nothing else. The UI agent never reads the integration agent’s half-finished work, because it cannot see it. Then one join node takes the three finished branches and does the only job that genuinely 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. Not a suggestion, 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, not assurances. Files changed, the command that verifies it, the exit code, what is still risky. “Done” on its own is worthless. The downstream node should be able to check rather than trust.

The same shape holds once the software is running, not just while it is being built. In Nora, the AI platform I run, a message arriving on WhatsApp or email is not marched through a checklist — one brain reads it and hands it to whichever agent owns that job, and the result comes 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

You are not buying prompting technique. You are buying a working system on a date, so here is the translation.

• Calendar time compresses. Three independent branches finishing in parallel take about as long as the slowest one, not the sum of all three. On a multi-week build that is days, not minutes.
• Rework drops. The single 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 — and it will — that node retries. The UI branch, finished an hour ago, is untouched. Compare that with a linear run where 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 about 70% there” is not.
• It is why a fixed price is possible. I quote fixed prices from $4,000 because I can bound the work. You cannot bound work whose failure mode is unbounded rework.

None of this is a claim that the software is smarter. 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. That is the point — fresh means clean. It also means ignorant. A node that knows nothing about your business asks the same three questions the last node asked, makes the same wrong assumption about your invoicing rules, and rediscovers at 4pm the thing another agent discovered at 11am. Parallelism multiplies that waste rather than removing it.

The fix is not a longer prompt. It 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. Knowledge that compounds versus knowledge that resets.

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 — one page per entity, per decision, per system — each summarising the raw material and citing it.
• A rules file — in practice a CLAUDE.md — that governs both. What gets a page, how pages are named, what must be cited, when something is marked stale. Without it you get a chatbot with a folder. With it you get a maintained wiki.

Three operations run against it: ingest a new source, query it with citations, and — the one everyone skips — lint it, meaning have the agent hunt for contradictions, claims that have gone stale 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 actually keep in there for a client build is unglamorous: the schema decisions and why the rejected alternative was rejected, the quirks of their third-party APIs, who signs off on what, the constraint someone mentioned once on a call in week one. None of it is clever. All of it is the stuff that gets asked twice.

It is the same idea running inside Nora, the AI platform I run — the home page block is literally 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 rather than each keeping private notes. 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 simple and it is about the second invoice, not the first. If your second project with the same developer costs the same as the first, nothing was retained. Ours get cheaper, because the discovery work is written down in a form the next build’s agents can read directly, and because “why is it built like that” has an answer with a date on it rather than a shrug. It is also the honest answer to bus-factor: the knowledge is in files you own, not in one person’s head or one 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 is not a brain. It 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 — and 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 “can we add nightly invoice sync for them?”, the answer comes back with the rate limit already attached — not because anyone remembered it, but because it was one hop from the client page. Unlinked, that fact is discovered again the hard way, in production, on a Friday.

Which is the spine of this whole piece, so let me say it plainly: in both halves, nodes are cheap and edges are where the leverage is. Writing the units — a work node, a wiki page — is the easy part, and it is the part that looks like progress. The dependency between two nodes, the reference between two pages: that is the part that carries the actual information, and it is the part that gets skipped because it feels like admin. A graph with no edges is a to-do list. A wiki with no links is a folder. Same failure, twice.

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 about four 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: this is not the same thing as a knowledge graph in the database sense — formal entities, typed relationships, something you query. That is a real and 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

I am going to be blunt here, because the technique is currently fashionable and fashion makes people apply things everywhere.

Small tasks should stay linear. Fix a bug, add a field, change some copy — one agent, one context, done in minutes. Wrapping that in a dependency graph adds planning and handover overhead to a job that had none. I do it linearly every day and so should anyone else.

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 the answer is no — if every step edits the same file, the same schema, the same migration — then a graph is a straight line drawn with more ceremony. A data migration where each step transforms the output of the last one is not a graph. It 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.

That is also why every node in my graphs finishes with something machine-checkable — a migration that runs, a suite that passes, a build that compiles. Not an opinion from another model.

Three questions to ask whoever is building for you

1. How is this work broken up, and what runs in parallel? You are not auditing the technique, you are checking there is a plan with structure. If the answer describes one long continuous session, expect the last 30% to run long.
2. What proves each piece is finished? The good answer names a command and an outcome — the tests pass, the build succeeds, the sandbox call returns. 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. Structuring the same job as a graph — small nodes, explicit dependencies, owned files, verified handovers, parallel where it is genuinely parallel — means 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 actually works — six-stage methodology