Como criar uma indicação honesta de ETA para seu agente de programação

O primeiro artigo apresentou o problema de planejamento: espero, resolvo algo rápido ou começo outro assunto enquanto o agente trabalha? Este guia cria um pequeno registro local de quando a tarefa pode voltar a precisar da sua atenção.

O exemplo não prevê automaticamente a duração da tarefa. Você ou seu agente informa um estado e, quando há base para isso, uma faixa aproximada de tempo. A ideia é deixar essa informação legível e impedir que previsões antigas continuem parecendo confiáveis.

1. Rode um exemplo isolado

Você precisa de Python 3 no terminal do macOS ou Linux. Confira com python3 --version. Baixe e examine agent-eta.py, depois salve o arquivo em uma pasta temporária de trabalho. Execute os comandos abaixo a partir dessa pasta. Não é necessário instalar pacotes nem alterar as configurações do Claude Code.

Cada tarefa precisa do próprio arquivo JSON local. Não compartilhe o mesmo arquivo entre vários agentes. A pasta que vai recebê-lo precisa existir.

python3 agent-eta.py --file ./eta-demo.json write --state working --phase verification --min 5 --max 12
python3 agent-eta.py --file ./eta-demo.json show

No início, a saída será aproximadamente:

verification | WORKING | rough next-attention window 5-12m | declared, not calibrated

Cinco a doze minutos é um valor inventado para a demonstração. Não é benchmark, garantia nem evidência sobre sua tarefa real. A faixa indica quando sua atenção pode voltar a ser necessária, não quando uma solução pronta estará garantida.

2. Se o tempo é desconhecido, deixe isso claro

Quando não há uma base útil para estimar uma faixa, registre apenas o estado:

python3 agent-eta.py --file ./eta-demo.json write --state working --phase research

A indicação mostra next attention window unknown. A falta de estimativa não vira zero. Enquanto a faixa informada permanece válida, o renderizador desconta o tempo transcorrido. Quando o limite superior passa, ele mostra declared window expired; refresh needed em vez de manter um contador enganoso parado no zero.

3. Avise quando uma pessoa precisa agir

python3 agent-eta.py --file ./eta-demo.json write --state needs-input --phase implementation
python3 agent-eta.py --file ./eta-demo.json write --state waiting --phase external
python3 agent-eta.py --file ./eta-demo.json write --state ready --phase review

Execute estes exemplos separadamente para representar mudanças reais de estado. Não são uma sequência para rodar sem avaliar. INPUT NEEDED tem prioridade sobre qualquer faixa de tempo. READY FOR REVIEW não afirma que os testes passaram. Uma espera externa sem faixa informada continua com duração desconhecida.

O script não observa diálogos reais de permissão nem resultados de testes. O registro só é tão atual e correto quanto as informações de quem o escreve.

4. Inclua atualizações explícitas no fluxo

No primeiro teste, atualize o registro manualmente a cada mudança de fase. Se depois pedir ao agente para fazer isso, forneça o script aprovado e um arquivo separado. Exija atualizações antes de solicitar sua intervenção e ao encerrar o trabalho, e peça que omita faixas sem justificativa.

Isso é uma orientação de fluxo de trabalho, não uma integração automática com Claude Code já verificada. Uma adaptação para a linha de status nativa ou para hooks do ciclo de vida é outro trabalho. Uma chamada de show imprime um retrato do momento; não cria um painel ao vivo nem consulta nada em segundo plano. Você pode chamá-la quando for conferir a tarefa.

Observe se isso ajuda a escolher uma atividade adequada para o intervalo. Não interprete o número sozinho como autorização para se afastar: uma pergunta ainda pode surgir antes do esperado.

5. Teste os limites e remova o registro

A implementação foi testada com relógios e entradas sintéticos: arquivos ausentes ou inválidos, faixas desconhecidas ou vencidas, estados que exigem atenção, intervalos inválidos e mudanças no relógio. Registros com mais de 24 horas são marcados como desatualizados. Não foi estabelecida precisão de previsão para tarefas reais.

São armazenados apenas nomes fixos de estado e fase, o horário da atualização e a faixa informada. Não há chamadas de rede, captura de prompts nem arquivo histórico. O mesmo arquivo é sobrescrito a cada atualização e não é apagado automaticamente. Remova eta-demo.json pelo gerenciador de arquivos ao terminar o teste. Apagar o script e esse arquivo desfaz o exemplo; não há configurações do agente para restaurar.

Calibrar com base no histórico fica para depois, quando houver tarefas concluídas comparáveis. Até lá, uma faixa declarada com validade visível é mais útil que uma previsão de aparência exata, mas sem evidências.