Um fluxo noturno para agentes de código

Escreva as tarefas como faria para um prestador novo

Uma tarefa noturna não tem a quem perguntar. Ela precisa levar o próprio contexto. Cada tarefa deve caber em um parágrafo e responder três perguntas. O que está errado ou faltando. Como é o pronto. Como provar.

## Task: paginate the /orders endpoint
Problem: GET /orders returns every order. Large accounts time out.
Done: accepts ?cursor and ?limit (max 100), returns next_cursor.
Proof: new tests in tests/orders_pagination.test.ts pass; existing tests pass.
Do not: change the response shape of existing fields.

Mantenha as tarefas pequenas. Duas a quatro horas de trabalho humano é o tamanho ideal. Maior do que isso, divida. Uma tarefa que o agente termina em vinte minutos também serve. Coloque as tarefas em um arquivo no repositório ou em issues que o agente consiga ler. Um arquivo é o mais simples.

Uma tarefa, uma branch, um worktree

As tarefas não podem compartilhar uma árvore de trabalho. Duas tarefas editando a mesma cópia geram um diff que ninguém consegue desembaraçar. Os worktrees do Git dão a cada tarefa a sua própria pasta no mesmo repositório.

git worktree add ../work/orders-pagination -b agent/orders-pagination
git worktree add ../work/retry-webhooks -b agent/retry-webhooks

Cada branch tem a sua própria execução do agente e o seu próprio pull request. De manhã você revisa um por vez. Se um estiver ruim, você fecha e os outros ficam intactos.

Decida o que o agente faz sozinho

Defina o modo de permissão e a lista de negação antes da primeira execução, não depois. O guia para rodar o Claude Code sem supervisão tem os ajustes exatos. A versão curta para o trabalho noturno é esta. Editar arquivos à vontade. Rodar a suíte de testes à vontade. Fazer commit e push da branch da tarefa à vontade. Abrir um pull request. Nada mais sem perguntar, e nada que saia do repositório.

O loop de execução

Um script pequeno inicia uma execução headless por tarefa, no worktree dela, com um teto de turnos e um arquivo de log. É só isto.

#!/bin/sh
# run-overnight.sh: one agent run per task file in tasks/
for task in tasks/*.md; do
  name=$(basename "$task" .md)
  dir="../work/$name"
  git worktree add "$dir" -b "agent/$name" 2>/dev/null
  (
    cd "$dir" || exit 1
    claude -p "Complete the task in $task. Commit on this branch, push it, and open a pull request with gh pr create. Stop when the tests pass or when you are blocked, and say which." \
      --permission-mode acceptEdits \
      --max-turns 80 \
      > "../logs/$name.log" 2>&1
  )
done

Rode dentro do tmux para que a conexão SSH não importe. As tarefas rodam uma depois da outra. Execuções em paralelo são possíveis, mas disputam CPU e o seu limite de uso, e deixam os logs mais difíceis de ler. Comece em sequência.

Deixe os testes serem o juiz

O prompt manda o agente parar quando os testes passarem. Depois, o seu CI roda os mesmos testes no pull request. Se o agente disse verde e o CI diz vermelho, você sabe antes de ler uma linha do diff. Proteja a main para que nada entre sem essa verificação. Esta é a proteção mais valiosa do fluxo e não custa nada.

A revisão da manhã, em dez minutos

• Abra a lista de pull requests. Compare com a lista de tarefas. Os que faltam estão nos logs.
• Leia o log de tudo que parou como bloqueado. Normalmente é uma credencial faltando ou uma tarefa ambígua. Corrija o texto da tarefa, não o agente.
• Revise os pull requests verdes do menor para o maior. Faça merge dos que estão certos. Feche os errados com uma linha dizendo por quê, e copie essa linha para o arquivo de tarefas de amanhã.
• Apague os worktrees e as branches que já entraram, para que a noite de hoje comece limpa.

git worktree remove ../work/orders-pagination
git branch -d agent/orders-pagination

O que entregar primeiro

Alguns trabalhos combinam mais com a noite do que outros. Comece por estes e amplie conforme a confiança cresce.

• Testes que falham ou são instáveis, com um comportamento esperado claro.
• Atualizações de dependências em que a suíte de testes é o juiz.
• Refatorações mecânicas em muitos arquivos.
• Testes que faltam para código que já funciona.
• Erros de tipo, erros de lint e avisos de descontinuação.

Deixe para o dia as decisões de design, tudo que mexe com cobrança ou autenticação e tudo que os testes não conseguem verificar. De dia você pode responder perguntas.

A máquina por baixo

Tudo isso supõe uma máquina que ainda está rodando às 4 da manhã. Um notebook que entra em repouso é o motivo mais comum para uma execução noturna não produzir nada. O guia sobre repouso resolve isso em um Mac seu, e um Mac para agentes hospedado já vem com isso resolvido.