Ground Truths: Ancorando Agentes de IA à Realidade

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

Agentes de IA são notavelmente capazes. Eles conseguem raciocinar, sintetizar e gerar. Mas têm uma fraqueza fundamental: eles inventam coisas. Não de forma maliciosa, mas com confiança. Um agente pode inventar parâmetros de API que não existem, referenciar configurações que nunca foram definidas, ou aplicar padrões dos seus dados de treinamento que contradizem a sua arquitetura real.

A mitigação padrão é “dar mais contexto ao agente”. Mas o contexto pode ser contraditório. A documentação se distancia da implementação. Comentários mentem. Até o próprio código pode enganar quando lido sem entender a intenção.

Precisávamos de algo mais explícito. Algo que não pudesse ser ignorado ou mal interpretado. Algo que ancorasse os agentes a uma realidade verificável.

Chamamos isso de Ground Truths.

O que é um Ground Truth?

Um ground truth é uma declaração de fato explícita e versionada que os agentes devem respeitar. Não é documentação. Não é um comentário. É uma entidade de primeira classe no sistema, com:

• Um identificador único (como GT-MAG-015 ou GT-MAG-036)
• Um status de ciclo de vida (atual, tentativo ou obsoleto)
• Um escopo (de toda a plataforma, específico de pacote, ou restrito a um domínio)
• Evidência (caminhos de arquivo, URLs ou referências que comprovam a declaração)
• Orientação para o agente (instruções explícitas do que fazer/evitar)

Aqui está um exemplo da nossa plataforma de inteligência de código Maguyva:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Isso não é prosa. É um contrato. Quando um agente encontra esse ground truth, ele sabe:

1. O padrão é determinístico (resultados vazios, não chutes aproximados)
2. Existem parâmetros específicos (find_similar, exact_match) com comportamentos definidos
3. Existe evidência em arquivos específicos que podem ser verificados
4. A declaração foi verificada em uma data específica

A Anatomia de um Registro de Ground Truths

Ground truths vivem em registros YAML sob ai_assets/reference/ground_truths.yaml. Cada pacote ou domínio pode ter seu próprio registro. A estrutura é:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

O registro inclui metadados sobre a própria coleção, configuração de renderização para geração de documentação, e as declarações em si. Cada declaração segue um schema rígido validado por modelos Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Como os Agentes Acessam Ground Truths

Ground truths são expostos por múltiplos canais:

1. Documentação Renderizada

O comando orkestra sync transforma registros YAML em markdown legível:

uv run orkestra sync

Isso gera arquivos GROUND_TRUTHS.md que são incluídos no contexto do agente. A saída renderizada agrupa as declarações por status e categoria:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Busca via CLI

Agentes com acesso a shell podem buscar ground truths de forma programática:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

A função de busca pontua correspondências em vários campos com relevância ponderada:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Composição de Contexto

Quando agentes são renderizados a partir de definições YAML, o contexto deles pode referenciar registros de ground truths:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Isso garante que os ground truths relevantes sejam carregados antes de o agente começar a trabalhar.

Categorias de Ground Truths

Olhando para os nossos registros, os ground truths se agrupam em vários padrões:

Princípios do Produto

Restrições sobre o que o produto é e o que não é:

“O Maguyva é somente leitura em relação aos repositórios dos usuários; o único ativo não reconstruível é o cache pago de embeddings.” (GT-MAG-001)

Limites de Arquitetura

Onde as responsabilidades vivem e por quê:

“Os limites entre pipeline e Maguyva são intencionais: o pipeline é reutilizável, o Maguyva contém a lógica específica de código, e o CQRS separa as escritas de stage das leituras de servidor.” (GT-MAG-006)

Regras Antialucinação

Mandatos explícitos que mantêm os contratos de ferramentas determinísticos em vez de inferidos:

“A correspondência fuzzy de símbolos é opt-in via find_similar=true. O comportamento padrão retorna resultados vazios para símbolos inexistentes; exact_match=true força a correspondência estrita e desativa todos os fallbacks fuzzy.” (GT-MAG-015)

Gates de Qualidade

Padrões que precisam ser mantidos:

“Mudanças em infraestrutura compartilhada (post_filters.py, extratores de relacionamento, handlers compartilhados) DEVEM ser validadas contra TODAS as linguagens suportadas via geração de manifesto completo antes do commit. Uma validação de uma única linguagem é insuficiente para código compartilhado.” (GT-MAG-036)

Padrões de Código

Requisitos de implementação:

“Use asyncio.to_thread() para trabalho limitado por CPU em contextos assíncronos; o padrão obsoleto loop.run_in_executor() não deve ser usado em código novo.” (GT-MAG-018)

O Ciclo de Vida de um Ground Truth

Ground truths não são estáticos. Eles evoluem por um ciclo de vida definido:

Tentativo

Uma verdade proposta em avaliação. A declaração é registrada, mas pode mudar:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Atual

Uma verdade verificada que os agentes devem respeitar. A evidência foi validada:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Obsoleto

Uma verdade que não se aplica mais. Mantida para referência histórica, com um ponteiro para o que a substituiu:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Por Que Não Apenas Documentação?

A documentação serve a um propósito diferente. Ela explica. Ela ensina. Pode ser vaga, pode usar qualificadores como “geralmente” ou “tipicamente”.

Ground truths não podem ser vagos. São afirmações. Ou se aplicam, ou não se aplicam.

Considere a diferença:

Documentação: “A API geralmente retorna resultados vazios quando um símbolo não é encontrado, embora a correspondência fuzzy possa estar habilitada em algumas configurações.”

Ground Truth: “O comportamento padrão retorna resultados vazios para símbolos inexistentes; exact_match=true força a correspondência estrita e desativa todos os fallbacks fuzzy.”

A primeira é útil para humanos aprendendo o sistema. A segunda é acionável para agentes tomando decisões.

Orientação para o Agente: Fazer e Evitar

Alguns ground truths incluem orientação explícita para o agente:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Isso remove a ambiguidade. Um agente lendo isso sabe não apenas o que é verdade, mas quais ações essa verdade implica.

Verificação e Manutenção

Ground truths exigem manutenção. Rastreamos:

• last_verified: quando alguém confirmou que a declaração ainda vale
• evidence: arquivos que comprovam a declaração (pode-se verificar se existem)
• source: de onde a verdade se originou (inspeção via CLI, revisão de arquitetura, aprendizado pós-incidente)

Um ground truth com datas de verificação desatualizadas ou links de evidência quebrados é um sinal para investigar. Ou a verdade ainda é válida e precisa de reverificação, ou a realidade mudou e a verdade precisa ser atualizada.

Exemplos Reais de Produção

Limite de Segurança

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Esse ground truth previne uma classe de “melhorias de segurança” mal orientadas que quebrariam o produto.

Precisão no Momento da Extração

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Isso veio de uma experiência dolorosa. Agentes corrigiam pacotes de linguagem com falhas adicionando filtros apenas no validador, que faziam o harness de teste parecer mais verde, enquanto o extrator Maguyva ao vivo continuava emitindo as arestas erradas. A regra força as correções de volta para o caminho real: configuração YAML, queries ou handlers.

Filtragem em Múltiplos Níveis

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Isso impede que agentes adicionem filtros no lugar errado, um erro comum que causou regressões de precisão.

Integração com o Sistema de Orquestração

Ground truths são uma camada de um sistema de contexto mais amplo:

1. Decisões Arquiteturais (ADRs) - Registram por que escolhemos a abordagem A em vez da B
2. Ground Truths - Declaram o que é definitivamente verdade agora
3. Padrões de Domínio - Descrevem como fazer as coisas corretamente
4. Antipadrões - Descrevem o que evitar e por quê

Um agente trabalhando no sistema tem acesso aos quatro. Os ground truths fornecem a âncora factual, enquanto as decisões explicam a história, os padrões guiam a implementação, e os antipadrões alertam sobre armadilhas.

Medindo o Impacto

Desde que introduzimos os ground truths, observamos:

• Menos ciclos de “corrigir a correção alucinada”
• Tomada de decisão mais confiante pelos agentes quando os fatos estão claros
• Revisões de PR melhores, porque as expectativas são explícitas
• Tempo de onboarding reduzido para novos agentes (e humanos)

O investimento em manter os ground truths se paga em menos depuração e limites de sistema mais claros.

Começando

Para adicionar um ground truth ao seu sistema:

1. Crie um ground_truths.yaml no diretório ai_assets/reference/ do seu pacote
2. Defina metadados e configuração de renderização
3. Adicione declarações seguindo o schema
4. Rode uv run orkestra sync para gerar a documentação
5. Inclua o registro na composição de contexto do agente

Comece pelos fatos que causam mais confusão ou pelas restrições que são violadas com mais frequência. Esses são os seus ground truths de maior valor.

Conclusão

Agentes de IA vão alucinar. Essa é a natureza deles. Mas podemos criar ambientes em que a alucinação é restringida, em que certos fatos são inegociáveis, em que os agentes podem checar suas suposições contra uma realidade verificada.

Ground truths não são uma solução completa. Eles exigem manutenção. Podem ficar desatualizados. Adicionam sobrecarga ao processo de desenvolvimento.

Mas eles fornecem algo valioso: um vocabulário compartilhado de fatos em que tanto humanos quanto agentes podem confiar. Em um mundo em que os agentes participam cada vez mais do desenvolvimento de software, essa base compartilhada se torna essencial.

A alternativa é um ciclo infinito de agentes cometendo erros com confiança e humanos os corrigindo. Ground truths quebram esse ciclo tornando as correções explícitas e duradouras.

Seus agentes merecem saber o que é verdade. Diga a eles.