Loop Engineering Handbook

Loop Engineering Handbook banner

License: MIT CI Docs: online 8 chapters 17 loops in the library 7 worked examples

Loop engineering is the practice of running an AI coding agent in a governed, verifiable loop until a clearly defined goal is met.

Learn loop engineering → · Copy a loop → · See one run →

The only loop-engineering repo where you can see the logs, the cost, and the output of every example — including work that isn't code.

This handbook eats its own dog food. It was assembled by a governed loop running in Claude Code — the guide, the prompt library, and all seven worked examples were produced and verified loop-by-loop, under the same loop-contract discipline (Done-when, Evidence, If-blocked) the handbook teaches. Loop engineering isn't a thing we describe here; it's the thing that made the repo.

Loop in 30 seconds

A loop contract is six fields. Fill them in and you have a governed loop:

Goal:        <the outcome, in one sentence>
Context:     <repo / inputs / the source of truth the agent may use>
Constraints: <read-only? sandbox/worktree? cost cap? rate?>
Done-when:   <the single verifiable stop condition a separate checker can test>
Evidence:    <the artifacts that prove Done-when is met (logs, repro, ledger, .xlsx)>
If-blocked:  <halt rule + escalation: max no-progress passes, wall-clock cap, who to ask>

Then run one. In the overnight code review, the ungoverned loop burned $217.34 re-reviewing an unchanged PR queue overnight; the governed one — same job, a Done-when and a cost cap — finished in $11.20. (Illustrative — as of June 2026, verify before relying; the receipts are in the example.)

See the canonical template, with each field explained, in the loop contract.

What this repo is

Three ways to learn loop engineering, in priority order:

  1. A guide you learn from — docs/: what it is, /goal vs /loop, benefits, risks + cost, recommendations.
  2. A copy-paste prompt library — library/: one card per loop, plus a machine-readable catalog.json and llms.txt.
  3. Seven worked examples — examples/: loops actually running, with the receipts (iteration logs, cost ledgers, before/after, charts, real .xlsx output).

About this repo

Star history

Star-history chart appears here after launch — set the owner in repo.config.json, then this section links https://star-history.com/#OWNER/loop-engineering-handbook.

Credits

Loop engineering as a discipline grew from a lineage of practitioners:

Geoffrey Huntley — the original Ralph loop Steinberger — long unattended agent loops Boris Cherny — loops in Claude Code Addy Osmani — defining loop engineering Greg Brockman — the governed Ralph loop++

Each card links to its original post. Full attributions: SOURCES.md.

Everything here is synthetic and safe — fictional orgs, toy repos, made-up datasets. Every example carries a "reconstruction for teaching" label. Volatile facts are marked as of June 2026 — verify before relying.