Grundsanningar: att förankra AI-agenter i verkligheten

Siffrorna i det här inlägget speglar systemet vid publicering (januari 2026). Se vår teamsida för aktuella siffror.

AI-agenter är anmärkningsvärt kapabla. De kan resonera, syntetisera och generera. Men de har en grundläggande svaghet: de hittar på saker. Inte illvilligt, men med självförtroende. En agent kan uppfinna API-parametrar som inte existerar, referera till konfigurationer som aldrig definierats, eller tillämpa mönster från sin träningsdata som strider mot din faktiska arkitektur.

Standardåtgärden är “ge agenten mer kontext”. Men kontext kan vara motsägelsefull. Dokumentation glider isär från implementationen. Kommentarer ljuger. Även kod kan vilseleda om den läses utan att man förstår avsikten.

Vi behövde något mer explicit. Något som inte kunde ignoreras eller misstolkas. Något som skulle förankra agenter i verifierbar verklighet.

Vi kallar dem Grundsanningar.

Vad är en grundsanning?

En grundsanning är ett explicit, versionshanterat sakpåstående som agenter måste respektera. Det är inte dokumentation. Det är inte en kommentar. Det är en förstklassig entitet i systemet med:

• En unik identifierare (som GT-MAG-015 eller GT-MAG-036)
• En livscykelstatus (aktuell, preliminär eller utfasad)
• Ett scope (plattformsomfattande, paketspecifikt eller domänbundet)
• Bevis (filsökvägar, URL:er eller referenser som styrker påståendet)
• Agentvägledning (explicita gör/undvik-instruktioner)

Här är ett exempel från vår Maguyva-kodintelligensplattform:

- 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

Det här är inte löpande text. Det är ett kontrakt. När en agent stöter på den här grundsanningen vet den:

1. Standardbeteendet är deterministiskt (tomma resultat, inte luddiga gissningar)
2. Det finns specifika parametrar (find_similar, exact_match) med definierade beteenden
3. Bevis finns i specifika filer som kan verifieras
4. Påståendet verifierades ett specifikt datum

Anatomin hos ett grundsanningsregister

Grundsanningar lever i YAML-register under ai_assets/reference/ground_truths.yaml. Varje paket eller domän kan ha sitt eget register. Strukturen är:

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 innehåller metadata om själva samlingen, renderingskonfiguration för dokumentationsgenerering, och själva påståendena. Varje påstående följer ett strikt schema som valideras av 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

Hur agenter kommer åt grundsanningar

Grundsanningar exponeras genom flera kanaler:

1. Renderad dokumentation

Kommandot orkestra sync omvandlar YAML-register till läsbar markdown:

uv run orkestra sync

Det här genererar GROUND_TRUTHS.md-filer som ingår i agentens kontext. Den renderade utdatan grupperar påståenden efter status och 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ökning

Agenter med skalåtkomst kan söka i grundsanningar programmatiskt:

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ökfunktionen poängsätter träffar över flera fält med viktad 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. Kontextkomposition

När agenter renderas från YAML-definitioner kan deras kontext referera till grundsanningsregister:

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

Det säkerställer att relevanta grundsanningar laddas innan agenten börjar arbeta.

Kategorier av grundsanningar

Om man tittar över våra register klustrar sig grundsanningarna i flera mönster:

Produktprinciper

Begränsningar för vad produkten är och inte är:

“Maguyva är skrivskyddat gentemot användarrepositorier; den enda tillgången som inte kan återskapas är den betalda inbäddningscachen.” (GT-MAG-001)

Arkitekturgränser

Var ansvar ligger och varför:

“Gränserna mellan pipeline och Maguyva är avsiktliga: pipeline är återanvändbar, Maguyva innehåller kodspecifik logik, och CQRS separerar stegskrivningar från serverläsningar.” (GT-MAG-006)

Regler mot hallucinationer

Explicita mandat som håller verktygskontrakt deterministiska istället för härledda:

“Luddig symbolmatchning är opt-in via find_similar=true. Standardbeteendet returnerar tomma resultat för symboler som inte existerar; exact_match=true tvingar fram strikt matchning och inaktiverar alla luddiga fallbacks.” (GT-MAG-015)

Kvalitetsgrindar

Standarder som måste upprätthållas:

“Ändringar av delad infrastruktur (post_filters.py, relationsextraktorer, delade hanterare) MÅSTE valideras mot ALLA språk som stöds via fullständig manifestgenerering före commit. En enspråkig validering räcker inte för delad kod.” (GT-MAG-036)

Kodmönster

Implementationskrav:

“Använd asyncio.to_thread() för CPU-bundet arbete i asynkrona kontexter; det utfasade mönstret loop.run_in_executor() bör inte användas i ny kod.” (GT-MAG-018)

Livscykeln hos en grundsanning

Grundsanningar är inte statiska. De utvecklas genom en definierad livscykel:

Preliminär

En föreslagen sanning under utvärdering. Påståendet är registrerat men kan komma att ändras:

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

Aktuell

En verifierad sanning som agenter måste respektera. Beviset har validerats:

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

Utfasad

En sanning som inte längre gäller. Behålls som historisk referens med en pekare till vad som ersatte den:

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

Varför inte bara dokumentation?

Dokumentation tjänar ett annat syfte. Den förklarar. Den undervisar. Den kan vara vag, kan använda kvalificerare som “generellt” eller “vanligtvis”.

Grundsanningar kan inte vara vaga. De är påståenden. De gäller antingen eller så gör de inte det.

Betrakta skillnaden:

Dokumentation: “API:et returnerar generellt tomma resultat när en symbol inte hittas, även om luddig matchning kan vara aktiverad i vissa konfigurationer.”

Grundsanning: “Standardbeteendet returnerar tomma resultat för symboler som inte existerar; exact_match=true tvingar fram strikt matchning och inaktiverar alla luddiga fallbacks.”

Den första är till hjälp för människor som lär sig systemet. Den andra är handlingsbar för agenter som fattar beslut.

Agentvägledning: gör och undvik

Vissa grundsanningar innehåller explicit agentvägledning:

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

Det tar bort tvetydighet. En agent som läser det här vet inte bara vad som är sant, utan vilka handlingar den sanningen medför.

Verifiering och underhåll

Grundsanningar kräver underhåll. Vi spårar:

• last_verified: När någon bekräftade att påståendet fortfarande gäller
• evidence: Filer som styrker påståendet (kan kontrolleras för existens)
• source: Var sanningen ursprungligen kom ifrån (CLI-inspektion, arkitekturgranskning, lärdom efter en incident)

En grundsanning med föråldrade verifieringsdatum eller trasiga bevislänkar är en signal att undersöka. Antingen är sanningen fortfarande giltig och behöver omverifieras, eller så har verkligheten förändrats och sanningen behöver uppdateras.

Verkliga exempel från produktion

Säkerhetsgräns

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

Den här grundsanningen förhindrar en klass av missriktade “säkerhetsförbättringar” som skulle förstöra produkten.

Noggrannhet vid extraktionstillfället

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

Det här kom från smärtsam erfarenhet. Agenter brukade lappa ihop misslyckade språkpaket genom att lägga till filter som bara påverkade validatorn och fick testställningen att se grönare ut, medan den skarpa Maguyva-extraktorn fortfarande avgav fel kanter. Regeln tvingar tillbaka fixar till den verkliga vägen: YAML-konfiguration, queries eller hanterare.

Filtrering i flera nivåer

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

Det här förhindrar att agenter lägger till filter på fel ställe, ett vanligt misstag som orsakade noggrannhetsregressioner.

Integration med orkestreringssystemet

Grundsanningar är ett lager i ett bredare kontextsystem:

1. Arkitektoniska beslut (ADR:er) – Registrerar varför vi valde metod A framför B
2. Grundsanningar – Anger vad som är definitivt sant just nu
3. Domänmönster – Beskriver hur man gör saker rätt
4. Antimönster – Beskriver vad man ska undvika och varför

En agent som arbetar i systemet har tillgång till alla fyra. Grundsanningar utgör den faktabaserade förankringen, medan beslut förklarar historien, mönster vägleder implementationen och antimönster varnar för fallgropar.

Att mäta effekten

Sedan vi introducerade grundsanningar har vi observerat:

• Färre cykler av “fixa den hallucinerade fixen”
• Säkrare agentbeslut när fakta är tydliga
• Bättre PR-granskningar eftersom förväntningarna är explicita
• Kortare onboardingtid för nya agenter (och människor)

Investeringen i att underhålla grundsanningar betalar sig i minskad felsökning och tydligare systemgränser.

Komma igång

För att lägga till en grundsanning i ditt system:

1. Skapa en ground_truths.yaml i ditt pakets ai_assets/reference/-katalog
2. Definiera metadata och renderingskonfiguration
3. Lägg till påståenden enligt schemat
4. Kör uv run orkestra sync för att generera dokumentation
5. Inkludera registret i agentens kontextkomposition

Börja med de fakta som orsakar mest förvirring, eller de begränsningar som bryts mot oftast. Det är dina mest värdefulla grundsanningar.

Slutsats

AI-agenter kommer att hallucinera. Det ligger i deras natur. Men vi kan skapa miljöer där hallucination begränsas, där vissa fakta inte är förhandlingsbara, där agenter kan pröva sina antaganden mot verifierad verklighet.

Grundsanningar är inte en fullständig lösning. De kräver underhåll. De kan bli föråldrade. De lägger till overhead i utvecklingsprocessen.

Men de ger något värdefullt: ett delat vokabulär av fakta som både människor och agenter kan lita på. I en värld där agenter i allt högre grad deltar i mjukvaruutveckling blir den gemensamma grunden avgörande.

Alternativet är oändliga cykler av agenter som gör självsäkra misstag och människor som rättar till dem. Grundsanningar bryter den cykeln genom att göra rättelserna explicita och varaktiga.

Dina agenter förtjänar att veta vad som är sant. Berätta det för dem.