Loop Engineering
The discipline of designing, bounding, and instrumenting the iterative reasoning cycles that AI coding agents run. The agent-era counterpart to prompt engineering — and the thing that decides whether your run finishes for $2.30 or burns $65 overnight.
Why loop engineering exists
Modern coding agents — Claude Code, OpenAI Codex, Gemini agents, Devin, OpenHands — don't produce a single response. They run an iterative observe → plan → act → verify cycle, often hundreds of times per task. The cycle is called an agent loop. The failure mode where it gets stuck retrying the same broken edit is called a Ralph loop.
Prompt engineering optimizes one call. Loop engineering optimizes the runtime that wraps all of them.
The five primitives
- Budget cap. Hard ceiling in dollars and tokens, enforced at the orchestrator, not the prompt. MartinLoop's
--budgetflag kills the loop cleanly at the cap. - Stop rule. Deterministic exit — no-progress detection, max iterations, time-boxed run. The loop has to be killable from outside the agent's reasoning.
- Verifier gate. The agent cannot declare success until an external check passes. Typically
--verify "pnpm test"or a custom invariant. Closes the hallucinated-completion failure class. - Rollback path. Partial work never lands on
main. Branch isolation by default; merge only after verify is green. - Inspectable receipt. JSONL run record of every step, model call, tool invocation, and failure class. The thing your security team and CFO will actually ask for.
The 13-class failure taxonomy
Every loop-engineered run that fails is tagged by class. This is the countermeasure design surface — you can't fix what you can't name.
- logic_error
- hallucination
- syntax_error
- type_error
- test_regression
- scope_creep
- no_progress
- repo_grounding_failure
- verification_failure
- environment_mismatch
- budget_pressure
- safety_leash_blocked
- sandbox_write_blocked
Full field guide: The 13 failure modes of autonomous agents.
Loop patterns in the wild
- ReAct
- Observe, reason, act — repeat. The default loop most coding agents implement.
- Plan-and-execute
- Decompose into steps first, then run the steps. Lower cost per step, higher cost on bad plans.
- Ralph loop
- Single tight retry cycle without bounds. Highest failure rate; the canonical example of why loop engineering matters.
- Reflexion loop
- Self-critique then retry. Improves quality but multiplies cost — useless without a budget cap.
- Governed loop
- Any of the above wrapped with the five primitives. The only pattern safe to run on a real codebase.
Frequently asked questions
What is loop engineering?
Loop engineering is the discipline of designing, bounding, and instrumenting the iterative reasoning cycles that AI coding agents run. It is the agent-era counterpart to prompt engineering: instead of optimizing a single response, loop engineering optimizes the structure of the observe–plan–act–verify cycle so the agent terminates, stays on-budget, and produces auditable evidence of completion.
How is loop engineering different from prompt engineering?
Prompt engineering optimizes the input to a single LLM call. Loop engineering optimizes the runtime that wraps hundreds of those calls — budget caps, stop rules, verifier gates, retry policy, rollback evidence, and the JSONL run record. Prompt engineering makes one call better; loop engineering makes the whole run safe to ship.
What are the core primitives of loop engineering?
Five primitives: (1) a hard budget cap in dollars and tokens, (2) a stop rule that fires deterministically, (3) a verifier gate (typically `--verify "pnpm test"` or equivalent) that must pass before the loop can claim success, (4) a rollback path so partial work never lands on main, and (5) an inspectable receipt — a JSONL run record tagging every step and any failures by class.
What are the common agent loop patterns?
ReAct (observe, reason, act), plan-and-execute (decompose then run), Ralph loops (single tight retry cycle — high failure rate without bounds), reflexion loops (self-critique then retry), and governed loops (any of the above wrapped with budget, stop, and verify primitives).
What is the 13-class failure taxonomy?
MartinLoop classifies every failed agent run into one of 13 classes: logic_error, hallucination, syntax_error, type_error, test_regression, scope_creep, no_progress, repo_grounding_failure, verification_failure, environment_mismatch, budget_pressure, safety_leash_blocked, sandbox_write_blocked. Loop engineering uses this taxonomy to design specific countermeasures per failure class.
Why does loop engineering matter in production?
An unbounded coding agent can spend $65 overnight on a single flaky-CI-gate task while never reaching a verified green state. A loop-engineered run of the same task finishes for $2.30 with an auditable receipt. Loop engineering is what turns autonomous agents from a demo into infrastructure you can put on real codebases.
What tools support loop engineering?
MartinLoop (Apache 2.0, `npx -y martin-loop@latest start`) is the open-source runtime built specifically for loop engineering — provider-agnostic across Claude Code, OpenAI Codex, Gemini agents, and custom LangGraph or AutoGen loops. It enforces budget, verify, and policy at the orchestrator level rather than the prompt level.
Related reading
Try it on your next agent run
MartinLoop ships every loop-engineering primitive as a CLI flag. Apache 2.0.
npx -y martin-loop@latest start