Ground Truths: anclando a los agentes de IA en la realidad

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Los agentes de IA son notablemente capaces. Pueden razonar, sintetizar y generar. Pero tienen una debilidad fundamental: se inventan cosas. No maliciosamente, sino con confianza. Un agente puede inventar parámetros de API que no existen, hacer referencia a configuraciones que nunca se definieron, o aplicar patrones de sus datos de entrenamiento que contradicen tu arquitectura real.

La mitigación estándar es «dale más contexto al agente». Pero el contexto puede ser contradictorio. La documentación se desvía de la implementación. Los comentarios mienten. Incluso el código puede engañar cuando se lee sin entender la intención.

Necesitábamos algo más explícito. Algo que no pudiera ignorarse ni malinterpretarse. Algo que anclara a los agentes a una realidad verificable.

Los llamamos Ground Truths.

¿Qué es un Ground Truth?

Un ground truth es una declaración de hecho explícita y versionada que los agentes deben respetar. No es documentación. No es un comentario. Es una entidad de primera clase en el sistema con:

• Un identificador único (como GT-MAG-015 o GT-MAG-036)
• Un estado de ciclo de vida (vigente, tentativo o en desuso)
• Un alcance (de toda la plataforma, específico de un paquete o acotado a un dominio)
• Evidencia (rutas de archivo, URLs o referencias que respaldan la declaración)
• Guía para el agente (instrucciones explícitas de qué hacer y qué evitar)

Aquí hay un ejemplo de nuestra plataforma de inteligencia 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

Esto no es prosa. Es un contrato. Cuando un agente se encuentra con este ground truth, sabe que:

1. El comportamiento predeterminado es determinista (resultados vacíos, no conjeturas difusas)
2. Hay parámetros específicos (find_similar, exact_match) con comportamientos definidos
3. Existe evidencia en archivos específicos que se pueden verificar
4. La declaración se verificó en una fecha específica

La anatomía de un registro de Ground Truths

Los ground truths viven en registros YAML bajo ai_assets/reference/ground_truths.yaml. Cada paquete o dominio puede tener su propio registro. La estructura es:

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..."
    ...

El registro incluye metadatos sobre la colección misma, configuración de renderizado para la generación de documentación, y las declaraciones en sí. Cada declaración sigue un esquema estricto validado por modelos de 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

Cómo acceden los agentes a los Ground Truths

Los ground truths se exponen a través de múltiples canales:

1. Documentación renderizada

El comando orkestra sync transforma los registros YAML en markdown legible:

uv run orkestra sync

Esto genera archivos GROUND_TRUTHS.md que se incluyen en el contexto del agente. La salida renderizada agrupa las declaraciones por estado y categoría:

## 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. Búsqueda por CLI

Los agentes con acceso a shell pueden buscar ground truths mediante programación:

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

La función de búsqueda puntúa las coincidencias en varios campos con relevancia 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. Composición de contexto

Cuando los agentes se renderizan a partir de definiciones YAML, su contexto puede hacer referencia a registros de ground truths:

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

Esto garantiza que los ground truths relevantes se carguen antes de que el agente comience a trabajar.

Categorías de Ground Truths

Mirando nuestros registros en conjunto, los ground truths se agrupan en varios patrones:

Principios del producto

Restricciones sobre qué es y qué no es el producto:

«Maguyva es de solo lectura respecto de los repositorios de los usuarios; el único activo que no se puede reconstruir es la caché de embeddings pagada». (GT-MAG-001)

Límites de arquitectura

Dónde viven las responsabilidades y por qué:

«Los límites entre pipeline y Maguyva son intencionales: pipeline es reutilizable, Maguyva contiene la lógica específica de código, y CQRS separa las escrituras de etapa de las lecturas del servidor». (GT-MAG-006)

Reglas antialucinación

Mandatos explícitos que mantienen los contratos de herramientas deterministas en lugar de inferidos:

«La coincidencia difusa de símbolos es opcional mediante find_similar=true. El comportamiento predeterminado devuelve resultados vacíos para símbolos inexistentes; exact_match=true impone coincidencia estricta y desactiva todos los mecanismos de respaldo difusos». (GT-MAG-015)

Compuertas de calidad

Estándares que deben mantenerse:

«Los cambios a la infraestructura compartida (post_filters.py, extractores de relaciones, handlers compartidos) DEBEN validarse contra TODOS los lenguajes compatibles mediante la generación de un manifiesto completo antes de hacer commit. Una validación de un solo lenguaje es insuficiente para código compartido». (GT-MAG-036)

Patrones de código

Requisitos de implementación:

«Usa asyncio.to_thread() para trabajo limitado por CPU en contextos asíncronos; el patrón en desuso loop.run_in_executor() no debe usarse en código nuevo». (GT-MAG-018)

El ciclo de vida de un Ground Truth

Los ground truths no son estáticos. Evolucionan a través de un ciclo de vida definido:

Tentativo

Una verdad propuesta bajo evaluación. La declaración se registra, pero puede cambiar:

- 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.

Vigente

Una verdad verificada que los agentes deben respetar. La evidencia ha sido validada:

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

En desuso

Una verdad que ya no aplica. Se conserva como referencia histórica con un puntero a lo que la reemplazó:

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

¿Por qué no simplemente documentación?

La documentación cumple un propósito distinto. Explica. Enseña. Puede ser vaga, puede usar calificadores como «generalmente» o «típicamente».

Los ground truths no pueden ser vagos. Son afirmaciones. O aplican, o no aplican.

Considera la diferencia:

Documentación: «La API generalmente devuelve resultados vacíos cuando no se encuentra un símbolo, aunque la coincidencia difusa puede estar habilitada en algunas configuraciones».

Ground Truth: «El comportamiento predeterminado devuelve resultados vacíos para símbolos inexistentes; exact_match=true impone coincidencia estricta y desactiva todos los mecanismos de respaldo difusos».

La primera es útil para que los humanos aprendan el sistema. La segunda es accionable para que los agentes tomen decisiones.

Guía para el agente: qué hacer y qué evitar

Algunos ground truths incluyen guía explícita para el 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"

Esto elimina la ambigüedad. Un agente que lee esto sabe no solo qué es verdad, sino qué acciones implica esa verdad.

Verificación y mantenimiento

Los ground truths requieren mantenimiento. Rastreamos:

• last_verified: cuándo alguien confirmó que la declaración sigue siendo válida
• evidence: archivos que respaldan la declaración (se puede verificar si existen)
• source: de dónde se originó la verdad (inspección por CLI, revisión de arquitectura, aprendizaje posterior a un incidente)

Un ground truth con fechas de verificación desactualizadas o enlaces de evidencia rotos es una señal para investigar. O la verdad sigue siendo válida y necesita reverificación, o la realidad cambió y la verdad necesita actualizarse.

Ejemplos reales de producción

Límite de seguridad

- 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.

Este ground truth evita una clase de «mejoras de seguridad» mal orientadas que romperían el producto.

Precisión en tiempo de extracción

- 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.

Esto surgió de una experiencia dolorosa. Los agentes solían parchar paquetes de lenguaje fallidos agregando filtros que solo actuaban en el validador, lo que hacía que el arnés de pruebas se viera más verde, mientras que el extractor real de Maguyva seguía emitiendo las aristas equivocadas. La regla obliga a que las correcciones vuelvan a la ruta real: configuración YAML, consultas o handlers.

Filtrado en múltiples niveles

- 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).

Esto evita que los agentes agreguen filtros en el lugar equivocado, un error común que causaba regresiones de precisión.

Integración con el sistema de orquestación

Los ground truths son una capa de un sistema de contexto más amplio:

1. Decisiones arquitectónicas (ADRs) - Registran por qué elegimos el enfoque A sobre el B
2. Ground Truths - Establecen qué es definitivamente cierto en este momento
3. Patrones de dominio - Describen cómo hacer las cosas correctamente
4. Antipatrones - Describen qué evitar y por qué

Un agente que trabaja en el sistema tiene acceso a los cuatro. Los ground truths proporcionan el ancla factual, mientras que las decisiones explican la historia, los patrones guían la implementación y los antipatrones advierten sobre los riesgos.

Midiendo el impacto

Desde que introdujimos los ground truths, hemos observado:

• Menos ciclos de «corregir la corrección alucinada»
• Toma de decisiones más segura por parte de los agentes cuando los hechos son claros
• Mejores revisiones de PR porque las expectativas son explícitas
• Menor tiempo de incorporación para nuevos agentes (y humanos)

La inversión en mantener los ground truths se paga sola con menos depuración y límites de sistema más claros.

Cómo empezar

Para agregar un ground truth a tu sistema:

1. Crea un ground_truths.yaml en el directorio ai_assets/reference/ de tu paquete
2. Define los metadatos y la configuración de renderizado
3. Agrega declaraciones siguiendo el esquema
4. Ejecuta uv run orkestra sync para generar la documentación
5. Incluye el registro en la composición de contexto del agente

Empieza con los hechos que causan más confusión o las restricciones que se violan con más frecuencia. Esos son tus ground truths de mayor valor.

Conclusión

Los agentes de IA van a alucinar. Es su naturaleza. Pero podemos crear entornos donde la alucinación esté acotada, donde ciertos hechos sean innegociables, donde los agentes puedan contrastar sus suposiciones con una realidad verificada.

Los ground truths no son una solución completa. Requieren mantenimiento. Pueden quedar desactualizados. Agregan sobrecarga al proceso de desarrollo.

Pero aportan algo valioso: un vocabulario compartido de hechos en el que tanto humanos como agentes pueden confiar. En un mundo donde los agentes participan cada vez más en el desarrollo de software, esa base compartida se vuelve esencial.

La alternativa son ciclos interminables de agentes cometiendo errores con total confianza y humanos corrigiéndolos. Los ground truths rompen ese ciclo al hacer que las correcciones sean explícitas y duraderas.

Tus agentes merecen saber qué es verdad. Díselo.