Loop Engineering — The 14-Step Roadmap from Prompter to Loop Designer

Overview

Codez (@0xCodez) presents a comprehensive 14-step roadmap for transitioning from manually prompting AI coding agents to designing automated loops that prompt, verify, and iterate on their own. Sourced from Anthropic's engineering docs, Addy Osmani's long-form essay on loop engineering, and recent measurement studies, the article is structured in three tiers: understanding if you need a loop, learning the five building blocks, and building the smallest loop that works without hurting you. The article is refreshingly honest — acknowledging that most developers don't need loops yet and that the economics heavily favor teams with unmetered tokens and strong test suites.

1 Loop Engineering Is Replacing Yourself as the Prompter

For two years, working with a coding agent meant: write a prompt → share context → read output → write the next prompt. You held the tool the entire time. That era is ending.

Loop engineering is building a small system that:

• Finds the work — scans for failures, updates, issues
• Hands it to the agent — with the right context and instructions
• Checks the result — via tests, linters, type checks
• Records what happened — persistent state across runs
• Decides the next move — retry, escalate, or archive

You design this system once. The system prompts the agent from then on.

Addy Osmani breaks it into six parts. Anthropic engineers now merge 8× as much code per day as they did in 2024 — a figure Anthropic itself calls "almost certainly an overstatement of the true productivity gain." The number is debated. The mechanism isn't.

2 The 4-Condition Test — Before You Build Anything

Loops earn their cost under four conditions. Miss one and the loop costs more than it returns:

1. The task repeats — a loop amortizes setup across many runs. For one-time jobs, a good prompt is faster. If the work doesn't recur weekly, you don't have a loop — you have a script you ran once.
2. Verification is automated — the loop needs something that can fail the work without you in the room: a test suite, type checker, linter, or build. No automated check means you're back reading every diff.
3. Your token budget can absorb the waste — loops re-read context, retry, explore. That burns tokens whether or not the run ships anything. This is why it reads as "obvious" to people with free tokens and "reckless" to people on metered plans.
4. The agent has senior engineer tools — logs, a reproduction environment, the ability to run code and see what breaks. Without that, the loop iterates blind.

3 Who Wins, Who Loses — The Economics Are Not Universal

The economics favor whoever can spend. The people calling loop engineering "obvious" tend to have unmetered tokens.

4 The 30-Second Loop Check — Tactical Checklist

The 4-condition test is strategic. This is the tactical checklist you run on a specific task before turning it into a loop. Miss one box → keep it as a manual prompt:

1. The task happens at least weekly
2. A test, type check, build, or linter can reject bad output
3. The agent can run the code it changes
4. The loop has a hard stop (token budget, iteration count, or time limit)
5. A human reviews before merge, deploy, or dependency changes

5 Automations — The Heartbeat

Automations are what make a loop an actual loop. They fire on a schedule, on an event, or on a trigger condition. Everything else hangs off them.

Codex

The Automations tab — pick a project, set a prompt, set a cadence, choose local checkout or background worktree. Runs that find something land in a Triage inbox; runs that find nothing archive themselves.

Claude Code

Three primitives that compose into the same shape:

• /loop — session-scoped cadence, re-runs on schedule
• Desktop scheduled tasks — survive restarts
• Routines — cloud runs that work when laptop is off

Two critical primitives

• /loop — re-runs on a cadence regardless of state
• /goal — keeps going until a stated condition holds. A separate small model checks completion, so the agent that wrote the code isn't the one grading it

6 Worktrees — Parallel Without Chaos

The second you run more than one agent, files start colliding. A git worktree fixes it — a separate working directory on its own branch sharing the same repo history.

• Codex — worktree support built-in; several threads hit the same repo without bumping into each other
• Claude Code — --worktree flag to open a session in its own checkout; isolation: worktree on subagents for auto-cleanup

7 Skills — Write Project Knowledge Once

A Skill stops you from re-explaining the same project context every session. Both tools use the same format: a folder with a SKILL.md inside, holding instructions and metadata, plus optional scripts, references, and assets.

Why this matters for loops: a loop without skills re-derives your whole project context from zero every cycle. With skills, intent compounds. The conventions, build steps, "we don't do it like this because of that one incident" — written once, read by every run.

8 Connectors (MCP) — The Loop Touches Your Real Tools

A loop that can only see the filesystem is a tiny loop. Connectors, built on the Model Context Protocol (MCP), let the agent interact with your real environment:

Connectors that pay back fastest, in order:

1. GitHub — read repos, create branches, open PRs, comment on issues, react to webhooks. The single biggest day-one win.
2. Linear/Jira — update tickets, link PRs to issues, auto-close on verification pass
3. Slack — post triage results, ping on escalations, summarize overnight runs
4. Sentry/error tracker — investigate live alerts, draft fixes for high-frequency errors

9 Sub-Agents — Keep the Maker Away from the Checker

The most useful structural pattern: splitting the agent that writes from the agent that checks.

This is the evaluator-optimizer pattern from Anthropic's December 2024 engineering post. One model generates, another critiques, repeat.

Implementation in both tools

• Codex — custom agents as TOML files in .codex/agents/. Security reviewer on a strong model with high effort; explorer on a fast read-only model.
• Claude Code — subagents in .claude/agents/ and agent teams. Typical split: one explores, one implements, one verifies against spec.

Why it matters for loops: the loop runs while you are not watching, so a verifier you actually trust is the only reason you can walk away. Sub-agents burn more tokens — spend them where a second opinion is worth paying for.

10 The State File — The Agent Forgets, The File Does Not

This is the piece that sounds too dumb to matter and is actually the spine of every working loop. A markdown file, a Linear board, a JSON state — anything that persists outside the conversation.

Two patterns

• Markdown in the repo — STATE.md at the root or inside .claude/. Version-controlled, diff-readable. Best for solo/small team work.
• External system (Linear, GitHub Issues, database) — survives across repos, queryable, team-wide visibility. Best for production loops.

For long-running loops, pair the state file with a standing high-level spec — VISION.md or AGENTS.md — that the agent rereads each run. State tells the agent where it is. The spec tells it where to go.

11 The Minimum Viable Loop — Four Parts, No Swarm

If you passed the 4-condition test, build the smallest loop that works:

1. One automation — a scheduled run that fires on a cadence and stops on a clear condition. Use /loop or /goal.
2. One skill — a single SKILL.md that stores project context the agent would otherwise re-derive from zero.
3. One state file — records what's done and what's next. Tomorrow's run resumes instead of restarting.
4. One gate — the test, type check, or build that fails bad work automatically.

The metric that matters: cost per accepted change — not tokens spent, not tasks attempted. If your accepted-change rate is below 50%, the loop is losing.

12 The Ralph Wiggum Loop — Loops That Fail Quietly

Named by engineer Geoffrey Huntley: an agent meant to emit a completion token only when finished emits it early, and the loop exits on a half-done job. Without a hard gate, loops fail quietly and keep spending.

The Ralph Wiggum loop happens when:

• No real verifier — just a second agent asked to "review," no objective signal. Two optimists agreeing.
• Soft completion conditions — "done" defined by the agent's judgment, not by a test
• No hard stops — loop continues until rate limit or someone notices the bill

Other measured failure modes

• Goal drift — each summarization step is lossy; "don't do X" constraints disappear at turn 47. Fix: VISION.md reread each run.
• Self-preferential bias — the maker grades its own homework. Fix: separate verifier subagent.
• Agentic laziness — the loop declares "done enough." Fix: /goal with an objective stop condition checked by a fresh model.

13 Comprehension Debt & Cognitive Surrender

This failure mode gets sharper as the loop gets better, not worse. Two named risks from Osmani's essay:

Comprehension Debt

The faster the loop ships code you didn't write, the larger the distance between what the repository contains and what you understand. The bill that hurts is not the token bill. It's the day you debug a system no one on the team has read.

Cognitive Surrender

The pull to stop forming an opinion and accept whatever the loop returns. Designing the loop is the cure when done with judgment and the accelerant when done to avoid thinking. Same action, opposite result.

Mitigations (not technical)

• Read the diffs — if you don't read what the loop ships, you're renting comprehension debt at compound interest
• Spot-check the gate — pick random PRs and verify the test actually catches the failure mode you care about. Gates rot.
• Block architecture work — keep the loop on small, machine-checkable changes only
• Pair-design loops with a teammate — catches blind spots the loop will exploit forever

14 The Security Tax — Unattended Attack Surface

A loop running unattended is an attack surface running unattended:

• Generated code shipping unreviewed — without SAST, dependency audit, and secret scanning, insecure code merges automatically
• Skills as injection vectors — auto-installed skills inherit every prompt injection in their descriptions. Audit skill sources before installing. 520 of 17,022 audited skills leak credentials.
• Credentials in logs — debug logging scatters secrets across unmonitored logs. Disable verbose logging in production loops.
• Permission scope creep — read-only permissions get one write added "for convenience," then never re-audited. Re-audit every 30 days.

⚠ The Mistakes That Turn Loops into Money Pits

1. No 4-condition test — most developers fail at least one condition
2. No objective gate — a second agent "reviewing" is just a second optimist
3. Same agent writing and verifying — self-preferential bias, always "A+"
4. No state file — tomorrow's run restarts from zero
5. Vague stop conditions — "done when it looks good" never holds
6. No token budget cap — ambitious loops burn 5–10× expected tokens
7. Consumer plan + heavy verification — token bill or rate limit gets you
8. Auto-installing community skills — 520 of 17,022 leak credentials
9. Loops on judgment-call work — keep it on lint-and-fix, not strategy
10. Not reading the diffs — comprehension debt at compound interest

🎯 Key Takeaways

🔗 Resources & Links

• Original X Article by Codez (@0xCodez) — the full 14-step roadmap post
• Codez on LinkedIn — author's LinkedIn profile