Aula 1 · 15 min
Uma sessão longa falha de três jeitos: não sabe quando parar, esquece o que fez depois de compactar e gasta o que não devia. O kit execucao-longa responde com arquivos, não com memória do modelo: o agente relê a pasta em vez de lembrar. Nesta aula você instala o kit e cria a primeira pasta.
Começar a aula
Objetivo: criar a pasta longrun/ de uma execução e dizer, para cada um dos sete arquivos, quem escreve, quando é lido e se só acrescenta.
Clique em cada bloco: quem escreve, quando é lido e como muda.
Role a página: cada etapa abaixo acende a sua parte do diagrama.
Resultado em uma frase, critérios de pronto (função, regressão, limite), tetos, restrições e portões humanos. É o único arquivo que o agente não deve reescrever: mudar o goal no meio é mudar de tarefa.
Os dois são fotografias do agora: reescrever, não acumular. O state.md termina com os comandos exatos para retomar. Quando a primeira linha de "Funciona" diz concluído, o vigia e o hook param de tratar a execução como ativa.
Histórico datado em tabela. Nunca se apaga linha: é o que permite ver depois se o agente reabriu um item já feito ou repetiu a mesma tentativa três vezes.
Conhecimento do projeto, não estado da tarefa: onde as coisas estão, o nome certo de cada peça, a armadilha que custou uma hora. Só acrescenta, uma linha por fato, com data. O hook pede para preencher na faixa 1 (aula 3).
Depois de toda compactação ou retomada, a primeira coisa é reler os arquivos, na ordem goal → state → plan → canal → fim de progress e failures, e seguir do primeiro item pendente.
O objetivo fica parado no goal.md; o agora fica no plan e no state; o histórico só cresce em progress, failures e decisions; o que o resumo perde fica no canal.
Os mesmos arquivos servem para o Claude Code e para o Codex: um retoma o que o outro gravou.
Uma execução do começo ao fim, vista pelos arquivos.
novo-longrun.sh cria a pasta com os sete arquivos já carimbados com a data.
Você preenche o goal.md. É a parte demorada, e é a que decide se a execução termina (aula 2).
longrun/2026-10-19-contador-palavras/
Lê state e plan, escolhe a próxima ação útil, executa e testa.
No fim reescreve state e plan e acrescenta uma linha em progress. Se algo deu errado, uma linha em failures.
| 2026-10-01 14:30 | medição do piloto | 7714c3c | sim (nível 3) | 332791 / 304000 / 4296 | 0 |
O resumo da compactação mistura o confirmado com o palpite. Os arquivos não.
O agente relê goal → state → plan → canal antes de agir e não reabre o que o state diz que está feito.
O state.md diz concluído, mas quem fecha é você: roda o teste final por conta própria e mede a sessão (aula 7).
A menor correção de cada falha vai do failures.md para o FALHAS.md do projeto.
Uma vez por máquina, e depois uma pasta por execução. Os caminhos seguem o README do kit.
git clone https://github.com/inematds/execucao-longa ~/projetos/execucao-longa cd ~/projetos/execucao-longa python3 -m pytest -q -p no:cacheprovider | tail -1
~/projetos/execucao-longa/tools/novo-longrun.sh ~/projetos/<seu-projeto> <slug-do-objetivo> ls ~/projetos/<seu-projeto>/longrun/*/
## Execução longa (/goal, loop, objetivo de horas) — método em ~/projetos/execucao-longa - **Antes de começar:** `~/projetos/execucao-longa/tools/novo-longrun.sh <projeto> <slug>` cria `longrun/<data>-<slug>/` (goal, plan, state, progress, failures, decisions, canal). Critério de pronto no `goal.md` em **nível 3+**: `comando → saída esperada`, cobrindo função, regressão e limite, sem atalho possível (contagem mínima, testes congelados, validador). - **Durante:** releia goal → state → plan → canal após toda compactação ou retomada; registre cedo no `canal.md` (só acrescentar) fatos, aprendizados, glossário e armadilhas; teste cada mudança; commit a cada checkpoint; continue enquanto houver próxima ação útil e segura. - **Parar e chamar o humano:** 3 ciclos sem avanço mensurável; o mesmo plano de fechamento repetido sem fechar ou item já feito reaberto (contexto degradou); crédito/API, ação irreversível ou externa, credencial ausente, decisão de negócio. - **Faixas de contexto** (no Claude Code o hook avisa uma vez cada; no Codex, acompanhe o % em `/status`): ~50% → registrar no `canal.md`; ~70% → atualizar estado e pedir `/compact`; ~85% ou 3ª compactação → `/session-handoff` + sessão nova + `/prime`. - **Headless:** `~/projetos/execucao-longa/tools/loop-longrun.sh <pasta-longrun>` (flock, timeout, MemoryMax, testes protegidos, parada por estagnação). Medir: `tools/medir-sessao.py <jsonl>`. - Tetos sempre: timeout, memória (`systemd-run --user --scope -p MemoryMax=`), saída de ferramenta curta. - **Histórico:** `recall "termo" [--projeto X] [--fonte codex|claude] [--desde AAAA-MM-DD]` busca em tudo o que já foi dito com o Codex e o Claude nesta máquina (índice reindexado de hora em hora) — use antes de perguntar ao usuário algo que pode já ter sido decidido.
$ python3 -m pytest -q -p no:cacheprovider | tail -1 73 passed in 18.59s $ novo-longrun.sh ~/ensaio/projeto-teste contador-palavras criado: ~/ensaio/projeto-teste/longrun/2026-10-19-contador-palavras próximo: preencher ~/ensaio/projeto-teste/longrun/2026-10-19-contador-palavras/goal.md (critérios nível 3+) e colar templates/prompt-goal-codex.md no /goal $ ls ~/ensaio/projeto-teste/longrun/*/ canal.md decisions.md failures.md goal.md plan.md progress.md state.md $ novo-longrun.sh ~/ensaio/projeto-teste contador-palavras já existe: ~/ensaio/projeto-teste/longrun/2026-10-19-contador-palavras $ echo $? 1
Rodado com o kit de 18/10/2026; só o caminho da pasta de ensaio foi encurtado. O tempo do pytest muda de máquina para máquina.
longrun/*/state.md na raiz do repositório git.Seis minutos com o conceito (10/10/2026). O conceito vale; dois detalhes mudaram depois: na faixa 3 e na 3ª compactação o agente termina a tarefa em curso antes da sessão nova (aula 3), e o cuidado com o cache hoje é o handoff automático aos 45 min parado (aula 4).
Na sua máquina. Só passe para o próximo quando o "pronto quando" for verdade.
Clone o kit em ~/projetos/execucao-longa e rode a suíte de testes dele.
Pronto quando: python3 -m pytest -q -p no:cacheprovider | tail -1 → 73 passed (num clone mais novo o número pode ser maior; nunca pode aparecer failed).
Escolha uma tarefa real de um projeto seu que leve mais de uma hora e crie a pasta dela. Rode o mesmo comando duas vezes.
Pronto quando: ls ~/projetos/[seu-projeto]/longrun/*/ | wc -l → 7; a segunda chamada imprime já existe: e echo $? → 1.
Cole o bloco de templates/AGENTS-long-run.md no ~/.claude/CLAUDE.md e no ~/.codex/AGENTS.md. Abra uma sessão nova e pergunte: "como você começa uma execução longa?" O bloco também cita /session-handoff, /prime e recall: eles só passam a existir nas aulas 5 e 7.
Pronto quando: grep -c novo-longrun.sh ~/.claude/CLAUDE.md → 1 ou mais, e a sessão nova responde citando novo-longrun.sh e critério nível 3 sem você lembrar.
Pergunta 1 de 4
Qual destes arquivos o agente deve REESCREVER a cada ciclo, em vez de só acrescentar?competência
Pergunta 2 de 4
O agente descobriu que o banco de teste só sobe com a variável DB_LOCAL=1. Onde isso vai?
Pergunta 3 de 4
Depois de uma compactação, qual é a primeira coisa que o agente faz?competência
Pergunta 4 de 4
Você rodou novo-longrun.sh com um slug que já existe hoje. O que acontece?
Escolha uma alternativa. A explicação aparece depois da sua tentativa.