Construção com gate — construção adversarial multiagente
Para trabalhos onde estar plausivelmente errado é caro. Um agente — por mais disciplinado que seja — não consegue detectar seus próprios erros de forma confiável: o ponto cego que produziu o bug é o mesmo que o revisa. A qualidade vem da independência: um segundo agente cujo trabalho é dizer NÃO-CONCORDO, questionando cada passo até que ele mereça uma aprovação explícita (APROVADO).
A economia: comprima tudo que os agentes leem (especificações, notas, prompts de revisão), para que você possa pagar por um segundo agente que discorde. A eficiência financia a redundância.
1. Definindo os papéis
Três papéis: Orquestrador (segura o documento âncora, define os outros, integra), Autor (redige código/design), Revisor (questiona até APROVADO). Definidos por tarefa, não por hábito:
| Autor | Revisor | Quando |
|---|---|---|
| Agente de fronteira (contexto total do repositório) | Agente de fronteira de fornecedor diferente | Construções de alto risco e pesadas em design — o padrão central |
| Agente CLI externo (ex.: Codex) | O próprio Orquestrador | Digitação mecânica em massa; o orquestrador tem o contexto + julgamento |
| Modelo local (classe Ollama) | Orquestrador | Redação de funções de baixo custo a partir de uma especificação enxuta |
| Subagente de nível barato | Agente de alto nível | Economia intra-família: mãos baratas, juiz caro |
Vínculos de execução — cada papel precisa de um transporte concreto em sua plataforma; use o que existe em vez de inventar infraestrutura:
- Autor com modelo local → a skill
rjv-ollama-delegate(executor integrado, regras de escrita de prompt, mandato de verificação). - Autor/Revisor CLI externo (classe Codex) → seu plugin de agente ou um subagente fino encaminhador Bash (ex.: o subagente de resgate Codex no Claude Code) — uma chamada de entrada, stdout de volta, modelo mais barato possível no encaminhador.
- Autor barato intra-família → spawn de subagente com o modelo definido explicitamente (veja §7).
Registre os papéis no plano. A definição de papéis acontece UMA VEZ, no início da construção, e é escrita na seção ## Papéis do plano âncora (veja rjv-feature-workflow): orquestrador, autor, revisor, tiers de subagentes, gates humanos — com modelos nomeados explicitamente. Cada retomada lê os Papéis e desempenha seu papel; o loop com gate nunca renegocia quem aprova. A redefinição de papéis é uma Decisão registrada com um motivo.
Duas regras rígidas de definição de papéis (baseadas em evidências, não flexibilizar):
- O revisor deve ser pelo menos tão forte quanto o autor. A força do revisor é de onde vem a qualidade; a força do autor é apenas velocidade de digitação. Um modelo fraco não revisa nada — testado: ao pedir para encontrar um bug real em código enviado para produção, um modelo local de 35B disse "nenhum bug encontrado".
- Prefira fornecedores diferentes para a revisão. Famílias de modelos diferentes erram em modos de falha diferentes; a revisão da mesma família herda os pontos cegos do autor.
O humano também é um revisor. Em uma execução real, o usuário detectou uma falha (latência do broker) que AMBOS os modelos de fronteira perderam ao longo de quatro rodadas de revisão. Apresente os projetos ao humano nos limites de fase; a experiência de domínio deles supera os prioris do modelo — quando a evidência ao vivo deles contradizer seu design, o design é atualizado imediatamente e registra isso.
2. Revise a ESPECIFICAÇÃO antes de qualquer código
A revisão de maior alavancagem acontece antes da implementação. No projeto de origem, o veredito da primeira rodada do revisor sobre o design foi "não construível como está" — 10 cenários de ataque classificados, 8 válidos. Corrigi-los antes do código custou a reescrita de um documento; depois do código, teria custado a construção.
- Envie a especificação/design para o revisor com: "ATAQUE este design. Liste cenários de falha classificados. Veredito: CONCORDO / NÃO-CONCORDO com bloqueadores."
- Itere especificação → ataque → corrija até CONCORDO. Registre cada rodada no documento âncora (v1 → v2 → v2.1 …), anotando quais objeções foram aceitas por mérito e quais foram rejeitadas com justificativas.
- Um revisor que nunca diz NÃO-CONCORDO não está revisando. Se toda rodada aprova instantaneamente, refine o prompt (veja §4) ou redefina os papéis.
3. O loop com gate (por etapa de implementação)
especificação → implementar → auto-revisão + teste rápido → REVISOR QUESTIONA → corrigir → questionar novamente … → APROVADO → commit → próximo
- Especificação primeiro. Escreva os critérios de aceitação da etapa no documento âncora ANTES de codificá-la. Avaliar a si mesmo contra uma especificação inventada durante o código é como bugs são abençoados.
- Auto-revisão + teste rápido descartável antes de passar para o revisor — pegue os bugs tolos de forma barata para que as rodadas do revisor sejam dedicadas aos sutis.
- Questione até um APROVADO explícito. Uma única ida e volta não é revisão.
- Estacione, nunca carimbe. Limite as rodadas de revisão por etapa (~6). Ainda bloqueado → escreva os bloqueadores abertos no documento âncora e PARE essa etapa. Um "estacionado deliberadamente, eis o porquê" é melhor do que uma aprovação falsa — inegociável quando dinheiro ou segurança estão em jogo.
- Plano vivo / retroações. Quando uma revisão invalida uma etapa ANTERIOR já aprovada: reabra-a, corrija, teste novamente, revise novamente, REGISTRE a retroação. Uma etapa errada e bloqueada é pior do que uma reaberta.
4. Direcionando o revisor — regras de prompt
- APENAS REVISÃO. Primeira linha: "APENAS REVISÃO — não modifique arquivos, não implemente." O revisor lê, raciocina, vota.
- Você executa os testes, não o revisor. Os sandboxes do revisor travam na execução. Execute a suíte você mesmo, cole os resultados no prompt ("suíte já executada: N passaram — revise lendo o código"). Ler arquivos é ok; executar não.
- Nomeie os modos de falha. Aponte para arquivos exatos, a seção da especificação e uma lista de caça numerada. Para código financeiro: dupla exposição, superavaliação, intenção perdida/duplicada em reinicializações, condições de corrida de ordenação, idempotência, taxas/precisão, o caminho arriscado específico que acabou de ser escrito. Prompts vagos geram revisões vagas.
- Limite cada revisão; cancele primeiro no timeout. Execute em segundo plano com um limite de tempo real (~12–15 min). No timeout: cancele o trabalho PRIMEIRO, verifique se nada está rodando, relance do zero. Mate processos órfãos. Limite relançamentos (~3); sem veredito persistente = falha de ferramenta → estacione, não finja.
5. O documento âncora (a memória real da construção)
Um documento de memória de trabalho comprimido por construção — e um repositório tem muitas construções. Não mantenha um único RESUME.md global: use o layout da skill rjv-feature-workflow (.plans/<nome>.md por trabalho, vinculado ao roadmap da funcionalidade), para que várias construções com gate possam estar em andamento e cada uma seja hidratada pelo nome. As seções abaixo vivem DENTRO desse arquivo de plano. A conversa é descartável; o documento âncora não é. "A especificação é o único artefato que ganha seus tokens" (cavekit).
Seções próprias — cada fase do loop escreve apenas na sua:
| Seção | Proprietário | Conteúdo |
|---|---|---|
| OBJETIVO | humano + orquestrador | um parágrafo, o ponto central, nunca esquecer |
| RESTRIÇÕES / VOCABULÁRIO | humano | palavras acordadas, palavras proibidas, limites duros |
| REGISTRO DE EVIDÊNCIAS | orquestrador | resultados vivos como restrições de design — ideias refutadas marcadas "não ressuscitar" |
| INVARIANTES | rodadas de revisão | regras de ferro que surgiram, cada uma rastreável a uma rodada ou a um cadáver |
| DESIGN vN | loop especificação-revisão | design atual + o rastro de revisão (v1 → v2 → …, quem objetou, o que foi aceito por mérito) |
| TAREFAS / PLANO | orquestrador | fases com critérios de aceitação; toda ideia ganha um LUGAR ou é descartada |
| BUGS / CADÁVERES | implementação | falhas estudadas no nível mais baixo, categorizadas |
| LÁPIDES | orquestrador | perguntas resolvidas mantidas visíveis "para ninguém reabri-las" |
| EM ABERTO | qualquer um | itens genuinamente não decididos, sinalizados USUÁRIO onde o humano deve decidir |
Regra de registro — comprima por audiência:
- Tudo que agentes leem (este documento, RESUME, prompts de revisão, memória): registro de homem das cavernas. Fatos, arquivo:linha, imperativos. "registrar ordem ANTES de enviar (sync fill drop → oversell)" — não em prosa. Escrito para um leitor sem contexto e com 10 segundos. ~75% mais barato em cada releitura, e releituras são o custo recorrente.
- Tudo que humanos leem (respostas, documentação voltada ao usuário): prosa normal, exemplos concretos com números. Falhas de compreensão custam mais do que tokens de saída.
- A divisão entre duas audiências é explícita: notas de agente são promovidas a documentos voltados ao usuário apenas quando concretas e acordadas.
A regra do "depois". Nunca arquive nada como "depois". Toda ideia ganha um lar em uma fase nomeada (com o porquê ali) ou é descartada. No projeto de origem, "depois" escondeu o experimento mais valioso — ele se tornou o PRIMEIRO item da construção uma vez trazido à tona. O único adiamento aceitável = uma dependência estrutural real, declarada.
Manutenção da compressão. O documento âncora e os arquivos de memória são relidos em cada retomada — eles são custo de ENTRADA recorrente, o tipo caro. Periodicamente (no final de uma fase, ou quando o documento incha) reescreva-os no registro: remova prosa, mantenha fatos. Regras de compressão: nunca toque em números, identificadores, referências arquivo:linha, código, comandos ou texto de erro (exato em bytes); nunca comprima o significado do REGISTRO DE EVIDÊNCIAS — uma nuance perdida ali reabre uma ideia refutada. Seções de design substituídas encolhem para lápides de uma linha; o rastro de revisão mantém apenas rodada + veredito + o que mudou.
6. Permanecendo vivo — a execução deve sobreviver a quedas
Dois modos de falha ACONTECERÃO em uma execução longa: o revisor trava, e sua própria conexão cai no meio de uma resposta. A defesa é a mesma: nunca mantenha estado apenas na conversa ao vivo.
- Ponteiro de retomada + reconciliação ao abrir. A seção Próximos Passos do documento âncora é reescrita no FINAL de cada etapa: etapa atual + status, próxima ação exata, arquivos de leitura obrigatória, regras rígidas. Em cada retomada — após compactação, após queda, despertar programado — a PRIMEIRA ação é o ritual de reconciliação do
rjv-feature-workflow: leia o plano → VERIFIQUE cada alegação de "concluído" contra o código/banco de dados real → anote deriva → reescreva Próximos Passos → carimbe "Última reconciliação" → então aja. Nunca confie em uma caixa de seleção desatualizada; uma queda pode ter perdido a edição que a caixa de seleção afirma. - Commit cedo e com frequência. Cada etapa aprovada faz commit imediatamente. Uma queda então perde no máximo a edição em andamento, não o trabalho de uma noite.
- Programe seus próprios despertadores. Ao passar o bastão para uma revisão limitada, programe um autodespertar (~15 min) para que você RETORNE ATIVAMENTE — observadores passivos do tipo "o trabalho me reativará" podem morrer silenciosamente.
- Passos idempotentes. Você pode reentrar no meio de um passo após uma queda; torne os efeitos colaterais seguros para repetir (chaves de desduplicação, upserts, verificações de já-feito).
7. Economia de modelo — não queime o modelo principal em tudo
Execuções longas travam no orçamento/limites de taxa antes de travarem na dificuldade. A conclusão depende de frugalidade:
- Barato por padrão. Modelo pequeno/rápido para subagentes mecânicos (o ENCAMINHADOR do revisor é uma chamada bash — vá para o mais barato; a qualidade da revisão é do modelo do REVISOR, não do encaminhador). Nível intermediário para código e análise de rotina.
- Modelos locais para funções implementáveis a partir de especificação — custo zero, e a partir de uma especificação enxuta eles atingem ~90% de qualidade de produção. Nunca como revisores (regra rígida 1). Veja a skill
rjv-ollama-delegate. - Reserve o modelo principal para design, síntese, julgamento final e a própria revisão.
- Defina o modelo EXPLICITAMENTE por subagente — nunca herde por padrão o pai caro.
8. Honestidade de escopo — especialmente para sistemas financeiros
Declare claramente o que "concluído" significa. "APROVADO pelo revisor até o passo N" ≠ "validado contra o mundo real" se a execução apenas percorreu um caminho simulado/em papel. Mantenha gates perigosos — negociação ao vivo, deploys em produção, operações destrutivas — fisicamente desligados até uma fase de validação separada e explícita com seu próprio gate (paridade de papel, bandas de taxa de preenchimento, limites de falha fechada). Nunca deixe "aprovado" significar "seguro para enviar".
Apêndice — quando o revisor é o OpenAI Codex CLI
Especificidades operacionais conquistadas a duras penas para direcionar o Codex como revisor:
- Cancele primeiro, nunca reconecte. Em um timeout de revisão, NÃO "reconecte para preservar seu trabalho" — a reconexão pode morrer instantânea e silenciosamente, deixando você sem vigilância enquanto o trabalho órfão roda por horas. Sempre: cancele o trabalho → verifique se nenhum está rodando → relance
--fresh. - pkill nos órfãos. Trabalhos cancelados/travados deixam processos
codex app-server,codex resumeeapp-server-brokerpara trás;pkill -9 -fneles durante a limpeza para que não se acumulem ao longo de uma execução longa. - O sandbox dele não pode executar seus testes (frequentemente sem diretório temporário gravável; ele trava "verificando" para sempre) — este é o PORQUÊ da regra de você-executa-os-testes da §4 existir. Ler arquivos (grep/sed/cat) dentro do sandbox dele é ok.
- Ele pode escrever arquivos, mas não executar git — faça o commit a partir da sessão do orquestrador após ele terminar.
- Os ids de sessão/thread da saída dele são retomáveis (
--resume-last/ retomar por id) — útil para revisões de acompanhamento que precisam do contexto da rodada anterior, sujeito à regra de cancelar-primeiro acima.
Invariante de uma linha: revisor independente + estado comprimido em disco + autodespertadores programados = uma execução que converge para o correto e sobrevive a toda trava, queda e compactação ao longo do caminho.
Proveniência: destilado de uma construção ao vivo de alto risco (bot de negociação de opções, julho de 2026: 6+ rodadas de revisão, NÃO-CONCORDOS reais, uma falha de design detectada por humano, perdas estudadas no nível de tick) e de um pico de delegação de modelo local verificado. Ideias de registro e seção de especificação creditadas à família caveman/cavekit (github.com/juliusbrussee).