Artigo Técnico · Engenharia Agêntica ✦ PROPOSED
Deterministic Grounding para Engenharia Agentic de Software
Um agente de IA pode passar em todos os testes e ainda entregar a mudança errada. Este artigo mostra por quê e propõe um caminho para reduzir esse risco.
O agente trabalha com o que acredita saber do repositório: contexto recuperado, memória, um plano. Se essa informação já não vale mais, o código pode estar correto isolado e errado para o projeto de hoje, violando a arquitetura, o escopo autorizado ou a privacidade.
Deterministic Grounding é o nome provisório que este artigo propõe (não é terminologia padronizada) para uma prática em três partes: ancorar o que o agente sabe num estado verificável do repositório, limitar o que ele tem permissão de fazer e validar cada mudança com evidência registrada. Os mecanismos descritos são propostas, ainda sem medição de eficácia; veja as limitações na Cena 09.
O que o agente acredita
Pedido: "Adicionar rota de exportação em PDF"
Contexto recuperado: índice do commit C1
Suposição: a dependência 'pdf-kit' v1.2 está no projeto
Plano: editar src/api/export.js e package.json
O que o repositório tem agora
Snapshot: commit C2 (o mais recente)
Lockfile: 'pdf-kit' foi removido em C2
Regra: src/api/ restrita pela ADR-014 (registro de decisão de arquitetura)
Resultado: a mudança feita sobre C1 conflita com C2
É como abrir um Pull Request (pedido de revisão de código) a partir de uma cópia do projeto feita uma semana atrás: sozinho, o código está correto; contra o que o time mudou desde então, já nasce quebrado.
Os selos coloridos ao lado dos títulos indicam o grau de certeza de cada trecho: OBSERVED (observado), ESTABLISHED (estabelecido), DOCUMENTED (documentado), PROPOSED (proposta) e INFERENCE (inferência).
- Formato
- Artigo
- Profundidade
- Leitura aprofundada · ~7 min para a ideia central · ~19 min completo
Prefere o essencial antes? Ler a síntese (~1 min)
Cena 01 · O Agent–Repository Gap
Cinco fontes de verdade, cada uma com autoridade limitada
O erro do exemplo acima nasce de tratar informações de origens diferentes como se fossem um contexto só. Cada fonte só pode afirmar certas coisas, e nenhuma pode falar no lugar da outra. Clique em cada cartão para ver o que ela autoriza afirmar e o que não autoriza.
Current State
Autoridade: O repositório e o ambiente de execução, do jeito que estão agora
✓ O que autoriza afirmar:
- Dizer qual é o commit atual, quais arquivos existem e quais dependências estão instaladas.
- Dizer quais arquivos mudaram desde o último commit.
✗ O que NÃO autoriza afirmar:
- Dizer o que o time pretende fazer ou o que os requisitos vão exigir no futuro.
- Garantir que a arquitetura desejada está sendo seguida. Isso precisa de verificação à parte.
Quando duas fontes discordam
Esses estados nem sempre concordam: a especificação pede uma coisa, o repositório mostra outra, a memória guarda uma terceira. O modelo não resolve esse conflito em silêncio. O sistema:
- registra o veredito CONFLICT;
- preserva de onde veio cada informação (a proveniência);
- verifica o escopo e o frescor de cada fonte (a qual commit ela se refere e se ainda vale);
- envia para revisão humana os conflitos de intenção, de segurança ou de alto impacto.
Há ainda um sexto tipo de informação, o estado estrutural derivado: o grafo de código extraído do repositório (Cena 04). Ele é derivado, não é fonte primária. O repositório tem a palavra final sobre o que existe agora.
O que aconteceu: o agente recuperou o índice de contexto construído no commit C1. O repositório já estava em C2, onde uma regra nova de arquitetura proíbe chamadas diretas ao banco de dentro do controller.
Por que parecia sucesso: o código gerado compila e passa nos testes unitários.
O que ninguém tinha checado: se o índice ainda correspondia ao commit atual (C2) e se a nova regra de camadas valia para o trecho alterado.
Lição: um índice recuperado pode parecer coerente e estar desatualizado. Compare o commit dele com o atual antes de usar.
Cena 02 · Identidade de Estado ✦ PROPOSED
Snapshot Capsule: provar onde o agente está olhando
Pense numa pulseira de festival: vale para uma noite e um portão, não dá para reaproveitar em outro dia, e sem ela a segurança não deixa entrar. A Snapshot Capsule (um envelope selado com a identidade exata do repositório) faz o mesmo com o contexto do agente: nenhum contexto recuperado chega a ele sem estar selado com os 7 atributos abaixo. Se um deles faltar, o contexto inteiro passa a ser tratado como não confiável.
Snapshot Identity Digest
✓ SEALEDEstado atual: Os 7 atributos estão presentes e batem com o repositório: a identidade do snapshot está verificada.
Cena 03 · Contratos & Requisitos ✦ PROPOSED
Prompt não é contrato
Um pedido em linguagem natural é uma intenção, não uma especificação que dá para testar. Entre a necessidade de quem pediu e a prova de que ela foi atendida existe uma cadeia de transformações. É pulando etapas que requisitos que parecem óbvios, como privacidade, se perdem pelo caminho.
Oráculo (em inglês, oracle) é qualquer verificação automática que dá um veredito sobre uma propriedade: um teste, um linter (que checa estilo e padrões do código), um scanner de segurança.
O contrato é como revisar o mesmo Pull Request em quatro zooms. Cada nível pode aprovar algo que o outro reprovaria:
Nível 1 · Interface
A forma bate? Tipos, schemas, assinaturas de métodos e formatos de mensagem.
Nível 2 · Comportamento
Faz o que promete, e só isso? Pré-condições, pós-condições, invariantes (o que nunca pode mudar) e efeitos colaterais.
Nível 3 · Arquitetura
Vive onde deveria? Camadas, fronteiras entre módulos, dependências permitidas e isolamento.
Nível 4 · Semântica
É seguro e está em conformidade? Quem é dono dos dados, privacidade, retenção e impactos regulatórios.
Declarar uma regra não é o mesmo que fazer com que ela seja cumprida, e validar uma ação não prova que ela está correta em geral. Por isso a cadeia abaixo separa cada papel:
- Restrição (constraint): o que deve ser verdade, ou o que limita a solução.
- Política (policy): o que é autorizado ou proibido.
- Imposição (enforcement): o mecanismo que impede a violação. Declarar uma política não impede nada por si só.
- Validação: como uma propriedade é avaliada.
- Evidência: qual resultado foi produzido.
O que aconteceu: o agente implementou um serviço de envio de fotos. Todos os testes de API (níveis 1 e 2 do contrato) deram PASS.
Por que parecia sucesso: a API recebia e guardava as fotos com ótimo tempo de resposta.
O que ninguém tinha checado: a implementação gravava o EXIF (metadados da câmera, incluindo a localização) em logs abertos e compartilhava esses metadados com terceiros sem consentimento. É uma violação de nível 4.
Lição: o caminho principal continua verde, e uma trilha lateral fica sem vigilância porque nenhum oráculo foi escrito para ela.
Cena 04 · Análise Estrutural ✦ PROPOSED
A análise estática vê o que está escrito, não o que acontece em execução
Análise estática (ler o código sem executá-lo) e grafos de código (AST/CST, a árvore sintática do código, mais os símbolos e as relações entre eles) formam um mapa confiável de tudo que está escrito. Mas o mapa não mostra o que só acontece durante a execução: nenhuma análise estática captura o runtime por completo.
Cena 05 · Governança de Ação ✦ PROPOSED
Autonomia não é autoridade: o Action Gateway
Um modelo avançado consegue montar planos complexos sozinho. Isso é autonomia: o quanto ele planeja e encadeia ações. Autoridade é outra coisa: a permissão de realmente alterar o repositório, disparar um deploy ou chamar uma ferramenta privilegiada. No desenho proposto aqui, quem decide isso é o Action Gateway, e apenas ele.
Pense nele como um revisor de Pull Request automático e inflexível: se a mudança toca um arquivo fora da lista de permitidos, ele bloqueia, por melhor que o código esteja.
Baixa Autonomia · Baixa Autoridade
Automação rígida, scripts locais e leitura de rotina. Pouco risco e pouca capacidade.
Baixa Autonomia · Alta Autoridade
Scripts de deploy com grande blast radius (o quanto um erro pode se espalhar) e nenhum julgamento para perceber que algo está errado.
✦ Alta Autonomia · Baixa Autoridade (Zona Recomendada)
O agente investiga, planeja e propõe. A execução é sempre intermediada e limitada a um sandbox (ambiente isolado).
⚠️ Alta Autonomia · Alta Autoridade (Zona de Alto Risco)
O agente decide e executa direto em produção: decisão e execução no mesmo passo, sem barreira no meio.
Action Gateway · os 12 passos (proposta deste artigo), em 3 fases
Os 12 passos e o Diff Lens são um desenho próprio deste artigo, não um padrão estabelecido. Antes de qualquer efeito real, cada proposta passaria por 12 checagens: entender o pedido (1 a 5), decidir se é permitido (6 a 9) e executar e provar (10 a 12).
Diff Lens · o Gateway comparando o pedido com o escopo permitido
O Gateway não aprova só metade da proposta: ele bloqueia a ação inteira até o escopo ser corrigido.
Ele só consegue bloquear o que suas regras, permissões e schemas cobrem. Uma ferramenta com efeito que ninguém mapeou passa por ele sem ser vista. Por isso a cobertura e a eficácia do Gateway precisam ser demonstradas, e não presumidas.
O que aconteceu: uma ferramenta de leitura, sem risco (release_status), é chamada normalmente. Um ticket induz o agente a chamar, por dentro, uma segunda ferramenta (sync_environment) que tem permissão de escrita.
Por que parecia sucesso: a primeira chamada passa na verificação de leitura.
O que ninguém tinha checado: a segunda chamada é uma ação nova no fluxo e precisa ser avaliada pelo Action Gateway por conta própria. Ela não herda a aprovação da primeira.
Lição: formato válido e aprovação da chamada principal não autorizam chamadas encadeadas com mais privilégio.
Cena 06 · Força Epistemológica ✓ ESTABLISHED
Passar no teste não é o mesmo que estar certo
Um teste que passa (PASS) prova uma coisa só: a propriedade que ele verifica foi satisfeita nas condições em que ele rodou. Não prova que o sistema está correto nem que não houve efeitos colaterais. A tabela mostra 10 tipos de verificação (oráculos), o que cada PASS garante e o que continua sem garantia.
Os veredictos possíveis: PASS (passou), FAIL (falhou), UNKNOWN (sem base para concluir, por teste pulado, timeout ou ausência de teste) e CONFLICT (registros válidos com resultados incompatíveis entre si).
| Verificação (oráculo) | Veredicto | O que garante quando passa | O que continua sem garantia |
|---|---|---|---|
| 01. Parser (sintaxe) | PASS | A entrada é válida segundo a gramática da linguagem. | Tipos corretos, significado certo ou funcionamento. |
| 02. Type Checker (tipos) | PASS | Os tipos respeitam as regras do sistema de tipos. | Comportamento em execução e bugs de lógica. |
| 03. Análise estática / Linter | PASS | As regras e padrões configurados foram respeitados. | Que nada está faltando e que não há regressão funcional. |
| 04. Teste unitário | PASS | O caso testado passou com as entradas usadas. | Casos de borda que ninguém escreveu e requisitos esquecidos. |
| 05. Teste de integração | PASS | Os componentes funcionaram juntos no cenário testado. | Comportamento sob muita concorrência ou em produção. |
| 06. Scanner de segurança | PASS | Nenhuma vulnerabilidade conhecida foi encontrada. | Falhas de lógica de negócio que nunca foram catalogadas. |
| 07. Monitor de runtime | UNKNOWN | As métricas estiveram normais na janela observada. | O que acontece fora dessa janela, como em horários de pico. |
| 08. Model Checker (modelo formal) | FAIL | O modelo formal respeita as invariantes. | Que o modelo representa fielmente o código real. |
| 09. Verificador formal | CONFLICT | Prova matemática de que o código corresponde à especificação. | Que a especificação captura o que a pessoa realmente queria. |
| 10. Revisão humana | PASS | Uma pessoa avaliou e aprovou a mudança, segundo seu julgamento. | Proteção contra algo que a pessoa deixou passar. |
O que aconteceu: o teste test_rejects_negative_amount() falha depois de uma mudança. Para a suíte voltar a passar, ele é marcado com skip (pular).
Por que parecia sucesso: a suíte de testes fica 100% verde, sem nenhuma falha à vista.
O que ninguém tinha checado: a cobertura do que deveria ser testado diminuiu. O skip esconde a lacuna em vez de resolvê-la.
Lição: menos testes falhando não significa software mais correto. Pode significar apenas menos coisa sendo observada.
Cena 07 · Auditabilidade ✓ ESTABLISHED
Evidence Record: o recibo de cada validação
Toda validação deve gerar um Evidence Record imutável. Ele não guarda só o resultado: registra de onde veio (a proveniência), qual versão do validador rodou, em que ambiente e o que ficou de fora. É um recibo, não um certificado: prova que passou naquele teste, naquelas condições, e não garante que nada vai quebrar depois.
Alvo (Subject URI): git://repo@a8f3d1e/src/api/export.js
Commit: a8f3d1e992b47c01
Requisito: REQ-EXPORT-001
Propriedade verificada (predicate): POST /export devolve um PDF válido
Verificação (oráculo): orc_nodetest_v22 (teste de integração)
Executor (validator): node-test-runner:v22.22.1
Ambiente de execução: Docker Sandbox / rede isolada
O que ficou fora (Coverage Boundary): 88% das linhas cobertas / logging de EXIF NÃO coberto
Limitações declaradas: não cobre concorrência nem entradas malformadas
Assinatura de origem (Provenance): sig:sha256:990a1f...
Repare no campo em destaque: o registro declara o próprio ponto cego. Aqui, o PASS com 88% de cobertura não diz nada sobre o logging de EXIF do Caso 2. O tipo do oráculo importa: um PASS de parser e um PASS de uma regra de negócio formalizada não têm o mesmo peso (Cena 06).
Cena 08 · Decisão & Fechamento ✦ PROPOSED
Da evidência à decisão, e por onde começar
A reconciliação é o momento de decidir o que fazer com a mudança. Ela compara o estado desejado, o estado atual, a evidência obtida e as regras de política, e produz uma entre 7 decisões possíveis, não só aceitar ou rejeitar.
01. Desired State
Os requisitos de aceitação e as regras que nunca podem ser quebradas.
02. Current State
O diff (a diferença entre o código antes e depois) do repositório após a ação do agente.
03. Evidence State
O Evidence Record, com veredictos e limites.
04. Policy State
A lista de permitidos e as aprovações da ação.
As 7 decisões possíveis
Grounding é um ciclo, não um passo
Cinco palavras aparecem neste artigo e significam coisas diferentes: grounding (associar algo à realidade observada), imposição (restringir ou bloquear), validação (avaliar propriedades), evidência (registrar o resultado) e reconciliação (comparar estados e decidir). O ciclo de grounding percorre cinco momentos:
| Momento | O que faz | Mecanismo neste artigo |
|---|---|---|
| Contexto | Associa o contexto recuperado a fatos e entidades atuais. | Snapshot Capsule (Cena 02) |
| Planejamento | Confronta o plano com o estado atual e com a especificação. | Contrato e Desired State (Cena 03) |
| Execução | Restringe as ações autorizadas. | Action Gateway (Cena 05) |
| Validação | Avalia a ação contra propriedades definidas. | Oráculos (Cena 06) |
| Reconciliação | Compara estado desejado, estado atual e evidência. | As 7 decisões (esta cena) |
Experimento: e se você desligar um controle?
Desligue os mecanismos abaixo e veja quais das 5 classes de desvio (dependência inventada, contexto desatualizado, mudança fora de escopo, violação de arquitetura e estado divergente do repositório) voltam a ficar sem proteção. Cada classe depende de pelo menos um controle, e a violação de arquitetura depende de dois (validação e grounding). É uma simulação da lógica de cobertura, não um resultado medido em projetos reais.
Comece com um MVA (Minimum Viable Architecture)
Um MVA é a menor versão do pipeline que já vale rodar. Monte-o com um risco baixo, seguindo estas 7 ações:
- Escolha uma tarefa pequena e de baixo impacto.
- Fixe a Snapshot Capsule (o SHA do commit, o tree digest e o hash do lockfile).
- Declare no Action Gateway a lista de arquivos permitidos e a de proibidos.
- Transforme pelo menos um requisito em contrato, com um oráculo independente para verificá-lo.
- Rode o agente em sandbox, sem nenhuma autoridade implícita.
- Registre os veredictos PASS, FAIL, UNKNOWN e CONFLICT no Evidence Record.
- Compare o resultado com um baseline (a mesma tarefa, sem grounding).
Cena 09 · Limitações
O que este artigo ainda não prova
Este texto descreve uma proposta de arquitetura, não um resultado medido. Antes de adotar qualquer parte dela, considere:
- É uma proposta. Snapshot Capsule, Action Gateway (com os 12 passos e o Diff Lens) e Evidence Record são desenhos deste artigo. Não há, até aqui, medição da eficácia deles.
- O nome é provisório. "Deterministic Grounding" não é terminologia padronizada.
- O experimento da Cena 08 é uma simulação. Ele mostra que controle cobre qual classe de desvio, não quanto cada um reduz erros na prática.
- O Gateway só bloqueia o que conhece. Efeitos de ferramentas sem regra, permissão ou schema correspondente escapam dele.
- O digest prova identidade, não completude. Ele cobre os artefatos incluídos na cápsula, e só eles.
- A análise estática não vê o código dinâmico (Cena 04), e um PASS vale apenas para a propriedade e o ambiente em que foi obtido (Cena 06).
- Faltam fontes. O artigo ainda não cita fontes primárias com data de verificação. As afirmações são a proposta do autor, não o resultado de uma revisão de literatura.
Cena 10 · Glossário
Os termos, em linguagem comum
Os termos originais continuam corretos e aparecem ao longo do artigo. Esta tabela é o atalho para lembrar o que cada um quer dizer.
| Termo original | Em linguagem comum | O que significa |
|---|---|---|
| Agent–Repository Gap | O desalinhamento | A diferença entre o que o agente acredita saber do repositório e o que realmente está lá agora. Em textos acadêmicos aparece como G_t = A_t − S_t, onde A_t é o que o agente assume no instante t e S_t é o estado real do repositório nesse instante. |
| Snapshot Capsule | O lacre de contexto | Envelope selado que prova qual commit e qual ambiente o agente está vendo. |
| Action Gateway | O revisor de Pull Request inflexível | A barreira que decide o que o agente pode de fato executar. |
| Allowlist | Lista de permitidos | Só o que está na lista pode ser tocado. O resto é bloqueado. |
| Policy-as-Code | Regra escrita como código | Regras de permitido e proibido versionadas, em vez de uma política em PDF que ninguém consulta. |
| Blast radius | Raio de estrago | Quanto uma ação pode se espalhar se der errado. |
| Oracle (oráculo) | A verificação automática | Qualquer checagem automática que dá um veredito sobre uma propriedade: teste, linter, scanner. |
| Evidence Record | O recibo de validação | Registro imutável do que foi checado, por quem e sob quais condições. |
| Coverage Boundary | O que ficou fora do teste | O limite explícito do que a validação não cobriu. |
| Provenance (proveniência) | Rastro de origem | A cadeia verificável de quem gerou e assinou uma evidência. |
| Desired State | O que deveria ser verdade | Requisitos e critérios de aceitação declarados. |
| Current State | O que é verdade agora | O estado observável do repositório neste momento. |
| Contrato de 4 níveis | Revisão em 4 zooms | Interface, comportamento, arquitetura e semântica. Cada nível pode aprovar o que outro reprovaria. |
| Autonomia vs. autoridade | Pensar sozinho vs. poder executar | Quanto o agente planeja sem ajuda, contra quanto ele pode alterar de verdade. |
| Reconciliation (reconciliação) | A decisão final | Etapa que junta requisito, estado, evidência e política e decide o próximo passo. |
| Determinismo (neste artigo) | Mesmo insumo, mesmo resultado | Mesma entrada, mesma versão do validador, mesma configuração, mesmas dependências e mesmo ambiente controlado produzem o mesmo resultado de verificação. |
| Constraint / Policy / Enforcement | Restrição / regra / imposição | A restrição diz o que deve ser verdade, a política diz o que é autorizado e a imposição é o mecanismo que impede a violação. |
| Grounding lifecycle | O ciclo de grounding | Os cinco momentos em que o agente é ancorado na realidade: contexto, planejamento, execução, validação e reconciliação. |
| MVA (Minimum Viable Architecture) | O mínimo que já vale rodar | A menor versão do pipeline de governança que já traz benefício. |