🎯 Step 1 — Choose the problem
Select a feature, bug, or legacy module from your repository. Choosing the wrong one is the number one cause of an exercise that doesn’t get finished—and you want to finish, because the value is in see the cycle complete.
✓ Good choices
- ✓A reproducible bug nobody has had time to fix
- ✓A missing validation in an endpoint
- ✓A new field in a response, with compatibility preserved
- ✓Error handling that currently returns a generic message
✗ Choices that stall the exercise
- ✗"Refactor the payments module"
- ✗Anything that requires a database migration
- ✗A change to a public contract consumed by other teams
- ✗Repository with no tests (start by creating one)
🧪 Do it now — prepare the groundwork
Objective: isolated environment and clean starting point.
git checkout -b exercicio/<nome-curto-da-tarefa> mkdir -p docs/exercicio <comando de teste do seu projeto> # precisa passar ANTES de começar
How to verify: the suite is green and you’re on a new branch. If the suite already fails before you start, fix that first — otherwise you won’t be able to tell what the agent broke.
Small
3 to 5 files
Verifiable
Prove it with a test
Reversible
No migration
Green first
Clean baseline
📐 Step 2 — Write the specification
Use the agent to draft and you to decide. The deliverable for this stage is docs/exercicio/spec.md — and, above all, the list of questions it would have answered on its own.
🧪 Do it now — draft the spec
Objective: a spec with verifiable criteria and no hidden assumptions.
Você vai escrever uma ESPECIFICAÇÃO. Não altere nenhum arquivo de código. Tarefa: <descreva em uma frase> Leia antes de responder: <caminhos relevantes do repositório> Produza docs/exercicio/spec.md com estas seções, nesta ordem: problema · objetivo · escopo · fora do escopo · entradas · saídas · contratos · condições de erro · restrições · critérios de aceitação · testes · definição de pronto Regras: - cada critério de aceitação precisa ser verificável com sim ou não; - liste explicitamente arquivos e comportamentos que NÃO devem mudar; - inclua pelo menos 3 condições de erro (timeout, entrada inválida, duplicidade); - termine com a seção "PERGUNTAS": tudo que você teve que supor.
How to verify: answer each item in QUESTIONS yourself and edit the spec. Count how many there were—that number is the first measure of the exercise. Then ask:
Review docs/exercicio/spec.md like a critic: which acceptance criteria are still NOT objectively verifiable? Rewrite only those.
💡 Practical tip
If the QUESTIONS section is empty, be suspicious: either the task is trivial, or the agent silently filled in the gaps. Ask explicitly: “list five decisions you made without consulting me.”
Drafts
It; you decide
QUESTIONS
The most valuable part
3 errors
At a minimum
Versioned
In the repository
⚙️ Step 3 — Configure the harness
Define tools, context, permissions, and limits. The output of this stage is a AGENTS.md that the agent reads before acting—and an isolated environment where mistakes are cheap.
🧪 Do it now — exercise AGENTS.md
Objective: move the rules out of your head and into a file. Adjust what’s between < >.
# AGENTS.md ## Comandos - testar: <comando> - lint: <comando> - build: <comando> - rodar local: <comando> ## Contexto desta tarefa - especificação: docs/exercicio/spec.md (fonte da verdade) - arquivos relevantes: <liste 3 a 8> - exemplo de padrão a seguir: <arquivo que você considera bem escrito> ## Pode (sem perguntar) - ler qualquer arquivo · rodar testes, lint e build - editar arquivos em <pastas permitidas> - commitar na branch atual ## Não pode (exige minha aprovação explícita) - alterar ou remover testes existentes - adicionar dependências - tocar em <pastas proibidas>, CI/CD, secrets ou infraestrutura - push na branch principal · qualquer deploy · qualquer migração ## Limites - máximo <5> arquivos alterados - máximo <3> tentativas de correção - mesma falha 2x seguidas → parar e me relatar ## Definição de pronto - todos os critérios de aceitação da spec atendidos - <comando de teste> verde, com a saída REAL colada - nenhum arquivo fora do escopo alterado
How to verify: open a new session and ask: “read AGENTS.md and the spec, then tell me in a list what you are NOT allowed to do in this task and how you’ll know when you’re done.” If the answer differs from what you wrote, the file is ambiguous — fix it before continuing.
Written
Not in chat
Prohibitions
Explicit
Limits
Files and attempts
Echo test
Does it repeat correctly?
🔄 Step 4 — Define the loop
Write the cycle before running it. A loop defined on paper is the difference between a work session and a session of "try again" until you're exhausted.
How to read: is the loop from trail 2 applied to your case. The two outcomes on the right are the only permitted ones — notice that “keep trying indefinitely” isn’t in the diagram. If, during execution, you feel like letting it run a little longer, read this figure again.
🧪 Do it now — write the loop
Objective: record in docs/exercicio/loop.md before executing.
Objetivo verificável: <comando> retorna 0 e os critérios da spec estão atendidos. Ciclo: 1. o agente apresenta o plano (máx. 10 linhas) e ESPERA aprovação; 2. implementa a menor mudança; 3. roda <comando de teste> e cola a saída real; 4. se falhar: descreve a hipótese, corrige e volta ao passo 3. Saídas permitidas: - SUCESSO: testes verdes + critérios atendidos → segue para revisão (módulo 6.2) - TETO: 3 tentativas ou 5 arquivos alterados → para e relata - SEM PROGRESSO: mesma falha 2x → para, relata o que tentou e o que descartou Proibido durante o loop: alterar testes, adicionar dependência, sair do escopo.
How to verify: read the three outcomes aloud. If you can't say right now which command proves the "SUCCESS" outcome, go back to step 2: the criterion is not yet verifiable.
Plan first
With approval
Three outputs
And only them
Tests
Protected area
Written beforehand
Not in the heat of the moment
🧾 Prepare the exercise log
Without a record, the exercise becomes an impression (“I thought it went well”). With a record, it becomes the case you take to the team—and the basis for deciding the module 5.3 autonomy level.
Create docs/exercicio/registro.md
tarefa: <uma linha> perguntas que a spec revelou: <n> tempo de preparação (etapas 1-4): <min> tempo de execução (etapas 5-8): <min> tentativas do loop: <n> custo aproximado: <valor> intervenções minhas (o que eu precisei corrigir): - <...> suposições que o agente fez sem avisar: - <...> gates que faltaram no repositório: - <...> o que vira rule / gate / item do AGENTS.md na próxima vez: - <...>
💡 Practical tip
Take notes while you work, not afterward. The intervention that seems obvious in the moment fades from memory in two hours—and it’s exactly the one that becomes the best rule in your AGENTS.md.
Take notes while
Not afterward
Intervention
It’s data, not a failure
Cost
Sign in to the account
Becomes a rule
On your next task
✅ Preparation checkpoint
Move on to module 6.2 only when every item is checked. Each item missing here becomes costly rework there—or, worse, a result that passes the tests but is wrong.
📋 Before releasing the agent
☐ New branch created and test suite passing on the baseline
☐ Task fits in 3 to 5 files and is reversible
☐ docs/exercicio/spec.md written, with all verifiable criteria
☐ QUESTIONS section answered by you and incorporated into the spec
☐ Explicit negative scope (files and behaviors that must remain untouched)
☐ AGENTS.md with commands, permissions, prohibitions, and limits
☐ Echo test completed: the agent correctly repeated what it must not do
☐ docs/exercicio/loop.md with a verifiable objective and three outputs
☐ docs/exercicio/registro.md created, with the preparation already documented
Quick check: you finished the spec and are in a hurry. What MUST be in place before you release the agent?
All ✓
Before moving on
Zero code
So far
Good preparation
Quick run
Missing item
It gets expensive later
📌 What you produced in this module
Next Module:
6.2 - Execution, quality gates, independent review, and delivery with evidence.