🎯 Etapa 1 — Escolha o problema
Selecione uma funcionalidade, bug ou módulo legado do seu repositório. A escolha errada é a causa número um de exercício que não termina — e você quer terminar, porque o valor está em ver o ciclo fechar.
✓ Boas escolhas
- ✓Um bug reproduzível que ninguém teve tempo de corrigir
- ✓Uma validação faltando num endpoint
- ✓Um campo novo numa resposta, com compatibilidade preservada
- ✓Tratamento de erro que hoje retorna mensagem genérica
✗ Escolhas que travam o exercício
- ✗"Refatorar o módulo de pagamentos"
- ✗Qualquer coisa que exija migração de banco
- ✗Mudança em contrato público consumido por outros times
- ✗Repositório sem nenhum teste (comece criando um)
🧪 Faça agora — preparar o terreno
Objetivo: ambiente isolado e ponto de partida limpo.
git checkout -b exercicio/<nome-curto-da-tarefa> mkdir -p docs/exercicio <comando de teste do seu projeto> # precisa passar ANTES de começar
Como verificar: a suíte está verde e você está numa branch nova. Se a suíte já falha antes de você começar, resolva isso primeiro — senão você não vai conseguir distinguir o que o agente quebrou.
Pequena
3 a 5 arquivos
Verificável
Prova por teste
Reversível
Sem migração
Verde antes
Baseline limpa
📐 Etapa 2 — Escreva a especificação
Use o agente para rascunhar e você para decidir. O produto desta etapa é docs/exercicio/spec.md — e, principalmente, a lista de perguntas que ele teria respondido sozinho.
🧪 Faça agora — rascunhar a spec
Objetivo: uma spec com critérios verificáveis e nenhuma suposição escondida.
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.
Como verificar: responda cada item de PERGUNTAS você mesmo e edite a spec. Conte quantas eram — esse número é a primeira medida do exercício. Depois peça:
Revise docs/exercicio/spec.md como um crítico: quais critérios de aceitação ainda NÃO são verificáveis objetivamente? Reescreva apenas esses.
💡 Dica prática
Se a seção PERGUNTAS vier vazia, desconfie: ou a tarefa é trivial, ou o agente preencheu as lacunas em silêncio. Peça explicitamente: "liste cinco decisões que você tomou sem me consultar".
Rascunha
Ele; você decide
PERGUNTAS
A parte mais valiosa
3 erros
No mínimo
Versionada
No repositório
⚙️ Etapa 3 — Configure o harness
Defina ferramentas, contexto, permissões e limites. O produto desta etapa é um AGENTS.md que o agente lê antes de agir — e um ambiente isolado onde errar é barato.
🧪 Faça agora — AGENTS.md do exercício
Objetivo: tirar as regras da sua cabeça e colocá-las num arquivo. Ajuste o que está entre < >.
# 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
Como verificar: abra uma sessão nova e peça: "leia o AGENTS.md e a spec e me diga, em lista, o que você NÃO pode fazer nesta tarefa e como saberá que terminou". Se a resposta divergir do que você escreveu, o arquivo está ambíguo — corrija antes de seguir.
Escrito
Não no chat
Proibições
Explícitas
Limites
Arquivos e tentativas
Teste do eco
Ele repete certo?
🔄 Etapa 4 — Defina o loop
Escreva o ciclo antes de rodá-lo. Um loop definido no papel é a diferença entre uma sessão de trabalho e uma sessão de "tenta de novo" até o cansaço.
Como ler: é o loop da trilha 2 aplicado ao seu caso. As duas saídas à direita são as únicas permitidas — repare que "continuar tentando indefinidamente" não existe no desenho. Se durante a execução você sentir vontade de deixar rodar mais um pouco, releia esta figura.
🧪 Faça agora — escreva o loop
Objetivo: deixar registrado em docs/exercicio/loop.md antes de executar.
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.
Como verificar: leia as três saídas em voz alta. Se você não souber dizer, agora, qual comando prova a saída "SUCESSO", volte à etapa 2: o critério ainda não é verificável.
Plano primeiro
Com aprovação
Três saídas
E só elas
Testes
Área protegida
Escrito antes
Não no calor
🧾 Prepare o registro do exercício
Sem registro, o exercício vira impressão ("achei que foi bom"). Com registro, ele vira o argumento que você leva para o time — e a base para decidir o nível de autonomia do módulo 5.3.
Crie 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: - <...>
💡 Dica prática
Anote durante, não depois. A intervenção que parece óbvia no momento some da memória em duas horas — e é justamente ela que vira a melhor rule do seu AGENTS.md.
Anote durante
Não depois
Intervenção
É dado, não falha
Custo
Entra na conta
Vira regra
Na próxima tarefa
✅ Checkpoint da preparação
Só avance para o módulo 6.2 com todos os itens marcados. Cada item que faltar aqui vira retrabalho caro lá — ou, pior, um resultado que passa nos testes e está errado.
📋 Antes de liberar o agente
☐ Branch nova criada e suíte de testes verde na base
☐ Tarefa cabe em 3 a 5 arquivos e é reversível
☐ docs/exercicio/spec.md escrita, com todos os critérios verificáveis
☐ Seção PERGUNTAS respondida por você e incorporada à spec
☐ Escopo negativo explícito (arquivos e comportamentos intocáveis)
☐ AGENTS.md com comandos, permissões, proibições e limites
☐ Teste do eco feito: o agente repetiu corretamente o que não pode fazer
☐ docs/exercicio/loop.md com objetivo verificável e três saídas
☐ docs/exercicio/registro.md criado e com a preparação já anotada
Checagem rápida: você terminou a spec e está com pressa. O que NÃO pode faltar antes de liberar o agente?
Tudo ✓
Antes de avançar
Zero código
Até aqui
Preparação boa
Execução rápida
Item faltando
Custa caro depois
📌 O que você produziu neste módulo
Próximo Módulo:
6.2 - Execução, quality gates, revisão independente e entrega com evidências.