# Grundsanningar: att förankra AI-agenter i verkligheten Canonical source: https://maguyva.ai/sv/blog/ground-truths-anchoring-ai-to-reality License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license). Date: 2026-01-13 · Author: Maguyva Team > AI-agenter hallucinerar med självförtroende. Grundsanningar är versionshanterade, avgränsade fakta som förankrar agentbeteende i verkligheten. Så här byggde och upprätthåller vi dem. > *Siffrorna i det här inlägget speglar systemet vid publicering (januari 2026). Se vår [teamsida](/sv/team) 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 sina 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: ```yaml - 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 gissningar baserade på ungefärlig matchning) 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: ```yaml 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: ```python 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: ```bash 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: ```markdown ## 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: ```bash uv run orkestra registry truths search "embedding" uv run orkestra registry truths search --tag security uv run orkestra registry truths list --status current ``` Sökfunktionen poängsätter träffar över flera fält med viktad relevans: ```python 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: ```yaml 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 grupperar 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: > "Ungefärlig 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 reservalternativ med ungefärlig matchning." (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: ```yaml - 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: ```yaml - 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: ```yaml - 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 ungefärlig 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 reservalternativ med ungefärlig matchning." Den första är till hjälp för människor som lär sig systemet. Den andra går att omsätta i handling för agenter som fattar beslut. ## Agentvägledning: gör och undvik Vissa grundsanningar innehåller explicit agentvägledning: ```yaml - 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 ```yaml - 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 ```yaml - 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 testmiljön att se grönare ut, medan den skarpa Maguyva-extraktorn fortfarande producerade felaktiga kanter. Regeln tvingar tillbaka fixar till den verkliga vägen: YAML-konfiguration, queries eller hanterare. ### Filtrering i flera nivåer ```yaml - 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 försämrade precisionen. ## 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 gemensamt ordförråd 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.