What to look at: seven milestones in a row. Each section below is a milestone. You don't have to guess anything — just follow the path from left to right, and at the end you'll have a loop running.
🎯 Choose a task with a clear answer
The first step determines the success of all the others: pick a task whose "ready" can be checked by something beyond your opinion. The tests pass, the format matches, the script runs without errors. If only you can tell whether it’s good, the loop can’t know it’s finished.
✓ Correct answer (good 1st loop)
- ✓“Make the failing test pass.”
- ✓“Convert this CSV to JSON in format X.”
- ✓“Make the script run without throwing an error.”
✗ Opinion-based answer (avoid for now)
- ✗“Make the site look better.”
- ✗“Improve the architecture.”
- ✗“Write an engaging piece of text.”
🧭 Anthropic's advice, read carefully
Anthropic recommends the loop for open tasks, where you can’t predict the steps in advance. True—but in your first loop, narrow the scope to something that has a built-in checker. Open during execution, closed during verification: the agent figures out the path, and a test decides whether it got there.
📝 Write the objective in one sentence
Now crystallize the task into one sentence that describes the final state. Example: "Every test in /tests passes when you run npm test." That sentence becomes the done-state — the exact signal that tells the loop “you can stop.”
✓ Sentence with a done state
- ✓"Every test in /tests passes when you run npm test."
- ✓“The /health endpoint returns 200 in curl.”
- ✓“The build compiles without warnings.”
✗ Endless sentence
- ✗“Clean this up.”
- ✗“Make the code better.”
- ✗“Solve the problems.”
💡 Sentence test
Read your sentence and ask: "could a computer decide on its own whether this is done?" If the answer is no, your sentence is still an opinion in disguise. Rewrite it until it becomes something a command can verify.
🔧 Decide which tools to use and what NOT to touch
Define what the agent can and—more importantly—what it can't play. On the first run: allow editing /src e /tests and run the tests; nothing for merge, deploy, or delete. The worker opens a PR; you merge it.
🧱 Guardrails are the real work
There’s a phrase worth holding on to: "the guardrails are the real work, not the agents." Anyone can put an agent in a loop in five minutes. What separates a safe loop from a disaster is the time you spend deciding what it no can do it. The worker opens a PR; a human merges it—that’s the safe starting pattern.
✓ Allowed on the 1st run
- ✓Edit /src and /tests
- ✓Run the test suite
- ✓Open a PR with the changes
✗ Forbidden on the 1st run
- ✗Merge on its own
- ✗Deploying / publishing
- ✗Delete files or tests
💾 Give state a place to live
A loop that lasts more than one turn needs external memory. Ask the agent to write its progress to PROGRESS.md and give a commit with every relevant change. That way, if it loses track, it picks up exactly where it left off — instead of starting over from scratch.
🔁 Anthropic’s harness, in 5 beats
Anthropic’s research on long-running agents describes a simple rhythm that repeats each round:
Read the state — opens PROGRESS.md and remembers where it was.
Incremental progress — makes ONE change that moves things forward.
Self-verify — checks its own work (runs the tests).
Commit — records the change with a note in PROGRESS.md.
Keep it clean — closes the environment so the next iteration can resume.
🔄 Connect the 4-step cycle
Now the heart of it: the cycle that repeats each round. Gather context → make ONE change → verify (run tests) → repeat. One change per turn isn’t laziness — it’s deliberate. "Work on one feature at a time" was described as critical for the loop to converge.
Read the diagram: on each turn, the agent rereads the state, makes a single change, and runs the tests. If they pass, it stops. If not, it goes back to the beginning — one feature at a time, until it converges.
💡 Why ONE change per round
When you tell the agent to fix everything at once, it flounders: it changes ten things, two tests break for different reasons, and it doesn’t know which change caused what. One change per iteration keeps the signal clear—each test that passes or fails points to exactly one change.
🛑 Set a hard stop before running
Before pressing play, write the brake. One sentence is enough: “Stop when all tests pass, or after 10 attempts—whichever comes first.” This is the hard stop, and it's never optional.
⚠️ What happens without a hard stop
Without a brake, two disasters await you: "bizarre emergent behavior" — the loop enters strange states, trying increasingly wild solutions — and the token count, which keeps rising as it spins its wheels. A hard cap closes both doors at once.
🧩 The golden rule
A loop has two stop conditions: the good one (the goal is met — tests pass) and the safety one (the cap — maximum number of attempts). You hope for the first; you enforce the second. Never trust the model to stop on its own.
👀 Run, observe, refine the prompt
The final step: watch the first run live. And when something goes wrong, fix the instructions — not the output. Editing the result by hand is plugging the hole; editing the prompt is fixing the factory.
🏺 "Clay on the pottery wheel"
There’s a great metaphor for this: the loop is clay on the potter's wheel. When it fails, you don’t fix the broken vase — you adjust the pressure of your hands (the prompt, the guardrail, the criterion) and put the clay back on the wheel. Each failure points to a part of the prompt that needs tightening.
Your first loop, complete. Combine the 7 steps into a single prompt. Paste it into Claude Code and watch:
# SEU PRIMEIRO LOOP — cole no Claude Code
# 1. Objetivo (a frase / done-state)
Objetivo: fazer todo teste em /tests passar ao rodar `npm test`.
# 2. Ferramentas e limites (permissões + guardrail)
Você pode editar </src> e </tests> e rodar os testes.
NÃO dê merge, deploy ou delete. Não apague testes para fazê-los passar.
Quando terminar, abra um PR com as mudanças — eu dou o merge.
# 3. Estado (PROGRESS.md + commit)
A cada mudança que melhora algo, escreva 1 linha em PROGRESS.md
e dê um commit com uma nota curta.
# 4. O ciclo de 4 passos (uma mudança por volta)
Repita: (1) leia o estado e rode `npm test`, (2) faça UMA correção
no arquivo mais responsável pela 1ª falha, (3) rode `npm test` de novo
para verificar, (4) se ainda falhar, volte ao passo 1.
# 5. Hard stop (max_turns em palavras)
Pare quando todos os testes passarem, ou após 10 tentativas —
o que vier primeiro.How to verify: open a small project with 1 or 2 failing tests, paste the prompt, and don't get in the way. You should see the agent run npm test, read the failures, make a fix, run it again, and log it in PROGRESS.md—repeating until it passes or hits 10 attempts. If it tries anything outside /src and /tests, your guardrail failed: tighten the instruction and run it again.
Your loop passes a test, but the fix is ugly. What do you do?
🧾 Module Summary
Next:
3.2 — Loops to copy and run