What you will be able to do
- Explain graph engineering in one sentence and how it differs from LangGraph.
- Cut an agent's CLAUDE.md or AGENTS.md down to a short identity file.
- Turn a process your team repeats into a workflow with decisions, gates and standards.
- Prove a workflow's "no" paths by planting a failure on a throwaway task.
Key takeaways
- Graph engineering is designing an agent system as a graph: nodes do the work, edges decide what runs next, and state travels between them.
- Our take: the graph replaces the instructions file, which shrinks to an 8-line identity file.
- The process moves into workflows of steps, decisions and gates, and the rules move into standards read at the step.
- The task holds the state, so a short file carries work across separate sessions.
- The knowledge grows, the prompt does not.
The problem: a CLAUDE.md that keeps getting too long
Every team running an AI coding agent like Claude Code keeps an instructions file, and it only ever grows. CLAUDE.md, AGENTS.md, .cursorrules. It starts at twenty lines: who the agent is, how the repo is laid out, a few rules.
Then the lessons arrive. A bug the agent caused becomes a rule. Some rules belong in a hook, not a file: see how to stop Claude Code deleting your files. A process the team agreed on becomes a paragraph. A routing table appears: "for bugs do this, for features do that". Months later the CLAUDE.md is too long: hundreds of lines, and the agent follows some of it.
This is not a feeling. Anthropic's Claude Code best-practices docs say it plainly: bloated CLAUDE.md files cause Claude to ignore your actual instructions (Anthropic, Best practices for Claude Code(opens in new tab)).
Every line added to make the agent better makes every other line weaker. Graph engineering is how we get out of that trap.
What is graph engineering: the definition, and our take
Graph engineering is designing an agent system as a graph: nodes do the work, edges decide what runs next, and state travels between them. That is the common meaning, and we did not coin the term. LangGraph is a library for building such graphs. Graph engineering is the discipline.
Our take goes one step further. The graph replaces the instructions file. The agent never reads the whole process at once. It reads one step, does exactly that step, and advances. Three things take the place of the long file:
| What it replaces | What replaces it | In one line |
|---|---|---|
| The instructions file | An identity file of 8 lines | Who the agent is, and "follow the step, then advance" |
| The process paragraphs | Workflows: a graph of steps, decisions and gates | A request enters at one node, a decision sends it down the path that owns it |
| The rules paragraphs | Standards: plain markdown files, one per topic | The agent each step starts reads them at that step |
The line the whole idea hangs on: the knowledge grows, the prompt does not.
We run these graphs as ConvOps(opens in new tab) workflows, and every example below is one, shown on demo data.
The five parts of the graph
Our graphs have five kinds of part, and each one deletes a section of the old prompt.
| Part | What it is | What it replaces in the prompt |
|---|---|---|
| Step (node) | One unit of work with its own instructions: plan, build, run tests, review | "Always plan before coding, then..." |
| Decision | A node with several edges. It routes a request down the path that owns it, for example feature or bug | The routing table |
| Gate | A step that cannot move on without an explicit yes or no. Our gate steps tell the agent to stop and ask a person. A no sends the work to a fix step | "Always ask before you..." |
| Standard | A markdown file in standards/, read by the agent the step starts | Rules pasted into the prompt |
| State | The task, its current step and the note each step leaves on it | Re-explaining everything every session |
Why call it engineering? Because the work is choosing nodes and edges. Where a request enters. Which decision sends it where. Which agent reads which standards. Where a human has to say yes. Steps leave notes on the task, so the state survives any session.
A run, step by step: one task, three sessions
The smallest example shows the whole idea: one task crosses three sessions it never sees together, and the instructions file never says how. Take Brightloom, a fictional four-person team building a class-booking app for yoga studios. Their agent's whole instructions file, with the tool names in plain words:
# Who you are
You are the team's co-worker in this repo. The task system is your task list and your memory.
# How you work
1. Every request becomes a task: search first, then create one if none exists.
2. The task carries a workflow. Read the current step, do exactly what it says, then advance. Repeat until the workflow completes.
Nothing about planning, testing, approvals or resuming. One request goes in: "Add the cancellation policy to the booking confirmation email." The agent creates the task and the six-step workflow attaches itself: Intake, Analyze (approval), Implement, Verify (approval), Capture Learnings, Complete.
| Session | Told | What the agent does | Where it stops |
|---|---|---|---|
| 1 | The request | Intake, then a plan: edit emails/booking_confirmed.html, add one paragraph, check the preview | Analyze gate |
| Human | Approves outside the agent's session | ||
| 2 | "Continue where we left off." | Finds the open task, makes the change, writes a verification report: the preview renders, the paragraph is there | Verify gate |
| Human | Approves | ||
| 3 | "Continue where we left off." | Writes the learning note "email templates live in emails/", closes the task | Complete, 6 of 6 |
No session holds the state. Each new one turns "continue" into: find the active task, read its step, do that step. The identity file never says how, because the task already knows where it is.
A graph built by talking
We build graphs by describing them, not by coding them. Brightloom's lead describes the team's process in one conversation: a decision routes features and bugs apart, a planner writes a plan that waits for approval, bugs start with a failing test, and everything ends in a shared block of build, run tests and a code review that sends work back on a no. The agent turns that description into the workflows.
In a later conversation the lead asks for a standards review after the tests. The agent adds it as a small sub-workflow with its own fix loop, entered from a decision, and the task that adds it runs through the new step before it closes. The graph grows. The identity file does not change by a single line. Lessons land the same way: each one goes into the step or standard that needed it, the loop behind how we build a self-improving AI system.
Then a feature goes through: "Add a waitlist to full classes."
| Step | Who | Output | Gate |
|---|---|---|---|
| Triage: feature or bug | decision | Feature path | auto |
| Plan the feature | planner | join_waitlist(class_id, member), first-come order, promote on cancel, 5 tests | human yes |
| Build, then Run tests | developer, then the main session | waitlist.py and 5 tests, 5 passed | note |
| Standards gate, Standards review | standards-reviewer | Checked against standards/testing.md: 0 findings | human yes |
| Code review, round 1 | code-reviewer | "test_full_class_goes_to_waitlist never fills the class first, so it passes on an empty class" | human no |
| Fix review findings | developer | Fills the class to its capacity of 12 before joining | note |
| Run tests, standards, Code review round 2 | main session, standards-reviewer, code-reviewer | 5 passed, standards pass, no findings | human yes |
| Done | Task completed |
The no is the point. The reviewer catches a test that proves nothing, a human agrees, and the graph sends the work to Fix, then tests, then a second review. Nobody wrote "if the review fails, go back" into a prompt. It is an edge.
What goes wrong: handoffs and untested no paths
A graph moves the process out of the prompt. It does not make handoffs or untested paths safe on its own. We hit both.
The next agent does not read the notes. After Plan the feature, the developer agent starts with only its brief. The approved plan sits on the task as a step note it never opens, and a fresh session sees only short previews of the newest notes. The rule we run now: the main session puts the approved plan and the open findings into the next agent's brief. The note stays on the task as the record, and the brief carries what the next step needs.
A no path nobody has taken is unproven. Our first review loop validated clean, yet the first real no could not take the back-edge. A clean validation proves the shape, not the path.
The rule: plant a failure on a throwaway task and watch the no path run end to end. For Brightloom that means a function with no test: the standards review catches it, Fix adds the test, the re-check passes, and the throwaway task is cancelled.
When graph engineering is worth it
A graph is overhead for one-off work and pays for itself on anything the team repeats.
| Situation | Better choice |
|---|---|
| One-off scripts, exploration, a quick question | A plain prompt |
| A process the team repeats: features, bugs, releases, reviews | A graph. Each repeat runs the same steps |
| Several people or agents doing the same kind of work | A graph. The process lives in one place, not in each person's file |
| Work that needs a human yes before it goes further | A graph with gates. A gate is a node, so it waits for an approval on every run |
| An instructions file past a few hundred lines | A graph. Move the process out first, the rules second |
If your file is already past that point, CLAUDE.md too long? What to cut and where it goes walks through the line-by-line audit.
To try graph engineering on a process your team repeats, connect your agent to ConvOps(opens in new tab), describe the process, and run your next task through the workflow it builds. For a graph that runs on a schedule with nobody starting it, see how we run SEO experiments with Claude Code, or a self-healing website loop where each bug gets its own run in an isolated environment. To see a whole company run on these graphs, read how we run our company on workflows that remember. For other tools that run agent workflows, see the AI agent orchestration directory.
Frequently asked questions
What is graph engineering?
Graph engineering is designing an AI agent system as a graph: nodes do the work, edges decide what runs next, and state travels between them. In ConvOps the graph is a set of workflows the agent walks one step at a time, so the instructions file can shrink to an identity file of 8 lines while the process lives in the graph.
Is graph engineering the same as LangGraph?
No. LangGraph is a library for building agent graphs in code, and graph engineering is the discipline of designing them. With ConvOps the graph is a set of workflows the agent walks through its task tools, with no graph code in the repo. The design choices are the same either way: where a request enters, which decision routes it, and where the work stops for a yes.
What should I do when my CLAUDE.md is too long?
Move the process out, not only the rules. Sort the file into three piles: who the agent is stays, anything with an order of work becomes a workflow step, decision or gate, and every rule becomes a standards file. In ConvOps the workflows hold the steps, so each new lesson goes into a step or a standard instead of the file.
Does the CLAUDE.md or AGENTS.md file disappear?
No. It shrinks to an identity file: who the agent is, that every request becomes a task, and that it follows the current step and then advances. In the setup this guide shows that is 8 lines, and it does not change when the graph grows, because new process goes into workflows and new rules go into standards.
What stops the agent from skipping a gate?
The workflow. A gate step cannot advance without an explicit yes or no, and in ConvOps the gate step's own instructions tell the agent to stop and ask a person. The identity file never has to say "always ask before you deploy", because the stop sits on the step where it applies.
Do the agents need their own instructions?
Yes, short ones. Each role (planner, developer, code-reviewer, standards-reviewer) has an agent file of a few lines that says what it does and points it at standards/. The workflow step decides which role runs, so the role files stay small and the process stays in the graph.