Graph Engineering tutorial

Decide when one loop is enough and when work needs a graph. Then design one: nodes, edges and shared state, with limits on width, depth and spend.

Start the course

Course contents

Graph Foundations

  1. Loop or Graph? — Not everything should be a graph. See when one loop with a checker is the better shape, when work needs a graph of nodes, edges and shared state, and how to tell the two apart.
  2. Nodes, Edges, Shared State — Write a state contract: every field has one writer, every node reads only the fields it needs, and a checkpoint lets a crashed run resume.
  3. Prompt Chaining — Split one fat node into investigate, then write. The writer starts clean with a typed handoff, never sees the dead ends, and gets the answer right.
  4. Routing — Send each ticket down the right path: a cheap path for easy work, a careful path with a human gate for risky work, and a safe fallback when the router is unsure.
  5. Parallelization — Run independent checks at the same time without breaking them: one field per branch, a timeout on every join, and a join policy that says what happens when a branch is missing.
  6. Orchestrator-Workers — When the work list is only found while running, an orchestrator starts workers for it. Cap width, depth and spend, record what it really started, and keep a kill switch.
  7. Evaluator-Optimizer — A fixer and a checker go round until the work passes. Give the loop real exits for oscillation, no progress, a flat score and a budget, report a stop on a bound clearly, then export your first graph pack.

Graphs in Production

  1. Composing Patterns — Real graphs combine patterns. Build a review graph from parallel audits, a verifier join, a router, a fixer loop and a human gate, and grade it on a scorecard over 40 tickets.
  2. Observability and Replay — When a graph run goes wrong, compare it with a run that worked. Find the first node that differs, read per-node tokens and verdicts, and see where the money goes.
  3. Human Gates — Put a person on the risky path: auth, payments and data migrations stop for approval, with the diff, the tests and the reason shown. Leave the quick path alone, so approvals stay real.
  4. Capstone — Build one of three graphs for your project: a risk-routed issue graph, a codebase migration graph, or a review-and-fix graph. Grade it on 40 tickets, keep it no bigger than needed, and export a graph pack for your tools.

Reference

  1. Cheat Sheet — One page to come back to: loop or graph, the graph file format, the five patterns, state contract rules, exits, caps, join policies, gates, the scorecard, graph pack files per tool, and an error index for every linter rule.