Ground Truths: AI-agents verankeren in de realiteit

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

AI-agents zijn opmerkelijk capabel. Ze kunnen redeneren, synthetiseren en genereren. Maar ze hebben een fundamentele zwakte: ze verzinnen dingen. Niet kwaadwillig, maar wel overtuigend. Een agent kan API-parameters bedenken die niet bestaan, verwijzen naar configuraties die nooit zijn gedefinieerd, of patronen uit zijn trainingsdata toepassen die in strijd zijn met jouw daadwerkelijke architectuur.

De standaardoplossing is “geef de agent meer context”. Maar context kan tegenstrijdig zijn. Documentatie raakt los van de implementatie. Comments liegen. Zelfs code kan misleidend zijn wanneer die wordt gelezen zonder de bedoeling te begrijpen.

We hadden iets explicieters nodig. Iets dat niet genegeerd of verkeerd geïnterpreteerd kon worden. Iets dat agents zou verankeren in verifieerbare realiteit.

We noemen ze Ground Truths.

Wat is een Ground Truth?

Een ground truth is een expliciete, geversioneerde feitelijke bewering die agents moeten respecteren. Het is geen documentatie. Het is geen comment. Het is een first-class entiteit in het systeem met:

• Een unieke identifier (zoals GT-MAG-015 of GT-MAG-036)
• Een levenscyclusstatus (current, tentative, of deprecated)
• Een scope (platformbreed, package-specifiek, of domeingebonden)
• Bewijs (bestandspaden, URL’s, of referenties die de bewering staven)
• Agent guidance (expliciete do/avoid-instructies)

Hier is een voorbeeld uit ons Maguyva code intelligence-platform:

- 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

Dit is geen proza. Het is een contract. Wanneer een agent deze ground truth tegenkomt, weet hij:

1. Het standaardgedrag is deterministisch (lege resultaten, geen vage gissingen)
2. Er zijn specifieke parameters (find_similar, exact_match) met gedefinieerd gedrag
3. Er bestaat bewijs in specifieke bestanden dat geverifieerd kan worden
4. De bewering is geverifieerd op een specifieke datum

De anatomie van een Ground Truth-register

Ground truths leven in YAML-registers onder ai_assets/reference/ground_truths.yaml. Elk package of domein kan zijn eigen register hebben. De structuur is:

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

Het register bevat metadata over de collectie zelf, renderconfiguratie voor documentatiegeneratie, en de beweringen zelf. Elke bewering volgt een strikt schema dat wordt gevalideerd door Pydantic-modellen:

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

Hoe agents toegang krijgen tot Ground Truths

Ground truths worden via meerdere kanalen beschikbaar gesteld:

1. Gerenderde documentatie

Het commando orkestra sync transformeert YAML-registers naar leesbare markdown:

uv run orkestra sync

Dit genereert GROUND_TRUTHS.md-bestanden die worden opgenomen in de agentcontext. De gerenderde output groepeert beweringen op status en categorie:

## 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. CLI-zoeken

Agents met shelltoegang kunnen ground truths programmatisch doorzoeken:

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

De zoekfunctie scoort matches over meerdere velden met gewogen relevantie:

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

Wanneer agents worden gerenderd vanuit YAML-definities, kan hun context verwijzen naar ground truth-registers:

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

Dit zorgt ervoor dat relevante ground truths worden geladen voordat de agent aan het werk gaat.

Categorieën van Ground Truths

Als we over onze registers heen kijken, clusteren ground truths in verschillende patronen:

Productprincipes

Beperkingen op wat het product wel en niet is:

“Maguyva is read-only ten aanzien van gebruikersrepositories; het enige niet-herbouwbare asset is de betaalde embeddings-cache.” (GT-MAG-001)

Architectuurgrenzen

Waar verantwoordelijkheden liggen en waarom:

“De grenzen tussen pipeline en Maguyva zijn opzettelijk: pipeline is herbruikbaar, Maguyva bevat codespecifieke logica, en CQRS scheidt stage-writes van server-reads.” (GT-MAG-006)

Anti-hallucinatieregels

Expliciete mandaten die toolcontracten deterministisch houden in plaats van afgeleid:

“Fuzzy symboolmatching gebeurt opt-in via find_similar=true. Standaardgedrag geeft lege resultaten voor niet-bestaande symbolen; exact_match=true dwingt strikte matching af en schakelt alle fuzzy fallbacks uit.” (GT-MAG-015)

Kwaliteitsgates

Standaarden die gehandhaafd moeten worden:

“Wijzigingen aan gedeelde infrastructuur (post_filters.py, relationship extractors, gedeelde handlers) MOETEN vóór commit worden gevalideerd tegen ALLE ondersteunde talen via full manifest generation. Een validatie voor één taal is onvoldoende voor gedeelde code.” (GT-MAG-036)

Codepatronen

Implementatievereisten:

“Gebruik asyncio.to_thread() voor CPU-bound werk in async-contexten; het verouderde loop.run_in_executor()-patroon mag niet worden gebruikt in nieuwe code.” (GT-MAG-018)

De levenscyclus van een Ground Truth

Ground truths zijn niet statisch. Ze evolueren via een gedefinieerde levenscyclus:

Tentative

Een voorgestelde waarheid die wordt geëvalueerd. De bewering is vastgelegd maar kan nog wijzigen:

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

Current

Een geverifieerde waarheid die agents moeten respecteren. Het bewijs is gevalideerd:

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

Deprecated

Een waarheid die niet langer van toepassing is. Bewaard als historische referentie met een verwijzing naar wat hem heeft vervangen:

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

Waarom niet gewoon documentatie?

Documentatie dient een ander doel. Ze legt uit. Ze onderwijst. Ze mag vaag zijn, mag kwalificaties gebruiken zoals “over het algemeen” of “doorgaans”.

Ground truths mogen niet vaag zijn. Het zijn beweringen. Ze gelden, of ze gelden niet.

Bekijk het verschil:

Documentatie: “De API geeft over het algemeen lege resultaten wanneer een symbool niet wordt gevonden, hoewel fuzzy matching in sommige configuraties ingeschakeld kan zijn.”

Ground Truth: “Standaardgedrag geeft lege resultaten voor niet-bestaande symbolen; exact_match=true dwingt strikte matching af en schakelt alle fuzzy fallbacks uit.”

De eerste is nuttig voor mensen die het systeem leren kennen. De tweede is bruikbaar voor agents die beslissingen nemen.

Agent guidance: do en avoid

Sommige ground truths bevatten expliciete agent guidance:

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

Dit neemt ambiguïteit weg. Een agent die dit leest, weet niet alleen wat waar is, maar ook welke acties die waarheid impliceert.

Verificatie en onderhoud

Ground truths vereisen onderhoud. We houden bij:

• last_verified: Wanneer iemand heeft bevestigd dat de bewering nog steeds klopt
• evidence: Bestanden die de bewering staven (kunnen op bestaan worden gecontroleerd)
• source: Waar de waarheid vandaan komt (CLI-inspectie, architectuurreview, post-incident-leren)

Een ground truth met verouderde verificatiedatums of gebroken bewijslinks is een signaal om te onderzoeken. Of de waarheid is nog steeds geldig en heeft herverificatie nodig, of de realiteit is veranderd en de waarheid moet worden bijgewerkt.

Echte voorbeelden uit productie

Beveiligingsgrens

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

Deze ground truth voorkomt een klasse van misplaatste “beveiligingsverbeteringen” die het product zouden breken.

Nauwkeurigheid op extractiemoment

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

Dit kwam voort uit een pijnlijke ervaring. Agents patchten falende taalpakketten door validator-only filters toe te voegen die de testharness groener lieten ogen, terwijl de live Maguyva-extractor nog altijd de verkeerde edges uitzond. De regel dwingt fixes terug naar het echte pad: YAML-config, queries, of handlers.

Meerlaagse filtering

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

Dit voorkomt dat agents filters op de verkeerde plek toevoegen, een veelvoorkomende fout die accuratesse-regressies veroorzaakte.

Integratie met het orchestratiesysteem

Ground truths zijn één laag van een breder contextsysteem:

1. Architecturale beslissingen (ADR’s) - Leggen vast waarom we aanpak A boven B kozen
2. Ground Truths - Stellen vast wat op dit moment definitief waar is
3. Domeinpatronen - Beschrijven hoe je dingen correct doet
4. Anti-patronen - Beschrijven wat je moet vermijden en waarom

Een agent die in het systeem werkt, heeft toegang tot alle vier. Ground truths bieden het feitelijke anker, terwijl beslissingen de geschiedenis verklaren, patronen de implementatie sturen, en anti-patronen waarschuwen voor valkuilen.

De impact meten

Sinds we ground truths hebben geïntroduceerd, zien we:

• Minder “repareer de gehallucineerde fix”-cycli
• Zelfverzekerdere agentbeslissingen wanneer feiten duidelijk zijn
• Betere PR-reviews omdat verwachtingen expliciet zijn
• Kortere onboardingtijd voor nieuwe agents (en mensen)

De investering in het onderhouden van ground truths betaalt zich terug in minder debuggen en helderdere systeemgrenzen.

Aan de slag

Om een ground truth toe te voegen aan jouw systeem:

1. Maak een ground_truths.yaml aan in de ai_assets/reference/-directory van je package
2. Definieer metadata en renderconfiguratie
3. Voeg beweringen toe volgens het schema
4. Voer uv run orkestra sync uit om documentatie te genereren
5. Neem het register op in de agentcontextcompositie

Begin met de feiten die de meeste verwarring veroorzaken of de beperkingen die het vaakst worden overtreden. Dat zijn je meest waardevolle ground truths.

Conclusie

AI-agents zullen hallucineren. Dat zit in hun aard. Maar we kunnen omgevingen creëren waarin hallucinatie wordt beperkt, waarin bepaalde feiten niet onderhandelbaar zijn, waarin agents hun aannames kunnen toetsen aan geverifieerde realiteit.

Ground truths zijn geen complete oplossing. Ze vereisen onderhoud. Ze kunnen verouderen. Ze voegen overhead toe aan het ontwikkelproces.

Maar ze bieden iets waardevols: een gedeeld vocabulaire van feiten dat zowel mensen als agents kunnen vertrouwen. In een wereld waarin agents steeds meer deelnemen aan softwareontwikkeling, wordt dat gedeelde fundament essentieel.

Het alternatief is eindeloze cycli van agents die overtuigd fouten maken en mensen die ze corrigeren. Ground truths doorbreken die cyclus door de correcties expliciet en duurzaam te maken.

Jouw agents verdienen te weten wat waar is. Vertel het ze.