Ground Truths: Forankring af AI-agenter i virkeligheden

Tallene i dette indlæg afspejler systemet på udgivelsestidspunktet (januar 2026). Se vores team-side for aktuelle tal.

AI-agenter er bemærkelsesværdigt dygtige. De kan ræsonnere, syntetisere og generere. Men de har en fundamental svaghed: de finder på ting. Ikke ondsindet, men selvsikkert. En agent kan finde på API-parametre, der ikke findes, referere til konfigurationer, der aldrig blev defineret, eller anvende mønstre fra sine træningsdata, der modsiger din faktiske arkitektur.

Den standard afhjælpning er “giv agenten mere kontekst.” Men kontekst kan være modstridende. Dokumentation driver væk fra implementeringen. Kommentarer lyver. Selv kode kan vildlede, når den læses uden forståelse af hensigten.

Vi havde brug for noget mere eksplicit. Noget, der ikke kunne ignoreres eller fejlfortolkes. Noget, der ville forankre agenter til verificerbar virkelighed.

Vi kalder dem Ground Truths.

Hvad er en Ground Truth?

En Ground Truth er en eksplicit, versioneret faktapåstand, som agenter skal respektere. Det er ikke dokumentation. Det er ikke en kommentar. Det er en førsteklasses entitet i systemet med:

• En unik identifikator (som GT-MAG-015 eller GT-MAG-036)
• En livscyklusstatus (current, tentative eller deprecated)
• Et scope (platformbredt, pakkespecifikt eller domænebundet)
• Evidens (filstier, URL’er eller referencer, der beviser påstanden)
• Agentvejledning (eksplicitte gør/undgå-instruktioner)

Her er et eksempel fra vores 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

Dette er ikke prosa. Det er en kontrakt. Når en agent støder på denne Ground Truth, ved den:

1. Standarden er deterministisk (tomme resultater, ikke uklare gæt)
2. Der findes specifikke parametre (find_similar, exact_match) med definerede adfærd
3. Evidens findes i specifikke filer, der kan verificeres
4. Påstanden blev verificeret på en specifik dato

Anatomien af et Ground Truth Registry

Ground Truths lever i YAML-registre under ai_assets/reference/ground_truths.yaml. Hver pakke eller hvert domæne kan have sit eget register. Strukturen er:

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

Registret inkluderer metadata om selve samlingen, render-konfiguration til dokumentationsgenerering og selve påstandene. Hver påstand følger et strengt skema valideret af Pydantic-modeller:

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

Sådan tilgår agenter Ground Truths

Ground Truths eksponeres gennem flere kanaler:

1. Renderet dokumentation

orkestra sync-kommandoen omdanner YAML-registre til læsbar markdown:

uv run orkestra sync

Dette genererer GROUND_TRUTHS.md-filer, der inkluderes i agentkonteksten. Det renderede output grupperer påstande efter status og kategori:

## 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-søgning

Agenter med shell-adgang kan søge i Ground Truths programmatisk:

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

Søgefunktionen scorer træffere på tværs af flere felter med vægtet relevans:

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

Når agenter renderes fra YAML-definitioner, kan deres kontekst referere til Ground Truth-registre:

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

Dette sikrer, at relevante Ground Truths indlæses, før agenten begynder arbejdet.

Kategorier af Ground Truths

Ser man på tværs af vores registre, klynger Ground Truths sig i flere mønstre:

Produktprincipper

Begrænsninger for, hvad produktet er, og hvad det ikke er:

“Maguyva is read-only with respect to user repositories; the only non-rebuildable asset is the paid embeddings cache.” (GT-MAG-001)

Arkitekturgrænser

Hvor ansvar lever, og hvorfor:

“Pipeline and Maguyva boundaries are intentional: pipeline is reusable, Maguyva holds code-specific logic, and CQRS separates stage writes from server reads.” (GT-MAG-006)

Anti-hallucinationsregler

Eksplicitte mandater, der holder værktøjskontrakter deterministiske i stedet for udledte:

“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.” (GT-MAG-015)

Kvalitetsgates

Standarder, der skal opretholdes:

“Changes to shared infrastructure (post_filters.py, relationship extractors, shared handlers) MUST be validated against ALL supported languages via full manifest generation before commit. A single-language validation is insufficient for shared code.” (GT-MAG-036)

Kodemønstre

Implementeringskrav:

“Use asyncio.to_thread() for CPU-bound work in async contexts; the deprecated loop.run_in_executor() pattern should not be used in new code.” (GT-MAG-018)

Livscyklussen for en Ground Truth

Ground Truths er ikke statiske. De udvikler sig gennem en defineret livscyklus:

Tentative

En foreslået sandhed under evaluering. Påstanden registreres, men kan ændre sig:

- 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

En verificeret sandhed, som agenter skal respektere. Evidens er blevet valideret:

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

Deprecated

En sandhed, der ikke længere gælder. Bevaret som historisk reference med en pointer til, hvad der erstattede den:

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

Hvorfor ikke bare dokumentation?

Dokumentation tjener et andet formål. Den forklarer. Den underviser. Den kan være vag, kan bruge kvalifikatorer som “generelt” eller “typisk.”

Ground Truths kan ikke være vage. De er påstande. De gælder enten, eller også gør de ikke.

Overvej forskellen:

Dokumentation: “API’en returnerer generelt tomme resultater, når et symbol ikke findes, selvom fuzzy matching kan være aktiveret i nogle konfigurationer.”

Ground Truth: “Default behavior returns empty results for non-existent symbols; exact_match=true enforces strict matching and disables all fuzzy fallbacks.”

Den første er nyttig for mennesker, der lærer systemet at kende. Den anden er handlingsorienteret for agenter, der træffer beslutninger.

Agentvejledning: Gør og undgå

Nogle Ground Truths inkluderer eksplicit agentvejledning:

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

Dette fjerner tvetydighed. En agent, der læser dette, ved ikke kun, hvad der er sandt, men også hvilke handlinger den sandhed medfører.

Verificering og vedligeholdelse

Ground Truths kræver vedligeholdelse. Vi sporer:

• last_verified: Hvornår nogen bekræftede, at påstanden stadig holder
• evidence: Filer, der beviser påstanden (kan tjekkes for eksistens)
• source: Hvor sandheden stammer fra (CLI-inspektion, arkitekturgennemgang, læring efter hændelser)

En Ground Truth med forældede verificeringsdatoer eller ødelagte evidenslinks er et signal om at undersøge sagen. Enten er sandheden stadig gyldig og trænger til genverificering, eller også har virkeligheden ændret sig, og sandheden trænger til opdatering.

Reelle eksempler fra produktion

Sikkerhedsgrænse

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

Denne Ground Truth forhindrer en klasse af fejlrettede “sikkerhedsforbedringer”, der ville ødelægge produktet.

Nøjagtighed ved udtrækningstidspunktet

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

Dette kom fra en smertefuld erfaring. Agenter plejede at lappe fejlende sprogpakker ved at tilføje kun-validator-filtre, der fik testharnesset til at se grønnere ud, mens den live Maguyva-udtrækker stadig udsendte de forkerte kanter. Reglen tvinger rettelser tilbage ind på den rigtige sti: YAML-config, forespørgsler eller handlere.

Multi-lags filtrering

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

Dette forhindrer agenter i at tilføje filtre det forkerte sted, en almindelig fejl, der forårsagede nøjagtighedsregressioner.

Integration med orkestreringssystemet

Ground Truths er ét lag i et bredere kontekstsystem:

1. Arkitektoniske beslutninger (ADR’er) - Registrerer hvorfor vi valgte tilgang A frem for B
2. Ground Truths - Angiver hvad der definitivt er sandt lige nu
3. Domænemønstre - Beskriver hvordan man gør tingene korrekt
4. Antimønstre - Beskriver hvad man skal undgå, og hvorfor

En agent, der arbejder i systemet, har adgang til alle fire. Ground Truths giver det faktuelle anker, mens beslutninger forklarer historien, mønstre guider implementeringen, og antimønstre advarer om faldgruber.

Måling af konsekvens

Siden vi introducerede Ground Truths, har vi observeret:

• Færre “ret den hallucinerede rettelse”-cyklusser
• Mere selvsikker agentbeslutningstagning, når fakta er klare
• Bedre PR-gennemgange, fordi forventninger er eksplicitte
• Kortere onboarding-tid for nye agenter (og mennesker)

Investeringen i at vedligeholde Ground Truths betaler sig i form af mindre debugging og klarere systemgrænser.

Kom i gang

For at tilføje en Ground Truth til dit system:

1. Opret en ground_truths.yaml i din pakkes ai_assets/reference/-mappe
2. Definér metadata og render-konfiguration
3. Tilføj påstande, der følger skemaet
4. Kør uv run orkestra sync for at generere dokumentation
5. Inkludér registret i agentens kontekstkomposition

Start med de fakta, der skaber mest forvirring, eller de begrænsninger, der overtrædes oftest. Det er dine mest værdifulde Ground Truths.

Konklusion

AI-agenter vil hallucinere. Det er deres natur. Men vi kan skabe miljøer, hvor hallucination er begrænset, hvor visse fakta er ikke-forhandlelige, hvor agenter kan tjekke deres antagelser mod verificeret virkelighed.

Ground Truths er ikke en komplet løsning. De kræver vedligeholdelse. De kan blive forældede. De tilføjer overhead til udviklingsprocessen.

Men de giver noget værdifuldt: et delt ordforråd af fakta, som både mennesker og agenter kan stole på. I en verden, hvor agenter i stigende grad deltager i softwareudvikling, bliver det delte fundament essentielt.

Alternativet er endeløse cyklusser af agenter, der begår selvsikre fejl, og mennesker, der retter dem. Ground Truths bryder den cyklus ved at gøre rettelserne eksplicitte og holdbare.

Dine agenter fortjener at vide, hvad der er sandt. Fortæl dem det.