A fábrica Qirava: papéis, skills e portões de maturidade (G0 a G3)

Como se organiza uma fábrica de agentes governados? Com três peças: cada agente entra por um papel, esse papel carrega um pacote de skills, e o trabalho só avança quando cruza um portão de maturidade. Fora disso não há magia nem improviso. Há uma linha de produção com postos, ferramentas e controles de qualidade, como qualquer fábrica séria.

Durante um tempo fizemos o que quase todo mundo faz: pedir à IA "vamos ver no que dá". Isso tem nome, chama-se vibe coding, e funciona até você precisar repetir o resultado, auditá-lo ou colocar vários agentes trabalhando juntos sem se atropelarem. É aí que desaba. A fábrica Qirava nasceu para substituir esse improviso por um método: primeiro a especificação, depois a execução.

01 · a plantaPrimeiro a spec, depois o agente

O método se chama SDD, Spec-Driven Development, desenvolvimento guiado por especificação. A regra é simples e não admite atalhos: antes de um agente tocar em qualquer coisa, existe uma spec que diz o que precisa ser feito, com quais critérios se considera pronto e quais limites não se cruzam. A spec não é documentação escrita depois. É a planta escrita antes, e é quem governa o agente.

Isso não é uma mania nossa. A Amazon trabalha há mais de vinte anos "de trás para frente" (working backwards): antes de construir um produto, escrevem o comunicado de imprensa e o FAQ como se ele já existisse, e só se esse documento convence é que se executa [1]. A comunidade de engenharia com IA chegou ao mesmo lugar por outro caminho: ferramentas como o GitHub Spec Kit formalizam que a especificação, não o prompt improvisado, seja a fonte de onde sai o código [2].

Um prompt improvisado produz uma surpresa. Uma spec produz um resultado que você pode repetir.

02 · os postosCada papel carrega seu pacote de skills

Numa fábrica ninguém faz de tudo. Há postos. Na fábrica Qirava, cada agente entra por um papel, e esse papel define o que ele sabe fazer e o que não pode tocar. Faz isso carregando um pacote de skills com quatro camadas: uma skill universal que todos compartilham (a governança comum, qirava-llm-governance), uma skill primária própria do papel, skills secundárias de apoio, e uma lista de skills proibidas que esse papel não pode invocar nem que queira.

Essa última camada é a que quase ninguém coloca e a que mais protege. Não basta dizer a um agente o que ele pode fazer; é preciso dizer o que lhe é vetado. O agente de marketing não faz deploy de código. O de QA não aprova o próprio release. O limite faz parte do desenho, não é uma correção posterior.

Você não define um agente pelo que ele pode fazer. Você o define pelo que lhe proíbe.

Há um detalhe que sustenta tudo isso: a fonte documental de verdade é um DOCUMENT_INDEX, um índice único. As skills vivem num toolkit, a governança vive num vault, e os agentes os consomem por symlink em vez de copiar. Assim, quando uma regra muda, ela muda num único lugar e todos os agentes a herdam. Não há dez versões da governança flutuando por aí.

03 · os controlesPortões de maturidade: nada avança sem cruzar o seu

Ter papéis e skills não basta. Falta o controle de qualidade, e é aqui que a fábrica se torna fábrica de verdade. Tudo o que um agente produz atravessa quatro portões de maturidade, e não passa ao seguinte sem cumprir o anterior:

G0, especificada. Existe a spec. Sem planta nada arranca. G1, rascunho. O agente produziu uma proposta e passou pela validação básica. G2, operacional. O CEO aprovou: só aqui o trabalho pode tocar a realidade. G3, conselho. O que já opera e merece ser elevado a decisão de conselho. Cada salto é um portão com um dono, e o mais importante, G2, é aprovado por uma pessoa.

Aqui está o princípio que evita o desastre mais comum com agentes: os rascunhos deliberam, mas não simulam execução. Deliberar é propor, avaliar e decidir. Executar é fazer a mudança real. Um agente em G1 pode argumentar até cansar por que deveria fazer deploy de algo, mas não faz deploy de nada. Essa linha, entre pensar em voz alta e agir, é o que separa uma fábrica governada de um enxame de bots fazendo coisas que ninguém autorizou.

04 · o fechamento do laçoQA que certifica, não que aprova na marra

Falta o último controle, aquele que muitas equipes maquiam: a qualidade. Na fábrica Qirava, o QA é um laço com regressão profissional que roda até certificar. A diferença em relação à prática comum é brutal. Não se retesta só o suficiente para passar; testa-se a sério, e se algo falha volta ao laço. Certificar não é "já não achei erros procurando pouco". É "isto aguenta a regressão completa".

Essa disciplina existe fora de nós: o próprio ciclo de trabalho ágil separa a construção da validação justamente para que quem testa não seja quem tem pressa de entregar [3]. Numa fábrica de agentes, onde é tentador deixar um modelo "se aprovar sozinho", essa separação é a única defesa real.

Junte as quatro peças e você tem a fábrica: uma spec que governa (G0), agentes que nascem sob governança com seu pacote de skills, portões que ninguém pula (G1 a G3), e um QA que certifica de verdade. Cada agente delibera dentro do seu papel, propõe dentro da sua spec, e só executa quando uma pessoa abriu o portão. Não é burocracia: é o que faz o trabalho de dez agentes ser confiável em vez de ser dez surpresas.

Da próxima vez que você vir alguém pedir à IA "vamos ver no que dá", lembre-se de que isso não é uma fábrica. É uma oficina de uma pessoa só, com sorte. Uma fábrica tem plantas, postos e controles. E na da Qirava, nenhum agente cruza um portão que não lhe cabe.