Communitygithub.com

rjv-gated-build

Construção multiagente adversária com revisão independente para trabalho onde estar *plausivelmente errado* é caro.

O que é rjv-gated-build?

A skill **rjv-gated-build** implementa um processo de construção adversarial multiagente para tarefas de alto risco, onde erros podem ser muito custosos. Em vez de confiar em um único agente, que pode ter pontos cegos, a skill utiliza uma estrutura de três papéis: **Orquestrador** (gerencia o plano e integra), **Autor** (produz o código/design) e **Revisor** (analisa criticamente cada etapa, exigindo uma aprovação explícita `APPROVED`). A ideia central é que a qualidade vem da independência: um segundo agente (o revisor) tem a função de discordar (NO-AGREE) e só aprovar após um escrutínio completo. A skill é compatível com diversos ambientes, como Claude Code, Codex CLI, e modelos locais (Ollama), e oferece regras claras para orquestração econômica de agentes: o revisor deve ser tão forte (ou mais) quanto o autor, e é preferível que sejam de fornecedores diferentes (cross-vendor) para evitar herança de pontos cegos. O processo inclui um loop de revisão rigoroso (especificação → implementação → auto-revisão → revisão externa → correção → aprovação), um documento âncora que serve como memória persistente da construção (evitando perda de contexto em quedas de conexão), e estratégias de economia de modelo (usar modelos pequenos e locais para tarefas mecânicas e reservar o modelo principal para design, síntese e revisão). A skill também lida com falhas operacionais (timeouts, quedas) através de pontos de retomada, commits frequentes e passos idempotentes.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add rjvim/ai-skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

AutorRevisorQuando
Agente de fronteira (contexto total do repositório)Agente de fronteira de fornecedor diferenteConstruções de alto risco e pesadas em design — o padrão central
Agente CLI externo (ex.: Codex)O próprio OrquestradorDigitação mecânica em massa; o orquestrador tem o contexto + julgamento
Modelo local (classe Ollama)OrquestradorRedação de funções de baixo custo a partir de uma especificação enxuta
Subagente de nível baratoAgente de alto nívelEconomia 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):

  1. 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".
  2. 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çãoProprietárioConteúdo
OBJETIVOhumano + orquestradorum parágrafo, o ponto central, nunca esquecer
RESTRIÇÕES / VOCABULÁRIOhumanopalavras acordadas, palavras proibidas, limites duros
REGISTRO DE EVIDÊNCIASorquestradorresultados vivos como restrições de design — ideias refutadas marcadas "não ressuscitar"
INVARIANTESrodadas de revisãoregras de ferro que surgiram, cada uma rastreável a uma rodada ou a um cadáver
DESIGN vNloop especificação-revisãodesign atual + o rastro de revisão (v1 → v2 → …, quem objetou, o que foi aceito por mérito)
TAREFAS / PLANOorquestradorfases com critérios de aceitação; toda ideia ganha um LUGAR ou é descartada
BUGS / CADÁVERESimplementaçãofalhas estudadas no nível mais baixo, categorizadas
LÁPIDESorquestradorperguntas resolvidas mantidas visíveis "para ninguém reabri-las"
EM ABERTOqualquer umitens 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 resume e app-server-broker para trás; pkill -9 -f neles 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).

Habilidades Relacionadas