🎯 Etapa 1 — Elige el problema
Selecciona una funcionalidad, un error o un módulo heredado de tu repositorio. Elegir mal es la causa principal de que el ejercicio no termine, y quieres terminarlo porque el valor está en ver el ciclo cerrarse.
✓ Buenas decisiones
- ✓Un bug reproducible que nadie tuvo tiempo de corregir
- ✓Una validación faltante en un endpoint
- ✓Un campo nuevo en una respuesta, con compatibilidad preservada
- ✓Manejo de errores que hoy devuelve un mensaje genérico
✗ Decisiones que bloquean el ejercicio
- ✗"Refactorizar el módulo de pagos"
- ✗Cualquier cosa que requiera una migración de base de datos
- ✗Cambio en un contrato público que consumen otros equipos
- ✗Repositorio sin ninguna prueba (empieza creando una)
🧪 Hazlo ahora — preparar el terreno
Objetivo: entorno aislado y punto de partida limpio.
git checkout -b exercicio/<nome-curto-da-tarefa> mkdir -p docs/exercicio <comando de teste do seu projeto> # precisa passar ANTES de começar
Cómo verificar: la suite está en verde y estás en una nueva branch. Si la suite ya falla antes de que empieces, resuélvelo primero; de lo contrario, no podrás distinguir qué rompió el agente.
Pequeña
3 a 5 archivos
Verificable
Prueba mediante pruebas
Reversible
Sin migración
Verde primero
Baseline limpia
📐 Etapa 2 — Escribe la especificación
Usa el agente para hacer un borrador y tú para decidir. El producto de esta etapa es docs/exercicio/spec.md — y, sobre todo, la lista de preguntas que habría respondido por su cuenta.
🧪 Hazlo ahora — redactar la spec
Objetivo: una spec con criterios verificables y ninguna suposición oculta.
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.
Cómo verificar: responde tú mismo cada elemento de PREGUNTAS y edita la spec. Cuenta cuántas eran: ese número es la primera medida del ejercicio. Después pide:
Revisa docs/exercicio/spec.md como una persona crítica: ¿qué criterios de aceptación aún NO se pueden verificar objetivamente? Reescribe solo esos.
💡 Consejo práctico
Si la sección PREGUNTAS está vacía, desconfía: o la tarea es trivial, o el agente llenó los vacíos en silencio. Pide explícitamente: «enumera cinco decisiones que tomaste sin consultarme».
Borrador
Él; tú decides
PREGUNTAS
La parte más valiosa
3 errores
Como mínimo
Con control de versiones
En el repositorio
⚙️ Etapa 3 — Configura el harness
Define las herramientas, el contexto, los permisos y los límites. El producto de esta etapa es un AGENTS.md que el agente lee antes de actuar —y un entorno aislado donde equivocarse cuesta poco.
🧪 Hazlo ahora — AGENTS.md del ejercicio
Objetivo: sacar las reglas de tu cabeza y ponerlas en un archivo. Ajusta lo 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
Cómo verificar: abre una sesión nueva y pide: "lee el AGENTS.md y la spec y dime, en una lista, qué NO puedes hacer en esta tarea y cómo sabrás que terminaste". Si la respuesta difiere de lo que escribiste, el archivo es ambiguo; corrígelo antes de continuar.
Escrito
No en el chat
Prohibiciones
Explícitas
Límites
Archivos e intentos
Prueba del eco
¿Lo repite correctamente?
🔄 Etapa 4 — Define el loop
Escribe el ciclo antes de ejecutarlo. Un loop definido en papel es la diferencia entre una sesión de trabajo y una sesión de «inténtalo de nuevo» hasta el agotamiento.
Cómo leer: es el loop de la ruta 2 aplicado a tu caso. Las dos salidas de la derecha son las únicas permitidas: observa que «seguir intentando indefinidamente» no aparece en el diagrama. Si durante la ejecución sientes ganas de dejarlo correr un poco más, vuelve a leer esta figura.
🧪 Hazlo ahora — escribe el loop
Objetivo: dejar registrado en docs/exercicio/loop.md antes de ejecutar.
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.
Cómo verificar: lee las tres salidas en voz alta. Si no sabes decir ahora qué comando demuestra la salida «SUCESSO», vuelve a la etapa 2: el criterio todavía no es verificable.
Plan primero
Con aprobación
Tres resultados
Y solo ellas
Pruebas
Área protegida
Escrito antes
No en el calor del momento
🧾 Prepara el registro del ejercicio
Sin registro, el ejercicio se convierte en una impresión («me pareció bueno»). Con registro, se convierte en el argumento que llevas al equipo y en la base para decidir el nivel de autonomía del módulo 5.3.
Crea 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: - <...>
💡 Consejo práctico
Anota durante, no después. La intervención que parece obvia en el momento desaparece de la memoria en dos horas, y es justamente esa la que se convierte en la mejor rule de tu AGENTS.md.
Anota durante
No después
Intervención
Es un dato, no un error
Costo
Inicia sesión en la cuenta
Se convierte en regla
En la próxima tarea
✅ Punto de control de la preparación
Avanza al módulo 6.2 solo cuando todos los elementos estén marcados. Cada elemento que falte aquí se convierte en retrabajo costoso allá o, peor aún, en un resultado que pasa las pruebas y está mal.
📋 Antes de liberar al agente
☐ Nueva branch creada y suite de pruebas aprobada en la base
☐ La tarea abarca de 3 a 5 archivos y es reversible
☐ docs/exercicio/spec.md escritura, con todos los criterios verificables
☐ Sección PREGUNTAS respondida por ti e incorporada a la spec
☐ Alcance negativo explícito (archivos y comportamientos intocables)
☐ AGENTS.md con comandos, permisos, prohibiciones y límites
☐ Prueba del eco realizada: el agente repitió correctamente lo que no puede hacer
☐ docs/exercicio/loop.md con un objetivo verificable y tres resultados
☐ docs/exercicio/registro.md creado y con la preparación ya anotada
Chequeo rápido: terminaste la spec y tienes prisa. ¿Qué NO puede faltar antes de habilitar al agente?
Todo ✓
Antes de avanzar
Cero código
Hasta aquí
Buena preparación
Ejecución rápida
Elemento faltante
Cuesta caro después
📌 Qué produjiste en este módulo
Próximo módulo:
6.2 - Ejecución, quality gates, revisión independiente y entrega con evidencias.