What Is Loop Engineering?
Loop engineering is the practice of designing the repeatable control system around an AI agent: goal, context, tool access, observation, verification, retry policy, and stop rules. In coding work, that system should read repository evidence such as test output, compiler errors, diffs, logs, screenshots, or review comments before deciding the next step.
The reason it matters for software teams is simple: a coding agent can sound confident while still looping on the wrong file, rerunning the same failing command, or expanding scope without proof. A loop-engineered workflow makes the agent show evidence, change strategy after failure, and stop before cost, risk, or permissions drift out of bounds.
What Is Addy Osmani's Loop Engineering Approach?
The useful reading of Osmani's idea is that engineers should stop babysitting every agent turn and start designing the operating loop around the agent. The prompt still matters, but it is only one part of a system that also includes tools, feedback, memory, cost limits, and termination.
In a coding workflow, that means the loop must know what done looks like before the first edit happens. A good loop names the repository task, the allowed files or tools, the command that proves progress, the maximum attempts, and the human checkpoint for risky actions.
How Does Loop Engineering Work for AI Coding Agents?
Start with a plan, then let the agent act on the smallest useful change. The observe step reads evidence from the repository rather than trusting a fluent status update: failing tests, compiler output, diffs, logs, screenshots, or MCP tool responses. Verification turns that observation into a verdict. Retry only when the next attempt changes the strategy; otherwise stop and hand the evidence to a human.
This is why loop engineering is especially useful for AI coding agents. Software work already has observable signals: tests pass or fail, builds complete or fail, files changed or did not, and pull requests can be reviewed. The loop should attach to those signals instead of treating agent confidence as evidence.
Loop Engineering vs Prompt Engineering
Prompt engineering optimizes a single instruction or conversation. Loop engineering designs the repeated system around that instruction: context loading, tool access, action, observation, verification, retries, and stop conditions. A strong prompt can still fail inside a weak loop if the agent cannot see test output or has no rule for when to stop.
Loop engineering is also different from a cron job. A cron job runs a fixed command on a schedule. A coding-agent loop observes current state and decides the next action before it continues. If nothing inside the run observes evidence and changes strategy, it is scheduling, not loop engineering.
Where loops live in today's tools
Claude Code supports recurring work through /loop scheduling, hooks that fire at lifecycle points, subagents for split explore-implement-verify roles, and headless or CI-style runs that persist after a laptop closes. Cursor supports long-running cloud agents, parallel agents on isolated branches, and Automations triggered by GitHub, Slack, Linear, or schedules. Codex and similar agents implement loops through tool calls, subagents, and repository instructions that name verification commands.
The surface differs by vendor, but the architecture repeats: goal, context, tools, observation, adjustment, termination. Pick the tool by where your team already works, then design the loop around observable repo evidence rather than model charisma.
A Practical Loop Engineering Example
Suppose a dependency upgrade breaks frontend tests. A weak instruction says: fix the tests. A loop-engineered instruction says: inspect the failing output first, edit only the affected test or component files, run the focused test command, then run the wider project check if the focused command passes. Retry once with a different hypothesis, but stop after the same failure repeats twice.
That example matters because the loop is not trying to be autonomous in every direction. It is narrow, observable, and cheap to review. The agent can keep working through routine failure, but it must stop before rewriting unrelated files, touching production configuration, or burning more attempts on the same root cause.
When Should an AI Agent Stop the Loop?
Stop rules are not administrative decoration; they are the safety feature. Stop when verification passes, when an iteration cap is reached, when the same failure repeats, when the next action requires wider permissions, when cost crosses the budget, or when the agent can no longer tie its next action to observed evidence.
For team use, make the stop rule visible in AGENTS.md, CLAUDE.md, a Copilot instructions file, or the workflow configuration that starts the loop. The safest loops are boring to audit: every retry has a reason, every escalation has an owner, and every successful run leaves a concise artifact.
What counts as proof that an AI coding loop is done?
Treat DONE, tested, reviewed, and ready-to-merge as claims until current evidence supports the transition. Bind every test result, build receipt, diff review, or screenshot to the exact source revision it checked; reject stale receipts after the code changes; and record whether the run ended verified, review-required, blocked, or stopped by budget.
A July 2026 Proof-or-Stop preprint formalizes this as evidence-gated lifecycle control: fresh, source-state-bound, mechanically verifiable evidence must satisfy a gate before state can advance. The paper is a preprint with an evaluation limited to one model family, 24 ablation tasks, and a self-hosted corpus. Its operational proof means evidence admissible under a stated trust model, not a guarantee of semantic program correctness. The downloadable KyenAI contract below is an independent starter template, not the paper's reference implementation.
AI coding agent workflow checklist
Before scaling Automations, /loop schedules, or cloud agents, confirm the workflow has a named owner, a bounded goal, a verification command, a retry cap, a human checkpoint for risky actions, and a log that avoids secrets.
The checklist should answer five questions: what done looks like, what evidence the loop reads, what tools it may call, when it must stop, and who approves escalation. If any answer is missing, the workflow is still a prompt, not loop engineering.
Pilot on one repository task first. Record review time, token use, and human interventions actually observed. Add parallel agents or schedules only after a single-threaded loop is trustworthy.
Common Patterns and When to Use Them
Plan-execute-verify fits bounded repo tasks with a clear pass command. Retry-with-cap helps flaky setup steps but needs a hard attempt limit per item. Evaluator-optimizer pairs work well for reviews and docs when criteria are explicit. Explore-narrow prevents premature edits in unfamiliar code. Scheduled wake-up loops handle recurring triage. Human-in-the-loop checkpoints belong before production, permission widening, or destructive operations.
Anthropic's agent guidance recommends adding complexity only when simpler flows fail. Start with one loop on one repository task, measure review effort and token use, then add subagents or schedules only when the simpler loop stalls.
Recommended play
- Start with one real repository task and a single plan-execute-verify loop before adding schedules or parallel agents.
- Write the done signal as a command or artifact, not a vibe: passing tests, green build, opened PR, or filed ticket.
- Cap iterations per item and escalate when the same failure repeats twice with the same root cause.
- Separate exploration from implementation so read-only passes cannot mutate production paths.
- Budget tokens and concurrency before running unattended cloud or scheduled loops.
When to prompt vs when to loop
Use this table to decide whether a task needs a durable loop or a single supervised agent session.
| Area | Prompt once when | Design a loop when | Stop rule to add |
|---|---|---|---|
| Task shape | The steps are predictable and fit one focused session | The agent must read errors, revise, and re-run verification | Name the verification command and maximum iterations |
| Duration | You can stay at the keyboard for the whole task | Work should continue while you review other items or close the laptop | Set a schedule or queue with a summary artifact per run |
| Risk | Changes are reversible and confined to a local branch | The loop touches shared files, CI, production config, or permissions | Require a human checkpoint before merge or deploy |
| Cost | Token use is small and visible in one sitting | Retries, parallel agents, or long horizons can compound quickly | Set per-run and per-day budgets with automatic stop |
| Team workflow | One engineer needs a quick answer or small patch | A team wants repeatable triage, review, or hygiene across repos | Publish run logs without secrets and name an owner for loop drift |
Execution steps
Name the goal and done signal
Write what finished means in observable terms: command output, PR state, ticket link, or report section. Avoid fuzzy goals like 'make it better' that let the loop run without a verdict.
Choose the first pattern
Default to plan-execute-verify for code changes. Add evaluator-optimizer only when review criteria are explicit. Reserve scheduled wake-up loops for recurring triage after the single-task loop works once.
Wire observation before speed
Give the agent tests, linters, build commands, diff review, or MCP tools that return ground truth. A loop without observation is just expensive repetition.
Set termination and escalation
Cap attempts per file or task, stop when the same error repeats, and name who approves production or permission changes. Document what the loop should do when blocked.
Write the loop into repository instructions
Record the verification command, retry cap, forbidden paths, and human checkpoint in AGENTS.md, CLAUDE.md, Copilot instructions, or the workflow file that launches the loop.
Pilot, measure, then parallelize
Run the loop on one repo task, record review time, token use, and human interventions actually observed. Add parallel agents or cloud handoff only when single-threaded loops are trustworthy.
Common pitfalls
Fuzzy goals with no done signal
Translate goals into a verification command, required artifact, or explicit human acceptance step before the first unattended run.
Unbounded retries on the same mistake
Cap iterations per item and change strategy after repeated failures instead of paying for identical attempts.
Cron without an agent decision-maker
Ensure each run observes current state and chooses the next action; a fixed script on a timer is scheduling, not loop engineering.
Parallel agents on shared files
Isolate branches or assign disjoint ownership; merge results deliberately instead of letting agents overwrite each other.
Implementation checklist
- Write the goal and done signal in observable terms.
- Pick plan-execute-verify as the default loop pattern.
- Attach tests, linters, or builds as loop observation.
- Cap iterations and name escalation for repeated failures.
- Add human checkpoints before production or destructive actions.
- Budget tokens and parallel agents before unattended runs.
- Log outcomes without secrets and assign a loop owner.
Questions this guide answers
What is loop engineering for AI coding agents?
Loop engineering means designing the operating loop around the agent instead of writing one better prompt. For coding agents, the practical loop is Plan → Act → Observe → Verify → Stop: give the agent a bounded goal, inspect tests or diffs, retry only with a changed strategy, and stop on token caps, repeated failure, or a required human checkpoint.
When should an AI coding agent stop the loop?
Stop when verification passes, when an iteration cap is reached, when the same failure repeats, when the next action needs wider permissions, when cost crosses the budget, or when the agent can no longer tie its next action to observed evidence. Document stop rules in AGENTS.md, CLAUDE.md, Copilot instructions, or the workflow file that launches the loop.
How is loop engineering different from prompt engineering?
Prompt engineering improves a single instruction. Loop engineering designs the repeated system around that instruction: context loading, tool access, action, observation, verification, retry limits, and stop conditions. A strong prompt can still fail inside a weak loop if the agent cannot read test output or does not know when to stop.
What belongs on an AI coding agent workflow checklist?
Name the goal and done signal, pick plan-execute-verify as the default pattern, attach tests or linters as observation, cap iterations, add human checkpoints before production or destructive actions, budget tokens before unattended runs, and assign a loop owner who reviews logs without secrets.
What counts as proof that an AI coding agent loop is done?
An agent's DONE message is a claim, not proof. Require fresh evidence tied to the exact source revision: passing commands, required artifacts, an independently checked diff, and any named human approval. Record an explicit terminal state such as verified, review-required, blocked, or stopped-by-budget. A passed gate proves the named check under its trust model, not semantic correctness of the whole program.