O problema: prompt cresce, ninguém sabe mais o que está ativo
Todo assistente de IA interno começa do mesmo jeito: um arquivo de instruções que cresce a cada caso de borda descoberto. Alguém acha um comportamento errado, adiciona uma frase no prompt pedindo pra não fazer aquilo. Seis meses depois o arquivo tem duas mil linhas, ninguém sabe qual regra ainda vale, e regras novas contradizem regras antigas sem que nada avise.
O sintoma não é o agente "alucinando" — é o prompt virar uma pilha arqueológica de patches, sem precedência clara, sem forma de testar se uma mudança quebrou uma regra anterior, sem separação entre o que é sempre carregado e o que só deveria entrar em cenários específicos.
A resposta foi tratar o conjunto de instruções como um sistema versionado com schema, não como texto solto: um manifesto que declara ordem de precedência, políticas separadas por preocupação, árvore de decisão para roteamento de tarefa, checklists por tipo de entrega, e — a parte que fecha o ciclo — um validador que falha a build quando o sistema fica inconsistente.
Anatomia: carregamento progressivo, não tudo de uma vez
A decisão estrutural mais importante foi separar o que é sempre carregado do que é carregado sob demanda:
Core — poucas linhas, sempre presente: missão, ordem de instrução, princípios de operação ("inspecionar antes de assumir", "evidência é obrigatória para afirmação factual sobre o produto"). Orçamento de token explícito e pequeno.
Workflow — um por tipo de tarefa (responder pergunta de produto, investigar tecnicamente, documentar conhecimento, implementar mudança, corrigir bug, revisar mudança). Só o workflow da tarefa atual entra em contexto.
Playbook / rubrica / referência — carregado apenas quando o próprio workflow aponta pra ele. Nada entra "por garantia".
Isso resolve o problema raiz: cada peça tem um escopo de ativação declarado, então adicionar uma regra nova para o fluxo de revisão de código não infla o contexto de quem só está respondendo uma pergunta de produto.
O manifesto como fonte única de precedência
A ordem de instrução não fica implícita na posição de um parágrafo dentro de um arquivo gigante — fica explícita, em um campo de precedência: restrições rígidas primeiro, depois segurança e exigência de evidência, depois o pedido explícito do usuário, depois o workflow ativo, e só por último preferências e memória.
Essa ordem existe porque memória (contexto acumulado de sessões anteriores) é útil, mas não é fonte de verdade — o sistema trata memória explicitamente como contexto, nunca como evidência factual. Uma preferência lembrada de uma sessão passada não pode sobrescrever uma restrição de segurança da sessão atual. Sem essa hierarquia declarada, é exatamente esse tipo de conflito que fica resolvido de forma diferente a cada execução, dependendo de qual instrução "pesou mais" pro modelo daquela vez.
Roteamento por árvore de decisão, testado como código
Qual workflow carregar para uma tarefa não é decidido por um prompt tipo "identifique a intenção do usuário e escolha o fluxo apropriado" — é uma árvore de decisão explícita, com gatilhos por palavra/frase em dois idiomas, mapeando pra um workflow entre seis possíveis (responder pergunta de produto, investigação técnica, documentar, implementar, corrigir bug, revisar mudança). Roteamento de modelo e de ferramenta seguem o mesmo formato: condição → escolha, não prosa condicional.
O motivo de tratar isso como árvore e não como instrução em linguagem natural: uma árvore se testa com um benchmark de casos positivos, negativos e ambíguos. O time chegou a 95 casos cobrindo pares de confusão explícitos (por exemplo, "corrigir bug" vs "implementar mudança" — duas intenções que se parecem até alguém escrever os dois exemplos lado a lado e perceber a fronteira real) e 100% de acerto — partindo de uma base de 80 casos com quase 99%. Cada erro de roteamento encontrado nesse processo virou um caso novo no benchmark, não um ajuste de prompt sem registro.
O validador que trava build: RED também serve para arquitetura de agente
A peça que fecha o ciclo é um validador que roda contra o manifesto e falha explicitamente quando o sistema de agente fica inconsistente. Alguns exemplos do que ele pega:
Um workflow referenciando uma ferramenta que a política de segurança não permite naquele estado.
Uma transição apontando para um estado que não existe.
Um checklist ou política referenciado no manifesto que não existe no disco.
Orçamento de token excedido — o core tem um teto de ~800 tokens, cada workflow um teto de ~600, e o validador falha se qualquer um passar.
Drift entre o manifesto e os arquivos gerados a partir dele (variações de instruções específicas de cada ferramenta de IA, geradas automaticamente a partir da mesma fonte) — se alguém edita o arquivo gerado direto, sem passar pela fonte, o validador pega a divergência.
Ordem de precedência alterada de um jeito que não bate mais com a hierarquia obrigatória.
Cada uma dessas checagens nasceu de uma mutação proposital: o time pega o manifesto válido, aplica uma mutação específica (por exemplo, "remove a rubrica de objetividade"), e escreve o teste esperando a mensagem de erro exata que o validador deveria produzir. Isso é o mesmo espírito do ciclo TDD que trata código morto como "RED": aqui, o RED prova que o sistema recusa um estado inválido, não que uma feature nova funciona. Cobertura negativa cresceu de 8 para 21 casos assim, um por tipo de inconsistência que já foi imaginado — ou já aconteceu.
Confiança como campo de primeira classe, não em prosa
Uma política curta define os três níveis de confiança (alta: evidência direta valida a afirmação sem conflito crítico; média: evidência parcial ou indireta; baixa: sem evidência direta, ou resposta baseada só em memória) e uma regra que parece pequena mas evita um comportamento clássico de agente mal calibrado: confiança pode cair durante validação, nunca pode subir sem evidência mais forte. Ou seja, o modelo não pode "se convencer" de uma resposta ao longo da conversa — só pode ficar mais seguro se uma evidência nova e mais forte aparecer.
O que isso muda na prática
Nenhuma dessas peças, isoladamente, é surpreendente — árvore de decisão, checklist, orçamento de token, teste de mutação, tudo isso já existe em outros contextos de engenharia. O que muda é aplicar essa disciplina ao próprio sistema de instruções do agente, tratando-o como um artefato versionado com testes, não como um prompt que "só cresce".
O ganho concreto: quando alguém propõe uma regra nova, a pergunta não é mais "onde eu colo essa frase no prompt gigante" — é "isso é uma restrição, uma política, um workflow novo ou um caso de benchmark", e cada resposta tem um lugar certo, testável, com precedência já resolvida antes de qualquer execução real do agente.
Resumindo
Prompt monolítico que só cresce não escala — precedência fica implícita e ninguém consegue testar regressão.
A solução foi modelar o sistema de instruções com carregamento progressivo (core sempre, workflow por tarefa, playbook só sob demanda) e um manifesto único de precedência.
Roteamento de tarefa é árvore de decisão testável, não prosa — benchmark de casos positivos/negativos/ambíguos mede acerto real.
Um validador de mutação trata "isto não deveria ser um estado válido" como um teste RED, incluindo drift entre manifesto e arquivos gerados.
Confiança é campo estruturado com uma regra de uma via só: pode cair, nunca sobe sem evidência mais forte.
O que fica
O ponto comum entre um manifesto de agente e qualquer outro sistema de software não é a analogia bonita — é que os dois quebram do mesmo jeito quando ninguém trata as regras como algo testável. Um prompt que só cresce e um codebase sem teste de regressão falham pela mesma razão: mudança nova não sabe se contradiz decisão antiga até alguém descobrir em produção.
Tratar instrução de agente como sistema não é sobre desconfiar do modelo — é sobre parar de confiar na memória de quem escreveu a última frase do prompt pra saber se ela ainda é compatível com as duzentas anteriores. Um manifesto com precedência declarada e um validador que falha em mutação não deixam o agente mais inteligente; deixam o sistema em volta dele honesto sobre o que está, de fato, ativo.
Top comments (1)
Bookmarked. The part about evaluation being mandatory is exactly what I keep missing in my own experiments. How do you measure regressions, a separate test set?