O Playbook

Como construir software com agentes de IA — e manter o controle.

Este é o manual operacional do método H1VE. O manifesto diz o que valorizamos; os princípios dizem como agimos; este playbook diz exatamente como fazer o trabalho — papel por papel, gate por gate.

Versão: 1.0
Público: Quem lidera ou entra num time assistido por IA.

Introdução

A IA tornou gerar código quase gratuito. O custo não sumiu — ele se moveu. O código agora chega mais rápido do que qualquer time consegue ler, revisar e confiar nele, e é nessa lacuna que o risco se acumula.

O H1VE fecha a lacuna colocando o julgamento humano nos pontos que importam. Humanos e Agentes de IA · 1 Time — os agentes produzem, os humanos decidem, e toda decisão deixa um rastro.

Quando usar o H1VE

Vários desenvolvedores trabalham em paralelo, cada um com um agente de IA
Um bug silencioso em produção é caro
Alguém precisa responder “quem decidiu isso, e por quê?”
O time está escalando e a coordenação improvisada está quebrando

Quando não usar

Um protótipo descartável de uma pessoa que ninguém vai manter
Um script pontual sem necessidade de review
Um time que não usa agentes de IA

A ideia central

A IA propõe; o humano decide. Todo gate deste playbook é um lugar onde essa decisão fica explícita e sob a responsabilidade de uma pessoa.

Os papéis

O H1VE define cinco papéis humanos que a IA assiste mas nunca ocupa. Num time pequeno uma pessoa pode acumular vários chapéus — mas as responsabilidades nunca se fundem. Um revisor nunca valida sozinho o próprio trabalho.

Founder

Dono do porquê

Define visão, escopo e prioridades. Cria e atribui features, aprova specs e acompanha a saúde do sistema.

Pode: Aprovar specs, definir o appetite, criar features, ver tudo.
Não pode: Fazer merge na main, ou assinar como QA/Data na própria feature.

Arquiteto

Dono do como

Dono da fundação técnica e do merge final. Revisa o quadro completo antes de o código chegar à main.

Pode: Aprovar specs e DONEs, revisar e fazer merge na main — exclusivamente.
Não pode: Pular os gates ou fazer merge sem CI verde e os dois sign-offs.

Dev

Constrói com o agente

Transforma uma spec aprovada em código com a IA, só dentro do escopo, e move o trabalho para PR com uma AI declaration honesta.

Pode: Construir suas features, mover dev → PR, registrar blockers.
Não pode: Codar sem uma spec aprovada, ou fazer merge do próprio trabalho.

Valida que funciona

Confere de forma independente que a feature faz o que a spec diz. Uma metade do gate duplo.

Pode: Assinar (ou rejeitar) features em qa_data no critério funcional.
Não pode: Validar uma feature que ele mesmo construiu.

Data

Valida a integridade

Confere de forma independente a solidez do schema e a integridade dos dados. A outra metade do gate duplo.

Pode: Assinar (ou rejeitar) features em qa_data no critério de dados.
Não pode: Validar uma feature que ele mesmo construiu.

Humanos e agentes

O agente rascunha, gera e propõe em todos os papéis. Mas a assinatura — a aprovação, o sign-off, o merge — é sempre humana.

O ciclo de trabalho

O trabalho flui por uma sequência definida. Nada pula etapa, e o quadro mostra onde tudo está em tempo real. O ciclo tem duas partes: uma fundação única e, depois, um loop de feature que se repete.

A fundação (uma vez, no início)

Antes da primeira linha de código, o projeto precisa existir no papel. O founder e o arquiteto, assistidos pela IA, produzem quatro documentos: visão & escopo, especificação funcional, especificação técnica e o roadmap. Eles são o bolo; toda spec seguinte é uma fatia.

Por que isso importa

Pular a fundação é a falha mais comum. O time coda rápido mas sem um norte comum — a IA inventa decisões, dois devs se contradizem. A fundação custa dias e economiza semanas.

O loop de feature (repete por fatia)

Cada feature passa por nove estágios, e pode ser estacionada como bloqueada a partir de qualquer um deles.

Backlog
Spec
Dev + IA
Pull Request
CI
QA + Data
Arquiteto
Main

Backlog → Spec — Uma feature nasce, depois é definida. Nenhum código é escrito até um humano aprovar a spec.
Spec → Dev + IA — O dev constrói com o agente, estritamente dentro do escopo aprovado.
Dev + IA → Pull Request — O trabalho é submetido com uma AI declaration honesta do que o agente gerou.
Pull Request → CI — A máquina confere a mecânica — tipos, lint, testes.
CI → QA + Data — Dois humanos independentes validam dois tipos de risco; ambos precisam assinar.
QA + Data → Arquiteto — Com os dois sign-offs, a feature vai para o gate humano final.
Arquiteto → Main — O arquiteto revisa o quadro completo e faz o merge — o único que pode.
Qualquer estágio → bloqueada — Uma feature pode ser estacionada como bloqueada a partir de qualquer estágio, com o motivo registrado, sem quebrar o fluxo.

Uma nota sobre ownership

Uma feature pode ficar no backlog sem dono, mas não entra em desenvolvimento sem um. Atribuir um dono é pré-condição para o trabalho — controle por design.

Os artefatos

O H1VE roda sobre um pequeno conjunto de documentos vivos. Cada um tem uma função, um momento e um dono.

Os documentos de fundação

Visão & Escopo: Por que o produto existe, para quem e seus limites. Liderado pelo founder.
Especificação Funcional: O que o produto faz, na visão do usuário. Founder + arquiteto.
Especificação Técnica: Como é construído: stack, modelo de dados, APIs, decisões. Liderado pelo arquiteto.
Roadmap: O escopo fatiado em fases. Cada item vira uma spec. Um documento vivo.

Os documentos por feature

SPEC-NNN: Criada e aprovada antes de qualquer código. Define escopo, arquivos tocados, critérios de aceite, riscos.
DONE-NNN: Criado ao final, antes do PR. O que mudou, como testar, a AI declaration.

O documento de memória

CLAUDE.md: A memória viva do projeto: stack, regras inegociáveis, arquivos críticos, estado atual. Lido antes de cada sessão, atualizado depois.

A AI declaration

Todo PR registra quais arquivos a IA gerou e quanto cada um foi revisado. Não é burocracia — diz ao revisor onde focar e torna o sistema inteiro auditável.

Os gates

Os gates são onde o julgamento humano entra e onde a qualidade é imposta, não apenas esperada. São três, em sequência.

Gate 1

CI — automatizado

A máquina confere a máquina: checagem de tipos, lint, a suíte de testes. Objetivo e rápido. Uma falha devolve a feature para o dev. Necessário, mas não suficiente — pega o que está mecanicamente errado, não o que está errado no julgamento.

Gate 2

QA e Data — o gate duplo

A assinatura do H1VE. Dois humanos independentes, validando dois tipos de risco, nenhum deles quem escreveu o código. A feature só avança quando ambos assinam — então move para o arquiteto automaticamente.

QA pergunta: faz o que a spec diz?
Data pergunta: o schema é sólido?

Por que dois gates, não um

A IA falha de um jeito na lógica e de outro nos dados. O código pode estar funcionalmente correto e ainda assim corromper o schema em silêncio. Um revisor perde um dos dois; dois gates independentes pegam os dois.

Gate 3

O arquiteto — o merge

O gate humano final. O arquiteto revisa o quadro completo — CI verde, os dois sign-offs, o DONE escrito — e faz o merge na main. Essa autoridade é exclusiva. A IA nunca faz merge.

As métricas

O H1VE mede a saúde do sistema, não a ocupação das pessoas.

Taxa de aprovação do CI: Fração das execuções de CI que passam. Abaixo de ~80% sinaliza problema sistêmico — pare de adicionar features até saber por quê.
Tempo de ciclo: Quanto uma feature leva da spec à main. Subindo, há um gargalo — muitas vezes a fila do arquiteto.
Saúde dos gates: Com que frequência features são rejeitadas no QA ou no Data, e por quê. Um padrão aponta specs fracas ou erros da IA passando.
Idade dos blockers: Há quanto tempo os blockers ficam abertos. Mais que alguns dias pede intervenção direta.
Fila do arquiteto: Features esperando o gate final. Uma fila crescente significa que o gargalo é o merge.

Meça o sistema

Elas descrevem o fluxo, não as pessoas. Velocidade que esconde um gate quebrado é pior que lentidão que mantém a qualidade.

Anti-padrões

Saber o que evitar é tão valioso quanto saber o que fazer. Estes são os modos de falha que o H1VE existe para prevenir.

Anti-padrão

Codar sem uma spec

“É uma mudança pequena, eu faço rapidinho.” É assim que as features incham e o review perde a âncora: mudanças pequenas sem escopo.

Faça em vez disso: Sem código sem uma spec aprovada — por menor que seja a fatia.

Anti-padrão

Deixar a IA fazer merge

O agente é rápido e confiante, então é tentador deixá-lo fechar o loop de ponta a ponta.

Faça em vez disso: O merge é exclusivamente humano. A IA propõe; o arquiteto faz o merge.

Anti-padrão

Pular a fundação

Ir direto para as features parece produtivo, mas deixa o time sem um norte comum.

Faça em vez disso: Escreva os quatro documentos de fundação primeiro. A fundação é feita uma vez.

Anti-padrão

Um revisor para tudo

Uma única pessoa aprovando spec, código e dados colapsa a independência de que os gates dependem.

Faça em vez disso: Mantenha QA e Data independentes — e nunca quem fez o trabalho.

Anti-padrão

Confiar numa AI declaration em branco

Uma declaration vazia ou vaga esconde onde o risco realmente está.

Faça em vez disso: Exija uma AI declaration honesta, por arquivo, em todo PR.

Anti-padrão

Velocidade como única métrica

Otimizar só por velocidade recompensa pular gates e acumula dívida silenciosa.

Faça em vez disso: Meça a saúde do sistema — taxa de aprovação, saúde dos gates, idade dos blockers — não só a vazão.

Glossário

O vocabulário comum do H1VE. Uma língua comum é o que transforma uma prática em profissão.

Gate: Um checkpoint onde o trabalho precisa ser validado antes de avançar. O H1VE tem três: CI, o gate duplo QA+Data, e o merge do arquiteto.
Gate duplo: O mecanismo que define o método: QA e Data validando de forma independente, ambos obrigatórios para avançar.
Spec (SPEC-NNN): A definição aprovada de uma unidade de trabalho, escrita e aprovada antes de qualquer código.
Done (DONE-NNN): O registro de fechamento de uma feature: o que mudou, como testar, o que a IA gerou.
AI declaration: O registro, por PR, de quais arquivos foram gerados pela IA e quanto cada um foi revisado.
Appetite: O tempo que um time aceita gastar numa feature. O escopo se ajusta ao appetite, não o contrário.
Swim lane: O quadro visual de nove estágios mostrando onde cada feature está em tempo real.
Stage: Uma posição no ciclo: backlog, spec, dev, PR, CI, QA+Data, arquiteto, main ou bloqueado.
Fundação: Os quatro documentos que definem um projeto antes da primeira spec.
CLAUDE.md: A memória viva de um projeto, lida antes de cada sessão e atualizada depois.
Implementação de referência: Uma ferramenta que implementa o método H1VE. O método é neutro em relação à ferramenta; uma implementação o torna operável.

O Playbook H1VE · v1.0 · H1VE.org