Loop Engineering: The Complete Guide

TL;DR - The leverage in agentic development moved from writing prompts to designing the loop that prompts the agent. A loop is a recursive goal with a verifiable stop condition. This guide is the reading path across all nine parts of the series plus the self-improving spin-off, grouped into four phases so you always know which deep-dive to open next. Jump to the reading path →

📚 What’s in this guide:

• A one-paragraph, citable definition of loop engineering
• The five building blocks and one memory spine, mapped to the deep-dive posts
• A phase-ordered reading path: Foundations, Infrastructure, Practice, Appendix
• The pillar-vs-guide distinction, so you know what this is and is not
• A pick-your-path section and an FAQ built for direct citation

Prompting each turn (the old bottleneck)   → you are the loop body
A loop: recursive goal + verifiable stop   → the system prompts the agent,
  condition, iterated until it holds          you approve the result

The series has ten posts now: nine numbered parts and one spin-off. If you have read one out of order, or you bought the premise from Part 1 and want the parts list, this is the map. This loop engineering guide does one job: it indexes the series into a reading path you can return to as your own loops grow. It doesn’t re-argue whether loops are real. Part 1 does that. This is navigation.

If you want the theory, read the pillar post. If you want the parts list with a loop that runs, read Part 2. This post sits above both: a hub that points you at the right deep-dive for where you are right now.

What is loop engineering?

Loop engineering is designing a recursive goal for a coding agent: a purpose plus a verifiable stop condition the system iterates against until the condition holds, without a human prompting each turn. The plain version, credited to Matt Van Horn, is cron plus a decision-maker in the body. The model is the commodity. The loop is the leverage.

Here is the canonical definition the series uses, word for word:

A loop is a recursive goal: you define a purpose and a verifiable stop condition, and the system iterates agents against it until the condition holds — without you prompting each turn.

The shift is concrete. For two years the point of control was the prompt. Then it was the context. Then it was the harness, everything around the model that makes it reliable. A loop is that harness feeding itself: the floor you built, now running on its own pulse until a checkable condition says stop.

Key insight: The harness was the floor. A loop is that floor feeding itself. The model stays commodity, so the differentiator is no longer what you type each turn, it is the recursive goal and the stop condition you design once and let run.

For the full argument, the four-era history (prompt, context, harness, loops), and a six-item readiness check you can run in an afternoon, read the pillar post. This guide assumes you’re convinced and need the route.

How to use this loop engineering guide

Read this loop engineering guide in phases, not in one sitting. The series has a natural arc: understand what a loop is, give it infrastructure to run on, then watch it work and fail in production. The four phases below map to that arc. Each phase is a section with the deep-dive links, a one-line gloss per part, and a key insight you can carry into a design review.

The phases are cumulative. Foundations (Parts 1 to 3) defines the thing. Infrastructure (Parts 4 to 6) gives it persistence, parallelism, and a pulse. Practice (Parts 7 to 9) shows a real retrofit, a reusable blueprint, and the failure modes. The Appendix covers the self-improving spin-off, the optional layer you reach for once your first loop runs.

You don’t have to read in order. The pick-your-path section at the end routes you by situation: new to loops, loop-that-forgets, loop-you-no-longer-read, or loop-that-improves-itself. The table below indexes the whole series by part; the building-block spine table that follows indexes it by primitive.

The series at a glance

Every part in one view. Scan the table to find your entry point, then drop into the phase sections below for the full gloss and a key insight per phase.

What are the building blocks of a loop?

A loop is not a new primitive to learn. It is five building blocks you already use, assembled around one piece most people skip. The decomposition is Addy Osmani’s, from his “Loop Engineering” synthesis, and it holds across tools. Name the five blocks once and loops stop being magic. The sixth piece, the memory spine, is the only reason the next run knows what the last run did.

This table is the spine of the guide. Use it as an index into the series:

Most “loops” in the wild are really one-shot scripts because they ship the five blocks and drop the spine. snarktank/ralph (14.3k stars) keeps its memory in git plus a progress.txt and a prd.json, and stops when every story reads passes: true. Small, greppable, on disk. That file is what makes the work cumulative instead of amnesiac.

Key insight: Nothing in the map is exotic. The skill is assembly: picking which blocks a given job needs and wiring them around one state file. Drop the spine and you have automation that forgets every morning.

Foundations: where does the series start?

Read Parts 1 to 3 first. Together they answer three questions in order: what is a loop, what is it made of, and what makes “done” mean something. These three are the conceptual core. Skip them and the Infrastructure posts read like disconnected tooling tips.

Loop Engineering: Why You Should Stop Prompting is the pillar. Prompting turn-by-turn is now the bottleneck, not the model. The post defines loop engineering, places it as the fourth era after prompt, context, and harness, and hands you a six-item readiness check that tells you whether your harness is ready to wrap in a loop. Read it first, even if you skim the rest.

Anatomy of a Loop: Five Building Blocks and One Spine is the parts list. It names the five blocks and the memory spine, maps each to a concrete Claude Code primitive, and walks you through a minimal lint-sweeper loop that actually runs: one scheduled prompt, one state file, one verifier check. Read it second to turn the concept into something you can build.

Stop Conditions: Making ‘Done’ Mean Something is the part most people get wrong. It shows how to make a loop’s “done” checkable by a different model than the one doing the work, climbs the four rungs of verifiability from “looks fine” to “a checker agent gated it on an exit code”, and caps every loop so it can’t run forever. Read it third.

Key insight: A loop without a verifiable stop condition is just a cron job that burns tokens. The stop condition is the line between a loop and a script. If “done” is whatever the maker model says, you haven’t built a loop, you’ve built an expensive way to trust one model’s self-report.

Infrastructure: what does a loop run on?

Once you know what a loop is, Parts 4 to 6 give it the three things it needs to survive contact with real work: persistence, parallelism, and a pulse. This is the phase where a clever demo becomes something you can leave running.

State File Pattern: Memory Outside the Context Window is the spine made concrete. It is a greppable markdown file with sections like tried, passed, open, and blocked, that lives on disk and survives between runs. The context window resets every session; the state file does not. Read this the first time your loop redoes work it already finished yesterday.

Git Worktrees for Agents: Parallel Loops Without Chaos is how you run more than one agent at once without collisions. Give each sub-agent its own worktree, split the maker from the checker so they can’t mark each other’s homework, and merge results back into one state file. Read this when one agent at a time is too slow and you want to fan out safely.

Scheduled Agent Automation: Give Your Loop a Heartbeat is the pulse. Run triage on cron, on a hook, or in CI, route findings to an inbox you actually read, and keep empty runs near-free so the loop costs almost nothing when there is nothing to do. The heartbeat is what makes a loop a loop instead of a thing you remember to run. Read this to take a manual ritual off your own calendar.

Key insight: The state file is the only reason the next run knows what the last run did. Persistence, not intelligence, is what separates a loop you can leave running from a script you have to babysit. Add the heartbeat and the worktrees on top of the spine, never instead of it.

Practice: what does production look like?

Parts 7 to 9 are the phase where loops meet reality. You have the concept and the infrastructure; now see a real retrofit with its honest scars, a reusable blueprint you can ship as a plugin, and the failure modes that decide whether you stay the engineer or become a rubber stamp.

Retrofit Automation Loop: Our Honest First Try is the field log. It walks through turning a manual triage ritual into a scheduled loop with a heartbeat, a state file, and a stop condition, and it doesn’t hide what broke on the way. Read this for the realistic version of the path the earlier tutorials describe cleanly.

AI Devkit Loop: From Fixkit to a Reusable Plugin is the blueprint. A devkit loop is a role harness with a heartbeat. The post walks the fixkit loop from bug intake to verified fix, then shows how to package the whole pattern as a Claude Code plugin so the next project starts with the harness and the definition of done already built - you still wire the schedule and connectors per repo. Read this when one good loop makes you want a reusable one.

AI Slop Prevention Is Loop Design, Not Luck is the finale, and the one to reread. The same loop produces clean output or a pile of slop depending on its design. The post names the real costs (comprehension debt and token burn), the three caps that bound the burn (iteration, cost, time), and the merge-seat review ritual that keeps a human in the path. Read this before you let any loop run unattended.

Key insight: The failure mode of a loop is not that it stops working. It is that it keeps working while you stop understanding what it ships. Comprehension debt compounds while the loop keeps working. The three caps in Part 9 bound the burn, but it’s the merge seat and its pre-flight review ritual that keep the loop accountable to a person who still reads the diff.

Get weekly Claude Code tips - One email per week. Practical loop and harness patterns, no fluff. Subscribe to AI Developer Weekly →

Appendix: the self-improving loop

The spin-off is the optional layer above the nine. Read it once your first loop runs and you want it to get better on its own, with you still in the approval seat.

Self-Improving Agent Loops: From Traces to a Harness PR shows a loop that reads its own traces, finds where it underperformed, and proposes a harness fix as a pull request you approve. The post walks one real hill-climbing pass from trace to diff. It doesn’t auto-merge anything. The loop suggests; you decide. Read this as the advanced move, not the starting point.

Key insight: A self-improving loop is the floor feeding itself one level up. The safety property is that it proposes a change and waits, it doesn’t rewrite its own harness silently. The human stays in the hill-climbing path by reviewing the PR, which is exactly the cap that keeps “self-improving” from meaning “unsupervised”.

Where should you start reading?

Four paths, based on where you are today. Each gets you to a concrete next action, not just more reading.

New to loops. Start with the pillar post for the definition and the readiness check, then Part 2 for the five blocks and a loop you can run. Come back here for the next deep-dive.

You have one loop and it forgets things. Go straight to the state file post, then add a heartbeat. Those two posts cover persistence and pulse, the two reasons most loops fail quietly.

Your loop produces output you no longer read. Skip to the failure-modes finale and add the three caps before your next run. Then read the stop-conditions post to make “done” mean something checkable.

You want the loop to improve itself. Read the self-improving spin-off, but only after a first loop is running. Hill-climbing needs a hill.

Try it now:

1. Pick the path above that matches where you are today
2. Open the first linked post and read its TL;DR
3. Copy one state file or kickoff template into your repo
4. Run one loop with a real, verifiable stop condition
5. Come back here and pick the next phase

FAQ

What is loop engineering?

Loop engineering is designing a recursive goal for a coding agent: a purpose plus a verifiable stop condition that the system iterates against until the condition holds, without a human prompting each turn. The plain version, credited to Matt Van Horn, is cron plus a decision-maker in the body. The model is commodity, the loop is the leverage.

What’s the difference between this guide and Part 1, the loop engineering pillar?

Part 1, Loop Engineering: Why You Should Stop Prompting, defines what loop engineering is, with the four-era history and a six-item readiness check. That is the pillar, the theory node. This guide is the reading path across the nine parts plus the self-improving spin-off, organized by phase. Read Part 1 for theory and this guide for navigation.

What are the building blocks of a loop?

Five blocks assembled around one memory spine: scheduled automation (the heartbeat), worktrees (isolation), skills, plugins and connectors, and sub-agents (the maker/checker split), wired around a single greppable state file that survives between runs. Drop the spine and you have automation that forgets every morning.

Where should I start if I have never built a loop?

Read Part 1 for the definition and the readiness check, then Part 2 for the five building blocks and a minimal lint-sweeper loop you can run, then Part 3 for stop conditions. Those three are the Foundations phase. Come back to this guide to pick your next deep-dive from the Infrastructure and Practice phases.

New parts get added to the matching phase section above as they ship. Bookmark this page if you want the running index for the series.

Ready to build your first loop? Pick one deep-dive above, wire one state file and one stop condition into your repo, and let it run once. The compound benefit starts on run #2. Start the Claude Code Mastery course →

What to Read Next

• Loop Engineering: Why You Should Stop Prompting - The pillar that defines the term and gives the six-item readiness check. Start here if you haven’t read it.
• Claude Code Harness Engineering: The Complete Guide - The harness reading path this guide is the sequel to. A loop wraps a harness, so build the harness first.
• Harness Engineering: The System Around AI Matters More Than AI - The harness pillar, the era directly below loops in the four-era arc.