Conteúdo detalhado
🧭 Por que um agente se perde em horas
Um agente que trabalha por minutos costuma ir bem. Por horas, o problema aparece: a conversa enche, o sistema compacta (resume) o que veio antes e detalhes importantes se perdem. O agente passa a repetir "vou terminar e commitar" sem terminar, ou reabre item que já estava feito. Isso é contexto degradado, e não é falta de inteligência: é falta de memória fora da conversa.
🌱 Novo aqui?
Compactação é quando o agente resume a conversa antiga para caber mais coisa. O resumo é útil, mas esquece detalhes. Contexto degradado é quando, depois de algumas compactações, o agente já não lembra bem o que combinou.
🔥 Os sinais de que o contexto degradou
Repetir a mesma frase de fechamento sem fechar; reabrir um item já feito; esquecer uma regra combinada no começo; ficar rodando sem produzir nada novo. Se você vê isso, a sessão já passou do ponto.
✓ A saída
Tirar a memória da conversa e pôr em arquivos: o objetivo com prova de pronto, o estado atual, o plano e as notas. Depois de cada compactação o agente relê os arquivos e volta ao rumo. É isso que o kit execucao-longa organiza.
Por que aprender
Porque a execução longa só funciona se o rumo mora em arquivos e não na cabeça do agente. Entender por que ele se perde mostra quais proteções montar nos próximos tópicos.
Conceitos-chave
📁 A pasta longrun/ (novo-longrun.sh e os 7 arquivos)
O kit cria uma pasta própria para cada trabalho longo. Você roda tools/novo-longrun.sh <projeto> <slug> e ele monta longrun/<data>-<slug>/ com sete arquivos. Cada um tem uma função, e juntos formam a memória que sobrevive à compactação.
🌱 Novo aqui?
O slug é um nome curto do trabalho, sem espaços (ex.: limpar-docs). O canal é um arquivo onde o agente só acrescenta notas: fatos, aprendizados e armadilhas que a compactação costuma apagar.
Os 7 arquivos criados por novo-longrun.sh
longrun/2026-10-12-meu-projeto/ ├── goal.md # o resultado + a prova de pronto ├── plan.md # os passos ├── state.md # onde estou agora ├── progress.md # o que já foi feito ├── failures.md # o que deu errado ├── decisions.md # o que ficou decidido └── canal.md # notas do que a compactação perde
🔎 Regra de ouro
Depois de toda compactação ou retomada, o agente relê nesta ordem: goal, state, plan, canal. Durante o trabalho, ele registra cedo no canal e faz commit a cada checkpoint.
Por que aprender
Porque é a pasta que transforma "um agente que se perde" em "um agente que retoma sozinho". Quem tem o rumo escrito nunca começa do zero.
Conceitos-chave
🎯 goal.md nível 3: comando → saída
O goal.md diz o resultado em uma frase e, o mais importante, como provar que está pronto. Cada critério é um par comando → saída esperada. No nível 3, os critérios cobrem função (faz o que devia), regressão (não quebrou o que já funcionava) e limite (não deu para cumprir por atalho).
🌱 Novo aqui?
Um atalho é cumprir o critério sem fazer o trabalho de verdade, por exemplo apagar os testes que falham para dar "0 falhas". A regressão e o limite existem para fechar essa porta.
Exemplo de prova de pronto em nível 3
# goal.md Resultado: todas as páginas do site passam no validador. Prova de pronto (nível 3): 1. função npm test → 0 falhas 2. regressão ls tests/ | wc -l → continua ≥ 48 testes 3. limite git diff --stat tests/ → vazio (tests/ intocado)
⚠️ Por que só "0 falhas" não basta
Um agente apressado pode apagar o teste que falha. Por isso o exemplo exige 0 falhas e pelo menos 48 testes e a pasta tests/ intocada. Três provas juntas, nenhum atalho.
Por que aprender
Porque o agente só para quando a prova passa. Se a prova é frouxa, ele "termina" cedo e errado; se é forte, ele trabalha até acertar de verdade.
Conceitos-chave
▶️ Rodar o /goal no Codex e no Claude Code
Com o goal.md pronto, você inicia o trabalho com o comando /goal, que existe tanto no Codex quanto no Claude Code. Você aponta para o objetivo e o agente passa a trabalhar até a prova passar. O mesmo kit serve aos dois executores, como a identidade portátil do módulo 5.1.
🌱 Novo aqui?
O /goal é um comando que fixa um objetivo e mantém o agente tentando até cumpri-lo, em vez de parar na primeira resposta.
🔎 Atenção no Claude Code
Lá, a prova precisa aparecer na saída da conversa. O avaliador do /goal só lê a conversa, não vai abrir seus arquivos. Então faça o agente rodar o comando da prova e mostrar o resultado.
✓ Enquanto roda
Acompanhe sem interromper. Releia o canal de vez em quando. Só intervenha nos sinais do próximo tópico.
Por que aprender
Porque o /goal é o botão de "ir e voltar mais tarde". Sem ele, você teria que empurrar o agente a cada passo.
Conceitos-chave
🛑 Quando parar e chamar o humano
Trabalho longo não é trabalho sem você. Há três sinais de que é hora de parar o agente e agir: três ciclos sem avanço mensurável; o agente repete "vou terminar e commitar" sem terminar ou reabre item já feito (o contexto degradou); e a 3ª compactação.
🌱 Novo aqui?
Um ciclo sem avanço mensurável é uma rodada em que nenhum número da prova melhorou (mesmos testes falhando, mesma contagem). Handoff é o resumo de passagem que a próxima sessão lê para continuar.
1. Sem avanço
3 ciclos seguidos sem nada medir melhor.
2. Contexto degradou
Repete o fechamento sem fechar ou reabre item feito.
3. 3ª compactação
Grave o handoff, abra sessão nova e rode /prime.
⚠️ Também chame o humano quando
Envolver crédito ou API, ação irreversível ou externa, credencial ausente ou decisão de negócio. Isso conversa com as cercas do módulo de Regras e Ganchos: o agente não decide sozinho o que é caro ou sem volta.
Por que aprender
Porque saber parar é parte do método. O erro caro é deixar o agente girar por horas em falso.
Conceitos-chave
🤖 Modo headless: loop-longrun.sh com tetos
No modo headless ninguém fica olhando a tela. O script tools/loop-longrun.sh <pasta> repete ciclos, cada um um codex exec com limite de tempo. Quem decide continuar é o teste da prova. O loop para sozinho quando conclui, quando estagna ou quando bate um teto.
🌱 Novo aqui?
Headless é rodar sem janela nem interação, no fundo. Teto é um limite máximo (de tempo, de memória) que corta o processo antes que ele estrague a máquina.
O laço do modo headless
tools/loop-longrun.sh longrun/2026-10-12-meu-projeto │ ├── cada ciclo = um codex exec com teto de tempo ├── quem decide continuar é o teste, não o agente └── para sozinho: concluído · estagnação · teto
🔥 Tetos sempre
Timeout em cada ciclo, memória limitada com systemd-run --user --scope -p MemoryMax= e saída curta das ferramentas. Sem teto, um laço esquecido pode travar o computador.
Por que aprender
Porque é o que permite dormir enquanto o agente trabalha, com segurança. Os tetos são o cinto de segurança.
Conceitos-chave
🛠️ PRÁTICO: seu primeiro longrun + medir-sessao.py
Hora de fazer. Escolha um trabalho pequeno e verificável (algo que um comando prove que acabou) e rode o ciclo completo. Ao final, tools/medir-sessao.py mostra duração, compactações, tokens e cache da sessão, para você ver o que o trabalho custou.
🌱 Novo aqui?
O .jsonl é o arquivo de log da sessão que o Claude Code e o Codex guardam. O medir-sessao.py lê esse log e devolve os números.
Passo a passo do primeiro longrun
# 1. criar a pasta do trabalho tools/novo-longrun.sh meu-projeto limpar-docs # 2. abrir e preencher o goal.md (resultado + prova nível 3) longrun/<data>-limpar-docs/goal.md # 3. iniciar o /goal no Codex ou no Claude Code /goal longrun/<data>-limpar-docs/goal.md # 4. acompanhar: relê goal → state → plan → canal após compactar # 5. ao fim, medir a sessão (duração, compactações, tokens, cache) tools/medir-sessao.py <sessao>.jsonl
✓ Confira ao final
A prova do goal.md passou, o canal tem notas úteis e você tem os números da sessão. Se parou antes, veja em failures.md o que travou e ajuste a prova.
🔗 Guia e área
Guia completo: inematds.github.io/execucao-longa/guia. Área com materiais: eventos.inema.pro/execucao-longa.
Por que aprender
Porque execução longa se aprende fazendo uma vez. O primeiro longrun pequeno ensina mais que ler tudo duas vezes.
Conceitos-chave
🎉 Você chegou ao fim
Fim da Trilha 5 — e do curso:
Você fechou as 5 trilhas. Agora escolha um domínio, construa o seu OS e rode /os-coach audit para pontuá-lo contra o seu objetivo.