⚡ Os Tres Comandos Fundamentais
Antes de montar qualquer sistema de loop, voce precisa entender os tres primitivos que o Claude Code oferece nativamente. Eles sao os tijolos de qualquer automacao ciclica. Como Cole Medin coloca: "Loop engineering is really not that complicated. I don't even know if it deserves its own term."
🧱 Os Tres Primitivos
/loop - Intervalo de execucao
Define um intervalo (ex: cada 5 minutos) para o agente acordar e executar um prompt. O uso mais comum: monitorar algo externo (GitHub issues, fila de tarefas) e agir quando ha trabalho.
"Every five minutes, I'm going to check for new GitHub issues in this repo and handle any that come in." - Cole Medin
/goal - Criterio de conclusao
Voce define o que "pronto" significa. O agente trabalha ate satisfazer o criterio, sem intervalo fixo. Parecido com o conceito de Ralph loops que viralizou: trabalhe ate estar feito.
/routines - Jobs agendados
Jobs agendados recorrentes. Ex: "A cada hora, acorde, leia o spec document e execute a proxima tarefa pendente." E o cron do mundo dos agentes.
"Every hour, I want you to wake up, look at some larger spec document, and then handle the next task." - Cole Medin
💡 Dica Pratica
Na maioria dos casos, voce so precisa do /loop com um plan.md. Os outros dois sao ferramentas complementares. Nao complique se o problema e simples.
📋 Criando o plan.md
O plan.md e o coracao de qualquer loop basico. E um arquivo Markdown simples com uma lista de tarefas. O agente le, executa a primeira tarefa nao-concluida, valida, marca como feita, e dorme ate o proximo ciclo. Cole Medin demonstrou isso ao vivo: "I just have this as an example. These are the tasks that we wanted to go through incrementally."
📄 Template de plan.md
# Plano de Tarefas
## Contexto
Projeto: [nome do projeto]
Objetivo: [o que queremos construir/fazer]
Regras: uma tarefa por ciclo, validar antes de marcar
## Tarefas
- [ ] Tarefa 1: Criar estrutura base do projeto
Criterio: pasta criada, package.json init, deps instaladas
- [ ] Tarefa 2: Implementar componente principal
Criterio: componente renderiza sem erros
- [ ] Tarefa 3: Adicionar testes unitarios
Criterio: npm test passa com 0 falhas
- [ ] Tarefa 4: Configurar linting e formatacao
Criterio: npm run lint sem warnings
- [ ] Tarefa 5: Documentar API no README
Criterio: README com exemplos de uso
## Notas
- Nao pular tarefas
- Se uma tarefa falhar, reportar o erro e parar
- Cada tarefa deve ser auto-contida✓ Bom plan.md
- ✓Tarefas atomicas e independentes
- ✓Criterio de validacao explicito
- ✓Contexto do projeto no topo
- ✓Checkboxes Markdown para tracking
✗ Plan.md problematico
- ✗Tarefas vagas ("melhorar o codigo")
- ✗Sem criterio de "pronto"
- ✗Tarefas interdependentes demais
- ✗10+ tarefas num unico plan
🤔 Ponto de Reflexao
O plan.md e essencialmente um contrato entre voce e o agente. Quanto mais explicito o criterio de validacao, menos chance do agente "achar" que terminou quando nao terminou. Pergunte-se: se eu der esse plan para um estagiario, ele saberia quando cada tarefa esta feita?
🚀 O Prompt que Monta o Loop Sozinho
A parte mais elegante do sistema: voce nao precisa configurar o loop manualmente. Voce pede ao Claude Code para carregar a loop skill e ele configura o ciclo por conta propria. Cole Medin mostrou exatamente isso: "You just tell it to use the loop skill. So there's a capability built right into the tool where it knows how to set up these loop systems based on what we ask it to do."
📦 Prompt Pack: Setup do Loop
Copie e cole diretamente no Claude Code. O agente vai configurar tudo sozinho.
PROMPT 1 - Setup basico
Load the loop skill. Read plan.md in the project root.
Work through the tasks one at a time. For each cycle:
1. Find the first unchecked task
2. Execute it completely
3. Validate against the criteria listed
4. Mark it as done with [x] in plan.md
5. Schedule a quick wake-up for the next task
If all tasks are complete, report back with a summary.PROMPT 2 - Com intervalo definido
/loop 5m
Check plan.md. Execute the next unchecked task.
Validate the result. Mark complete if validation passes.
If validation fails, note the error in plan.md and move on.PROMPT 3 - O que Cole Medin usou (simplificado)
/loop work through plan.md one task at a time"I didn't write this prompt myself at all... it wrote the prompt: /loop work through plan.md one task at a time." - Cole Medin
💡 Como funciona por dentro
Quando voce diz "load the loop skill", o Claude Code:
- Reconhece que existe uma capability de loop interna
- Le o plan.md para entender o escopo
- Executa a primeira tarefa pendente
- Valida o resultado
- Configura o
/loopwake-up automaticamente - Repete ate tudo estar marcado como feito
👁️ Wake-Up Automatico e Monitoramento
O wake-up e o mecanismo que transforma uma execucao unica em um loop real. Depois de completar uma tarefa, o Claude Code agenda o proximo ciclo sozinho. "It sets up the /loop by itself. And if we scroll down after it does and validates the first task, we can see that it's resuming with a /loop wake up."
Leitura do plan.md
Primeiro ciclo
O agente le o arquivo, identifica que e uma "sequential task list" e encontra a primeira tarefa nao-marcada.
Execucao + Validacao
Trabalho real
Executa a tarefa, roda os testes ou verificacoes definidas no criterio, marca [x] no plan.md.
Wake-Up Automatico
Continuidade
O agente agenda um /loop wake-up com o prompt que ele mesmo escreveu: "work through plan.md one task at a time". No proximo ciclo, repete do passo 1.
Conclusao
Fim do loop
Quando todas as tarefas estao marcadas, o agente para de agendar wake-ups e reporta o resultado final.
⚠️ Limitacao Importante
O terminal precisa estar aberto durante todo o processo. Se voce fechar o terminal, o loop morre. Isso e diferente de um daemon ou servico em background. Cole Medin alerta: "As long as our terminal is up and running with Claude Code, it's able to autonomously handle this." Isso significa: sem terminal, sem loop.
🔧 Contexto e Boas Praticas
O loop basico e simples, mas tem armadilhas que sabotam o resultado se voce nao tomar cuidado. A mais perigosa: context bloat. Num loop, tudo roda na mesma sessao. Cada ciclo acumula mais contexto, e eventualmente o LLM fica sobrecarregado.
✓ Boas Praticas
- ✓Tarefas curtas (1-2 arquivos por ciclo)
- ✓Criterios de validacao automatizaveis
- ✓Plan.md com no maximo 5-7 tarefas
- ✓Monitorar a sessao periodicamente
✗ O que Evitar
- ✗Loops com 20+ tarefas na mesma sessao
- ✗Deixar rodando sem olhar por horas
- ✗Tarefas que dependem de output anterior
- ✗Ignorar erros e deixar o loop continuar
📊 Dados do Mundo Real
Cole Medin testou o loop basico e compartilhou resultados concretos:
- 2 minutos para completar as 2 primeiras tarefas de um plan simples
- Automatico o agente escreveu o proprio prompt de wake-up
- Sequencial uma tarefa por ciclo, sem tentar fazer tudo de uma vez
"I came back a couple of minutes later and it's already done with the first two tasks. So it's gone through two iterations of the loop already." - Cole Medin
🤔 Ponto de Reflexao
O loop basico e poderoso para tarefas simples e sequenciais. Mas perceba: tudo roda numa unica sessao, com um unico modelo, sem observabilidade. Para qualquer coisa mais complexa, voce vai precisar dos recursos das proximas secoes (Archon, dashboard, mix de modelos). O loop basico e o "Hello World" do loop engineering, nao o sistema de producao.
❓ Questionamentos e Limites
O loop basico e a forma mais simples de loop engineering, mas levanta questoes que voce precisa considerar antes de investir tempo nessa abordagem.
Questoes Abertas
Boris realmente gerencia "tens of thousands of agents per day"?
Cole Medin questiona abertamente: "Boris Cherny says that there are days he manages tens of thousands of AI agents at once. Like really, is that actually practical? Is that going to scale?" A resposta honesta: provavelmente, para a escala da Anthropic, sim. Para voce e para mim, nao necessariamente.
E se o loop engasgar no meio?
Sem state externo, um crash no terminal perde todo o progresso. O plan.md salva parte (tarefas ja marcadas), mas o contexto da sessao vai embora. Por isso os proximos modulos cobrem durabilidade via banco externo.
O custo vale a pena para tarefas simples?
Um loop de 5 tarefas simples pode custar dezenas de milhares de tokens so em overhead de orchestracao. Se voce pode fazer a mesma coisa em 5 prompts diretos, o loop nao faz sentido financeiramente. O valor real aparece em tarefas repetitivas onde o humano seria um gargalo.
🎯 Quando o loop basico brilha
- •Provas de conceito rapidas
- •Listas de tarefas mecanicas (refatoracao, migracao)
- •Aprendizado e experimentacao com loops
- •Prototipagem antes de investir em infra mais pesada
📝 Resumo do Modulo
Proximo Modulo:
3.2 - Workflows Deterministicos com Archon: como ir alem do loop basico com processos controlados e mix de modelos