Loop Engineering is becoming one of those terms that spreads faster than its definition.
That usually creates two bad outcomes. Some people dismiss it as another AI buzzword. Others treat it as magic: prepend /loop to a prompt and expect an agent to ship production-ready work while they sleep.
Both readings are wrong.
The practical definition is simpler:
Loop Engineering is the practice of designing AI agent work as a repeatable cycle with a clear goal, bounded action, verification, state persistence, and stop rules.
In other words, it is not a prompt trick. It is an engineering discipline for long-running AI work.
The Problem: You Are Still the Loop
Most developers use coding agents like this:
- Write a prompt.
- Let the agent edit code.
- Run tests manually.
- Paste the failure back.
- Ask the agent to try again.
- Repeat until it works or you give up.
It looks like the AI is doing the work. In reality, you are still the scheduler, QA engineer, state manager, and stop-condition checker.
The agent executes single instructions. You decide whether the result is correct, whether the next step should happen, which error matters, what changed, and when the task is done.
Loop Engineering moves those responsibilities out of your head and into an explicit workflow.
A good loop answers these questions before the agent starts:
- What does done mean?
- What is the allowed scope?
- What should happen in each iteration?
- How will the result be verified?
- Where is progress recorded?
- When should the agent stop?
- Which actions require human approval?
That is the shift. Prompt Engineering tries to improve one response. Loop Engineering tries to make multiple responses converge toward a verifiable result.
The Vocabulary That Matters
Before talking about /goal and /loop, it helps to separate several related concepts.
Prompt Engineering
Prompt Engineering is writing a good single instruction.
Example:
Fix the failing tests in the auth module and explain what changed.
This can work for a small task. But it does not define the scope, verification method, failure policy, or stop condition.
For one-shot requests, that may be fine. For multi-step coding work, it is fragile.
Context Engineering
Context Engineering is deciding what the model sees at each step: instructions, files, tool outputs, memory, logs, retrieval results, MCP data, and previous state.
Long-running agents produce new context every turn. If you simply keep adding more history, the model gets more noise, not more clarity.
Good context engineering keeps high-signal information and externalizes state into files the agent can reread.
Harness Engineering
The harness is the environment the agent runs inside.
For coding agents, that usually means:
- Project instructions:
CLAUDE.md,AGENTS.md, or similar files - Permission rules: what the agent can run automatically and what requires approval
- Tooling: MCP servers, browser access, GitHub, databases, design tools
- Hooks: format after edit, lint before commit, log tool calls
- Subagents: separate contexts for review, research, and verification
- Memory: durable project decisions and recurring preferences
The loop runs on top of the harness. Without a harness, the agent has to guess your project structure, commands, conventions, and boundaries every time.
Guessing is where many agent failures begin.
Loop Engineering
At its smallest, a loop looks like this:
Read goal -> act -> verify -> write state -> continue or stop
This is not the same as a traditional script.
A script repeats fixed steps. A looped agent evaluates state, chooses the next action, handles errors, and updates the plan.
That flexibility is useful. It is also dangerous if you do not define boundaries.
Verifier
The verifier is the evidence layer.
It should not ask, "Do you think this is done?" It should check evidence:
- Did the tests pass?
- Did the build pass?
- Did the diff stay inside the allowed scope?
- Do the links open?
- Does the screenshot match the target state?
- Does the implementation satisfy the written acceptance criteria?
The best verifier is often separated from the worker. If the same agent writes the code and judges the result in the same context, it can rationalize its own mistakes.
Memory and State
Memory and state are related, but they are not the same.
Memory is long-term project knowledge:
- team preferences
- architectural decisions
- recurring constraints
- things the agent should remember across sessions
State is current task progress:
- what has been done
- what failed
- what is blocked
- what the next iteration should read first
A useful minimal setup is:
AGENTS.md or CLAUDE.md # long-term project rules
LOOP-STATE.md # current loop progress
IMPLEMENTATION_PLAN.md # current plan and checklist
logs/ # iteration logs
Without state, a loop often becomes a repetition machine. It looks busy but keeps rediscovering the same facts.
Stop Rules
Stop rules are the brakes.
Every loop needs at least two kinds:
- Success stop: what evidence proves the task is complete
- Failure stop: when the agent should stop trying and return control to a human
Example:
Success:
- pnpm test auth passes
- auth coverage stays above 80%
- git diff only touches lib/auth and tests/auth
Failure:
- the same test fails 3 times without a new hypothesis
- database migrations need to be modified
- a new production dependency is required
- 8 iterations pass without meeting the goal
An agent loop without stop rules is not automation. It is a cost risk.
/goal vs /loop
In Claude Code, /goal and /loop represent two different loop shapes.
According to the Claude Code documentation, /goal sets a completion condition. Claude keeps working and checks after each turn whether the goal has been reached.
/loop runs a prompt repeatedly at an interval inside the current Claude Code session. It is better for polling, monitoring, reminders, or waiting for external state changes.
The short version:
| Command | Core question | Stop condition | Best for |
|---|---|---|---|
/goal |
What state counts as done? | Goal reached or failure rule triggered | migrations, failing tests, docs, issue cleanup |
/loop |
How often should this be checked? | external event, human stop, explicit rule | deployment checks, PR monitoring, scheduled review |
There is an important portability detail.
The engineering pattern transfers across tools. The command names do not.
Claude Code has /goal and /loop in its documentation. Codex emphasizes AGENTS.md, Automations, Subagents, Workflows, and CLI workflows. Do not assume every agent tool exposes the same slash commands.
Write portable loop specifications, then map them to the tool you are using.
When to Use /goal
Use /goal when the task has a verifiable endpoint.
Bad:
/goal make the project better
Good:
/goal auth migration is complete:
Done when:
- all new password writes use argon2id
- legacy bcrypt hashes are rehashed after the next successful login
- pnpm test auth passes
- tests cover migration, failed login, and legacy hash compatibility
Scope:
- only edit lib/auth, tests/auth, docs/auth-migration.md
- do not edit merged db/migrations
- do not change the session cookie format
Verification:
- run pnpm test auth after each change
- inspect git diff for out-of-scope files
- if tests fail, diagnose before editing again
Stop:
- stop when all done conditions pass
- stop if the same failure repeats 3 times
- stop before adding production dependencies
- stop after 8 iterations
State:
- maintain LOOP-STATE.md
- update done, blocked, and next-step items after every iteration
The point is not verbosity. The point is verifiability.
If your goal cannot be checked by tests, builds, diffs, file content, screenshots, link checks, metrics, or clear human acceptance criteria, it is not ready for a loop.
When to Use /loop
Use /loop when the main job is to check something repeatedly.
Example:
/loop 5m check whether production deployment is complete:
Each iteration:
- inspect the latest GitHub Actions workflow for this branch
- if it is still running, record the current job and elapsed time
- if it succeeded, check whether the production homepage returns 200
- if production is healthy, report success and stop
- if the workflow failed, summarize the failed log and stop
Stop:
- deployment succeeds and health check passes
- workflow fails
- 12 iterations pass without completion
Typical /loop tasks:
- check deployment status every 5 minutes
- monitor whether a PR has new review comments
- generate a daily project status summary
- watch whether an external service has recovered
- periodically process failed jobs or logs
Bad /loop tasks:
- one-shot questions
- vague ideation
- high-risk production changes
- product direction decisions without human context
- "keep improving this" with no stop condition
"Keep improving this" is one of the most dangerous instructions you can give to an autonomous agent. It has no endpoint, no boundary, and no cost ceiling.
A Reusable Loop Spec Template
For serious work, put the loop spec in a file such as PROMPT.md, LOOP-SPEC.md, or IMPLEMENTATION_PLAN.md.
# Goal
Describe the final state in one or two sentences.
Do not write "improve this." Write what evidence must be true.
## Work Scope
- Readable directories:
- Editable directories:
- Forbidden directories:
- Actions requiring human approval:
## Work Method
- Process one subtask per iteration
- Read the existing implementation before editing
- Prefer existing project patterns
- Do not add dependencies unless you stop and explain why
## Verification
- Commands to run each iteration:
- Files to inspect:
- Evidence to preserve:
- Retry policy when verification fails:
## State
- Read LOOP-STATE.md at the start of each iteration
- Update LOOP-STATE.md at the end of each iteration
- Allowed states: todo, doing, done, blocked, needs-human
## Stop Rules
- Success stop:
- Failure stop:
- Max iterations:
- Max budget:
- Conditions requiring human intervention:
## Report
At the end, report:
- what was completed
- verification evidence
- blockers
- files changed
- recommended next step
This template tells the agent how to work, not just what to do.
The Codex Equivalent
If you are using Codex, I would map the same pattern into three layers.
First, use AGENTS.md for repository-level instructions. OpenAI's Codex documentation describes AGENTS.md as the place for project guidance, test commands, coding standards, and constraints.
Minimal example:
# Repository Instructions
## Commands
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint
## Rules
- Prefer existing helpers under src/lib.
- Do not add production dependencies without asking first.
- Run pnpm test after changing TypeScript files.
- Keep changes scoped to the user request.
## Verification
Before finishing, report:
- Files changed
- Commands run
- Tests passed or why they could not run
Second, use Codex Automations for scheduled or recurring checks.
Third, use Subagents and Workflows when research, verification, log analysis, or review should happen in separate contexts.
The warning is the same as with Claude Code: parallel agents are not free. They consume more tokens and introduce coordination overhead. Use them when they reduce context pollution or improve verification quality.
What Loop Engineering Actually Solves
It reduces human QA relay work
You still review the final result. But you stop acting as the manual bridge between test output and the next agent instruction.
It makes long tasks recoverable
A clear LOOP-STATE.md lets an agent resume from the previous iteration instead of relying on a giant chat transcript.
It replaces confidence with evidence
Agents are often confident. Evidence is better.
Looped work should end with test logs, build output, diffs, screenshots, link checks, benchmark results, or explicit acceptance criteria.
It turns repeated work into team assets
The first loop spec is slow to write. The second is faster. By the third time, it probably belongs in a reusable workflow, skill, automation, or project template.
That is the difference between a prompt and an engineering practice.
Three Practical Scenarios
1. Research briefs without fake citations
A common failure mode: ask an AI to write a research brief, and it returns polished claims with references that are dead links or do not support the claim.
The loop version should require verification:
/goal research brief is complete:
Done when:
- every major claim has at least 2 accessible sources
- each source supports the specific claim it is attached to
- invalid sources are removed or replaced
- final Markdown includes a references section
Verification:
- open each link
- summarize what claim each source supports
- mark mismatched sources as invalid and replace them
Failure stop:
- no authoritative source found after 3 distinct search attempts
- required evidence is behind a paywall
- 6 iterations reached
The loop is not about writing faster. It is about not publishing unsupported claims.
2. Fixing a frontend persistence bug
Suppose a settings page says "saved," but after refresh the settings disappear.
Good loop:
/goal settings persistence bug is fixed:
Done when:
- the save-refresh-loss bug is reproduced
- root cause is identified and fixed
- a regression test covers save and reload
- npm test settings passes
- if a dev server is available, manual refresh confirms persistence
Scope:
- inspect app/settings, lib/settings, tests/settings first
- do not modify auth, billing, or database migrations
Stop:
- stop if the API contract must change
- stop if a data migration is required
- stop if the same test fails 3 times without progress
This works well because the task has natural stages: reproduce, diagnose, fix, test, verify.
3. Building a 0-to-1 product
Andrew Ng's framing of three product loops is useful:
- Agentic coding loop: the agent builds, tests, and fixes against a spec
- Developer feedback loop: the developer reviews product direction and updates the spec
- External feedback loop: real users, alpha testers, or A/B tests change the product vision
These loops run at different speeds.
The coding loop may run every few minutes. The developer feedback loop may run every few hours. External feedback may take days or weeks.
Do not try to automate all three equally.
My practical judgment: the first loop can be heavily automated. The second still needs human product context. The third must not be faked. User feedback cannot be replaced by a model's guess about what users might want.
The point is not to remove the human entirely. It is to move the human out of repetitive low-level relay work and back into judgment, direction, and acceptance.
Common Failure Modes
1. The goal is a wish
Bad:
/goal make the app better
Better:
/goal homepage performance pass is complete:
- Lighthouse Performance >= 90
- LCP < 2.5s
- existing analytics remain intact
- npm run build passes
- before and after metrics are reported
Agents need endpoints, not vibes.
2. The verifier is weak
"Check if there are any issues" is not verification.
Good verification:
- runs a specific command
- reads a specific output
- compares against a written condition
- reports pass or fail with evidence
- does not silently fix failures while pretending the check passed
3. There is no state file
Without state, loops repeat themselves:
- already-fixed tests get fixed again
- rejected hypotheses get rediscovered
- forbidden files get reopened
- previous failure reasons disappear
Keep state short and structured:
# LOOP-STATE
## Current Status
- status: doing
- current_step: add regression test for password migration
- last_verified: pnpm test auth failed on legacy hash path
## Done
- confirmed current hash implementation
- added migration helper draft
## Blocked
- none
## Next
- fix legacy bcrypt verification test
- rerun pnpm test auth
4. Permissions are too broad
The more autonomous the loop, the narrower the permissions should be.
Limit destructive commands, force pushes, database migrations, production deployment, customer data writes, outbound messages, purchases, and anything that cannot be safely undone.
5. Context keeps growing
More context is not always better. In long-running loops, it often becomes rot.
Prefer:
- file paths as indexes
- reading files only when needed
- summarizing large logs
- writing state to disk
- compacting long sessions
- separating verification into a fresh context
6. /loop is used where /goal belongs
If you know the endpoint, use a goal. If you only know the checking rhythm, use a loop.
Bad:
/loop 10m keep refactoring until it is better
Better:
/goal user-service split is complete:
- user-service.ts split into no more than 4 modules
- each module below 300 lines
- public API unchanged
- pnpm test user passes
- max 6 iterations
7. Human context is automated too early
Product taste, business tradeoffs, customer insight, and brand judgment can be AI-assisted. They should not be silently delegated when the model lacks the context you have.
Loop Engineering is strongest for execution and verification. Direction still needs context.
My Rule of Thumb
Before I put a task into a loop, I ask five questions:
- Can the result be verified?
- Can the scope be narrowed?
- Can failures be recovered or escalated?
- Are human-approval actions explicit?
- Can progress be written to a state file?
If I cannot answer at least four of those clearly, I do not start a loop.
"Design a better business model" is not ready for a loop. I would first use normal conversation to clarify constraints and options.
"Classify 20 pieces of user feedback, output the top 5 issues, preserve the original quote for each, and assign a priority" is ready. It has inputs, outputs, evidence, and a completion condition.
Final Checklist
Before writing a loop, check this:
Goal:
- Is there a clear final state?
- Can it be verified by tests, builds, diffs, links, screenshots, metrics, or acceptance criteria?
Scope:
- What can be read?
- What can be edited?
- What is forbidden?
- Are new dependencies allowed?
Execution:
- Is each iteration small?
- Should existing project patterns be reused?
- Is state written after each iteration?
Verification:
- What command or check proves progress?
- What happens on verification failure?
- Is the verifier separated from the worker when needed?
Stop:
- What is the success stop?
- What is the failure stop?
- What is the max iteration or budget?
Permissions:
- Are destructive, production, and sensitive-data actions restricted?
- Are high-risk actions routed back to a human?
If you cannot fill this out, do not start the loop yet.
Conclusion
Loop Engineering is not about making AI "run by itself."
It is about making AI run inside boundaries.
The real shift is:
- from writing prompts to writing completion conditions
- from pasting errors to designing verification layers
- from trusting confidence to requiring evidence
- from accumulating chat history to externalizing state
- from one-off interactions to reusable workflows
/goal is for tasks with endpoints. /loop is for repeated checks. Harness provides the floor. Verifier provides evidence. Memory and state provide continuity. Stop rules provide the brakes.
The stronger the model gets, the more discipline it needs.
A weak model cannot get very far. A strong model can get very far in the wrong direction.
Top comments (0)