auto-dev — uma frota contínua que implementa e mescla issues

O que auto-dev — uma frota contínua que implementa e mescla issues faz?

O que isso faz

implement-issue transforma uma issue planejada em um PR pronto; merge-pr mescla um PR. O auto-dev os supervisiona em escala: N workers em segundo plano são donos de uma issue ponta a ponta (implement-issue <N> → merge-pr <PR>); no momento em que o PR de um worker é mesclado, o worker é aposentado e um novo worker é despachado para a próxima issue na fila — então N issues permanecem em andamento sem que você precise supervisionar.

O valor está na orquestração que um simples "executar em loop" não tem:

• Prevenção de conflitos — cada worker concorrente recebe uma issue em uma área de código diferente, então os branches raramente colidem.
• Ordenamento — issues pequenas e autocontidas primeiro (vitórias rápidas, menos conflitos), depois médias. Issues L/XL e de QA manual são excluídas por padrão.
• Mesclagem obrigatória — workers adoram parar em "PR pronto" (metade do trabalho). O auto-dev verifica o estado real de mesclagem no GitHub a cada sinal e redireciona qualquer worker que tenha travado.
• Captura de escopo fora — um worker que encontra um bug não relacionado o corrige inline apenas dentro da exceção do implement-issue (local a um arquivo que seu PR já modifica e pequeno, em seu próprio commit) e, caso contrário, o registra via create-issue, em vez de abandoná-lo, contra a barra de registro compartilhada (../_shared/filing-bar.md) para que uma frota de N workers não registre em N padrões diferentes. O backlog permanece fiel e drenável (#410).
• Higiene do ciclo de vida — agentes concluídos são desligados; um arquivo de estado sobrevive a reinicializações, então a frota é retomável.

Contrato de autonomia

O usuário inicia isso e se afasta — eles veem um backlog sendo drenado, não aprovam cada etapa. Execute hands-off: escolha o padrão razoável, declare-o, continue. Pare apenas para bloqueios genuínos:

• gh não está autenticado, ou você não tem direitos de push/merge.
• Nenhuma issue elegível (fila vazia após filtragem) — relate que o backlog foi drenado.
• Um bloqueio honesto e difícil de um worker (testes que não conseguem ficar verdes, um conflito onde ambos os lados reescreveram a mesma lógica, uma aprovação necessária que ele não pode dar a si mesmo). Exponha-o; não force uma mesclagem.

Nunca finja progresso: uma caixa de seleção, uma virada de "pronto" ou uma mesclagem afirma que o trabalho está feito — respalde cada um com evidências, conforme exigido pelas habilidades filhas. A squash-merge é o único ato irreversível — ela ocorre apenas através do merge-pr em um PR verde e mesclável, nunca através de uma substituição --admin aqui.

Entradas

• Concorrência N — workers ao mesmo tempo. Padrão: 3 (3–4 é o ponto ideal; mais = mais contenção e mais áreas para manter separadas).
• Ordenamento — esforço padrão pequeno→médio. Respeite o que o usuário disse.
• Conjunto elegível — padrão: issues abertas que (a) possuem um plano de implementação, (b) são tarefas de código (não "QA" manual / "verificar manualmente"), (c) estão dentro do teto de esforço (padrão ≤ médio). Respeite restrições ("apenas issues studio", "rotuladas priority: high").
• Heartbeat — normalmente lançado via loop em modo dinâmico, então o despertar auto-regulado do loop é o heartbeat. Se invocado diretamente, arme seu próprio despertar.
• Nível do modelo — padrão hierarquizado, não tudo-Opus (veja Economia de tokens): modelo mais barato e capaz para mecânica/documentação, intermediário para bugs típicos, topo reservado para trabalho transversal/difícil + escalonamento de falhas. A maior alavanca de custo. Respeite uma substituição ("tudo no Opus", "Sonnet para tudo").

Economia de tokens — execute a frota de forma barata

O custo de uma execução longa é ~83% leitura de cache de contexto por turno, ~16% saída — você paga por volume de contexto × turnos, não por pensamento. Aplique estas regras; raciocínio completo + medição em references/token-economics.md.

Medido em uma execução real de 19 mesclagens (um repositório .NET/Blazor, N=3, 21 sessões de worker, 863M tokens): 224 turnos/sessão · contexto 30K → 350K · contexto médio de 181K por turno · 0,55 chamadas de ferramenta por turno. Leitura de cache foi 98,3% dos tokens. Custo = Σ sobre turnos do tamanho do contexto, então turnos tardios custam ~10× os iniciais e a contagem de turnos é superlinear — ela impulsiona ambos os fatores ao mesmo tempo. Classifique as alavancas por isso, não por intuição.

Esse número principal conta sessões de worker — e o orquestrador foi um terço da conta. Dobrar a transcrição do supervisor no mesmo resumo: uma sessão, 551 mensagens de assistente, contexto médio de ~210K por mensagem, 33% do custo equivalente à lista da execução — mais do que todas as sessões de worker de alto nível combinadas — e ela nunca compactou uma vez em todas as 19 mesclagens. O gasto do worker é distorcido da mesma forma: as 3 principais de 37 sessões de worker foram 32% de todo o custo do worker, e a pior foi uma issue effort: medium no nível intermediário, então nem o rótulo nem o nível a previram. Ambas as medições, e os dois orçamentos contados que as limitam, estão em references/token-economics.md § Tamanho da sessão.

1. Divida cada worker em dois sub-agentes: implementar, depois mesclar — a única alavanca que funcionou de forma mensurável. Verificado A/B, ~11% de todos os tokens do worker. Fase 1 (/auto-dev-worker <N>) para em um PR pronto; fase 2 (/auto-dev-merge <PR>) o mescla em um contexto novo.

fase de mesclagem	turnos	ctx médio/turno	cacheRead
antes (18 workers, dentro da sessão de implementação)	27 méd	247K	6,6M por worker
depois (v2 fase 2, sessão nova)	24	71K	1,7M

Contagens de turnos quase idênticas, então o contexto por turno é toda a diferença: −74% na fase de mesclagem, ≈11% do gasto total do worker. Passe o número do PR entre as fases através de um arquivo que o prompt da fase 1 nomeia (recorra a analisar a linha do relatório, depois gh pr list --head). Bônus: ambas as cunhas pós-conclusão observadas na execução de base ocorreram nos turnos tardios de uma sessão longa — sessões mais curtas têm menos cunhas.

2. Agrupamento de chamadas de ferramenta — TENTADO E NÃO FUNCIONOU. Não espere ganho aqui. Uma regra de agrupamento rígida com exemplos foi adicionada ao prompt do worker e medida A/B: a densidade foi de 0,556 → 0,537 chamadas por turno (fase 1) — ou seja, nenhuma mudança. Mantenha a regra (não custa nada), mas não orce economias para ela. O diagnóstico: densidade abaixo de 1,0 não significa que chamadas que poderiam ser agrupadas não são. ~45% dos turnos não fazem nenhuma chamada de ferramenta — são turnos de raciocínio/narração — e a maioria do restante é genuinamente sequencial (editar → compilar → ler erro → corrigir). O desperdício recuperável são turnos que não produzem chamada de ferramenta, o que é um problema de verbosidade de saída, não um problema de agrupamento. Se você atacar isso, ataque a verbosidade (comprimento do pensamento, narração entre etapas) e meça chamadas/turno para verificar se você a moveu.

3. Mantenha a saída de comandos grandes fora do contexto — medido 4.262 tokens → ~2 por execução completa de teste. A saída completa de dotnet test tem ~17K caracteres e é relida a cada turno posterior. Determine: registre em um arquivo, coloque apenas EXIT + contagens no contexto, faça grep no arquivo apenas em caso de falha. Proíba explicitamente canalizar o comando através de tail/head — isso trunca a evidência enquanto ainda custa turnos. Escopo honesto: a redução por execução é exata e verificada, mas o ganho agregado depende de quantas vezes um worker executa o conjunto de testes. O maior resultado único do Bash caiu de 25,2K → 10,5K caracteres no A/B, enquanto o volume total de resultado de ferramenta por turno mal se moveu (722 → 710 caracteres) — porque a issue do A/B era uma tarefa de documentação que raramente executa testes. Espere o retorno real em issues com muitos testes.

4. Hierarquize o modelo para a tarefa — real, mas dependente do nível, conforme token-economics.md: fraco entre intermediário e pequeno ($0,419/Mtok vs $0,168/Mtok ≈ 2,5×); forte entre o topo e o intermediário ($2,376/Mtok vs $0,419/Mtok ≈ 5,7×). Vale a pena priorizar para trabalho transversal; menos impactante para bugs de rotina. Roteie por rótulos de issue (adapte os nomes ao trio pequeno/intermediário/topo do runtime, ex. Haiku/Sonnet/Opus):

Forma da issue (por rótulo)	Nível
docs/templates/manifest, regeneração de formato & snapshot, guardas de uma linha priority:low+effort:S	pequeno (ex. Haiku)
a maioria dos bugs: guardas de emitter/validator/parser, TS studio, CLI, LSP — effort:S/M; issues grandes por padrão	intermediário (ex. Sonnet)
um nível inferior falhou ao tornar esta issue verde	topo (ex. Opus), escalonamento reativo (uma vez)
transversal (várias áreas/emitters), ambíguo/design — trabalho que um mantenedor sabe ser difícil	topo (ex. Opus), último recurso preditivo

O orquestrador (você) permanece no modelo de topo, mas mantenha seu contexto por turno pequeno (alavanca 2).

5. Reduza o que é relido a cada turno.

• Apare o preâmbulo fixo — ele é pago em cada turno de cada worker. CLAUDE.md com 44KB (~11K tok) custou 52M tokens em uma execução de um único arquivo; mova material de referência de deploy/secrets/kubectl para documentos vinculados e deixe um ponteiro.
• Sem TaskList por issue — ela cresce ilimitadamente e se reinsere a cada turno. O arquivo de estado é sua única memória de trabalho.
• Compacte deliberadamente, em uma cadência contada — não por sensação. O inteiro da cadência tem um lar, references/token-economics.md § Os dois orçamentos; a Etapa 4 o dispara a partir do contador de mesclagem do arquivo de estado, o mesmo campo contado que a cadência de re-pesquisa já usa. Não reafirme o número aqui — tests/auto-dev-cost-budgets/test.sh falha na construção se você o fizer. Por que contado: o custo é Σ(contexto × turnos), então a cauda de uma execução é superlinear, e a regra que isso substitui — uma porcentagem /context ou uma cadência frouxa o suficiente para nunca ter disparado dentro de uma execução de 19 mesclagens — não limitou nada e custou $213 em uma única sessão. Sempre compacte com uma diretiva de foco, ex. /compact manter o mapa slot→issue/PR, contador de mesclagem, ordem da fila, acompanhamentos registrados. Primeira ação após qualquer compactação / /clear / novo disparo de loop: releia o arquivo de estado.
• Mantenha os RELATÓRIOS FINAIS do worker concisos — eles são relidos em cada turno de reconciliação posterior.
• Delegue leituras pesadas a sub-agentes Explore descartáveis — o despejo de arquivo morre com o sub-agente em vez de andar no seu contexto.
• Inicie a sessão do SUPERVISOR enxuta — sub-agentes herdam o conjunto MCP do supervisor, então todo servidor conectado à sua sessão anda em cada turno de cada worker. A remoção de MCP por worker não está mais disponível (a ferramenta Agent não tem configuração de MCP por spawn); corte-a uma vez, onde você inicia.

6. Faça menos turnos (cada ida e volta relê todo o contexto).

• Agrupe chamadas de ferramenta independentes em um turno (leituras/greps/gh paralelos).
• Deixe scripts colapsarem consulta+classificação — scripts/survey.sh, scripts/reconcile.sh.
• Não pesquise em uma cadência curta a menos que uma mesclagem seja iminente — um despertar desnecessário relê tudo, e um passado do TTL de cache de ~5 min paga uma escrita de cache completa (1,25×), não uma leitura (0,1×).
• Limite a sessão, não apenas o turno. O agrupamento foi testado A/B e não se moveu (alavanca 2), então a otimização por turno está quase esgotada e o tamanho da sessão é a variável que resta — as 3 principais de 37 sessões de worker foram 32% de todo o custo do worker, e nem o rótulo de esforço nem o nível previram quais três. Workers da Fase 1, portanto, carregam um orçamento de turnos (o inteiro vive em references/token-economics.md § Os dois orçamentos, não aqui) e passam o bastão nele com STATUS: PARCIAL; a Etapa 4 os retoma em um sub-agente novo, que é onde está a economia — uma retomada SendMessage mantém o contexto que o orçamento existe para descartar. Este é o mecanismo da alavanca 1, a única vitória verificada da seção, aplicada em uma costura de comprimento em vez de uma costura de fase.

Meça isso — nunca afirme que uma alavanca funciona sem um A/B. Três scripts, todos recebendo um diretório de transcrições de sessão .jsonl:

• scripts/usage_report.py — tokens + equivalente em $ por modelo. Acompanhe tokens/mesclagem e $/mesclagem. ⚠️ Ele agrega TODO o diretório do projeto, incluindo execuções passadas — crie um link simbólico de uma execução em um diretório temporário primeiro, mantendo o layout: o arquivo <sid>.jsonl da sessão do supervisor mais seu diretório <sid>/subagents/ (<proj>/<sid>/subagents/agent-*.jsonl é onde toda transcrição de worker vive, então a frota de uma execução fica sob um id — pegue o id do arquivo de estado ou dos carimbos de data/hora do gh; mtime não é confiável). Uma pilha plana de links simbólicos agent-*.jsonl é lida como "0 sub-agente" e não emparelha nada.
• scripts/analyze_cache.py — turnos/sessão, contexto no início vs pico, contexto médio por turno e volume de resultado de ferramenta por ferramenta. É aqui que você vê por que uma sessão é cara.
• scripts/measure_phase2.py — emparelha as transcrições de sub-agentes da fase 1 e fase 2 de cada issue (pelo ISSUE: de suas linhas de relatório) e divide o custo em fase de implementação vs fase de mesclagem; em uma transcrição pré-2.0, ele encontra o turno de passagem de bastão de mesclagem na sessão. Isso é o que provou a alavanca 1.

Duas métricas carregam a maior parte do sinal: contexto médio por turno (os turnos tardios estão inchados?) e chamadas de ferramenta por turno (os turnos estão fazendo algum trabalho? linha de base ~0,55 — veja a alavanca 2).

Como funciona

        ┌─────────────────────── auto-dev (você, o supervisor) ───────────────────────┐
        │  arquivo de estado: fila (pequeno→médio), slots em andamento, concluídos, registrados          │
        │  a cada sinal → reconciliar vs GitHub → finalizar-mesclados + reabastecer → manter N em execução  │
        └───────────────────────────────────────────────────────────────────────────────┘
            │ despachar (isolado por área)        ▲ relatório estruturado / notificação ociosa
            ▼                                     │
   Worker A ─ implement-issue → [pronto] ⇢ NOVO sub-agente ─ merge-pr → relatório ┐
   Worker B ─ implement-issue → merge-pr → relatório ─┤  N agentes em segundo plano, uma issue cada,
   Worker C ─ implement-issue → merge-pr → relatório ─┘  aposentados na mesclagem, substituídos da fila

Workers são sub-agentes em segundo plano gerados com a ferramenta Agent. Comunique-se através de seus relatórios estruturados — a mensagem final de um sub-agente é seu relatório, entregue a você quando ele retorna — através de notificações ociosas e por SendMessage para um ainda em execução; nunca leia seus arquivos de transcrição brutos (<proj>/<sua-sessão>/subagents/agent-*.jsonl) — a saída de um worker é um log enorme que explodirá seu contexto. Confie no relatório