Ground Truths: ukotvení AI agentů v realitě

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (leden 2026). Aktuální čísla najdete na naší stránce týmu.

AI agenti jsou pozoruhodně schopní. Umí uvažovat, syntetizovat a generovat. Mají ale zásadní slabinu: vymýšlejí si věci. Ne zlomyslně, ale sebevědomě. Agent si může vymyslet parametry API, které neexistují, odkázat na konfigurace, které nikdy nebyly definované, nebo použít vzorce ze svých trénovacích dat, které odporují vaší skutečné architektuře.

Standardní protilék zní „dej agentovi víc kontextu“. Kontext ale může být protichůdný. Dokumentace se odchyluje od implementace. Komentáře lžou. Dokonce i kód dokáže zmást, když se čte bez pochopení záměru.

Potřebovali jsme něco explicitnějšího. Něco, co se nedá ignorovat ani špatně interpretovat. Něco, co by agenty ukotvilo v ověřitelné realitě.

Říkáme tomu Ground Truths.

Co je Ground Truth?

Ground truth je explicitní, verzované tvrzení faktu, které agenti musí respektovat. Není to dokumentace. Není to komentář. Je to plnohodnotná entita v systému s:

• Unikátním identifikátorem (jako GT-MAG-015 nebo GT-MAG-036)
• Stavem životního cyklu (aktuální, tentativní nebo zastaralý)
• Rozsahem (celoplošný pro platformu, specifický pro balíček, nebo vázaný na doménu)
• Důkazem (cesty k souborům, URL nebo reference, které tvrzení dokládají)
• Vedením pro agenta (explicitní instrukce co dělat a čemu se vyhnout)

Tady je příklad z naší platformy pro code intelligence 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

Tohle není próza. Je to smlouva. Když agent na tuto ground truth narazí, ví:

1. Výchozí chování je deterministické (prázdné výsledky, ne mlhavé odhady)
2. Existují konkrétní parametry (find_similar, exact_match) s definovaným chováním
3. Existují důkazy v konkrétních souborech, které lze ověřit
4. Tvrzení bylo ověřeno k určitému datu

Anatomie registru Ground Truths

Ground truths žijí v YAML registrech pod ai_assets/reference/ground_truths.yaml. Každý balíček nebo doména může mít vlastní registr. Struktura je:

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

Registr obsahuje metadata o samotné kolekci, konfiguraci vykreslení pro generování dokumentace a samotná tvrzení. Každé tvrzení dodržuje přísné schéma validované Pydantic modely:

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

Jak agenti přistupují k Ground Truths

Ground truths jsou vystaveny přes několik kanálů:

1. Vykreslená dokumentace

Příkaz orkestra sync transformuje YAML registry na čitelný markdown:

uv run orkestra sync

Tím vzniknou soubory GROUND_TRUTHS.md, které se zahrnou do kontextu agenta. Vykreslený výstup seskupuje tvrzení podle stavu a kategorie:

## 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 vyhledávání

Agenti s přístupem k shellu mohou ground truths vyhledávat programově:

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

Vyhledávací funkce boduje shody napříč více poli s váženou relevancí:

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

Když jsou agenti vykreslováni z YAML definic, jejich kontext může odkazovat na registry ground truths:

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

Tím je zajištěno, že relevantní ground truths se načtou dřív, než agent začne pracovat.

Kategorie Ground Truths

Když se podíváme napříč našimi registry, ground truths se shlukují do několika vzorců:

Produktové principy

Omezení toho, čím produkt je a čím není:

„Maguyva je vůči repozitářům uživatelů pouze pro čtení; jediné neobnovitelné aktivum je placená cache embeddingů.“ (GT-MAG-001)

Architektonické hranice

Kde bydlí odpovědnosti a proč:

„Hranice mezi pipeline a Maguyva jsou záměrné: pipeline je znovupoužitelná, Maguyva drží logiku specifickou pro kód a CQRS odděluje zápisy stage od čtení serveru.“ (GT-MAG-006)

Pravidla proti halucinacím

Explicitní mandáty, které udržují kontrakty nástrojů deterministickými, ne odvozenými:

„Fuzzy shoda symbolů je opt-in přes find_similar=true. Výchozí chování vrací prázdné výsledky pro neexistující symboly; exact_match=true vynucuje striktní shodu a vypíná všechny fuzzy fallbacky.“ (GT-MAG-015)

Brány kvality

Standardy, které se musí udržovat:

„Změny sdílené infrastruktury (post_filters.py, extraktory vztahů, sdílené handlery) MUSÍ být validovány proti VŠEM podporovaným jazykům přes generování celého manifestu. Validace jednoho jazyka nestačí pro sdílený kód.“ (GT-MAG-036)

Vzorce kódu

Implementační požadavky:

„Pro CPU-náročnou práci v asynchronním kontextu používejte asyncio.to_thread(); zastaralý vzorec loop.run_in_executor() by se v novém kódu neměl používat.“ (GT-MAG-018)

Životní cyklus Ground Truth

Ground truths nejsou statické. Vyvíjejí se skrz definovaný životní cyklus:

Tentativní

Navrhovaná pravda pod vyhodnocením. Tvrzení je zaznamenané, ale může se změnit:

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

Aktuální

Ověřená pravda, kterou agenti musí respektovat. Důkaz byl validován:

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

Zastaralá

Pravda, která už neplatí. Zachovaná pro historickou referenci s odkazem na to, čím byla nahrazena:

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

Proč ne prostě dokumentace?

Dokumentace slouží jinému účelu. Vysvětluje. Učí. Může být vágní, může používat kvalifikátory jako „obecně“ nebo „obvykle“.

Ground truths nemohou být vágní. Jsou to tvrzení. Buď platí, nebo neplatí.

Zvažte ten rozdíl:

Dokumentace: „API obecně vrací prázdné výsledky, když symbol nenajde, i když fuzzy matching může být v některých konfiguracích zapnutý.“

Ground Truth: „Výchozí chování vrací prázdné výsledky pro neexistující symboly; exact_match=true vynucuje striktní shodu a vypíná všechny fuzzy fallbacky.“

První je užitečné pro lidi, kteří se systém učí. Druhé je akceschopné pro agenty, kteří se rozhodují.

Vedení pro agenta: dělej a vyhýbej se

Některé ground truths obsahují explicitní vedení pro agenta:

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

Tím mizí nejednoznačnost. Agent, který tohle čte, ví nejen, co je pravda, ale i to, jaké kroky ta pravda implikuje.

Ověřování a údržba

Ground truths vyžadují údržbu. Sledujeme:

• last_verified: kdy někdo potvrdil, že tvrzení pořád platí
• evidence: soubory, které tvrzení dokládají (lze ověřit jejich existenci)
• source: odkud pravda pochází (inspekce CLI, architektonický review, ponaučení po incidentu)

Ground truth se zastaralým datem ověření nebo rozbitými odkazy na důkazy je signál k prošetření. Buď je pravda pořád platná a potřebuje znovu ověřit, nebo se realita změnila a pravda potřebuje aktualizovat.

Skutečné příklady z provozu

Bezpečnostní hranice

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

Tato ground truth brání třídě zavádějících „bezpečnostních vylepšení“, která by produkt rozbila.

Přesnost v čase extrakce

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

Tohle vzniklo z bolestivé zkušenosti. Agenti opravovali selhávající jazykové balíčky přidáváním filtrů jen na straně validátoru, díky kterým test harness vypadal zeleněji, zatímco živý extraktor Maguyva pořád emitoval špatné hrany. Pravidlo vrací opravy zpátky do skutečné cesty: YAML konfigurace, dotazy nebo handlery.

Vícevrstvé filtrování

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

Tohle brání agentům přidávat filtry na špatné místo, což je běžná chyba, která způsobovala regrese přesnosti.

Integrace s orchestračním systémem

Ground truths jsou jedna vrstva širšího kontextového systému:

1. Architektonická rozhodnutí (ADR) – zaznamenávají, proč jsme zvolili přístup A před B
2. Ground Truths – uvádějí, co je definitivně pravda právě teď
3. Doménové vzorce – popisují, jak věci dělat správně
4. Antivzorce – popisují, čemu se vyhnout a proč

Agent pracující v systému má přístup ke všem čtyřem. Ground truths poskytují faktické ukotvení, rozhodnutí vysvětlují historii, vzorce vedou implementaci a antivzorce varují před nástrahami.

Měření dopadu

Od zavedení ground truths jsme zaznamenali:

• Méně cyklů „oprav tu vyhalucinovanou opravu“
• Sebejistější rozhodování agentů, když jsou fakta jasná
• Lepší review pull requestů, protože očekávání jsou explicitní
• Zkrácenou dobu onboardingu nových agentů (i lidí)

Investice do udržování ground truths se vyplácí ve zmenšeném objemu debugování a jasnějších systémových hranicích.

Jak začít

Chcete-li do svého systému přidat ground truth:

1. Vytvořte ground_truths.yaml v adresáři ai_assets/reference/ svého balíčku
2. Definujte metadata a konfiguraci vykreslení
3. Přidejte tvrzení podle schématu
4. Spusťte uv run orkestra sync pro vygenerování dokumentace
5. Zahrňte registr do skladby kontextu agenta

Začněte s fakty, která způsobují nejvíc zmatku, nebo s omezeními, která se nejčastěji porušují. To jsou vaše nejcennější ground truths.

Závěr

AI agenti budou halucinovat. To je jejich přirozenost. Můžeme ale vytvořit prostředí, kde je halucinace omezená, kde jsou určitá fakta nezpochybnitelná, kde si agenti mohou ověřit své předpoklady proti ověřené realitě.

Ground truths nejsou kompletní řešení. Vyžadují údržbu. Mohou zastarat. Přidávají do vývojového procesu režii.

Poskytují ale něco cenného: sdílenou slovní zásobu faktů, které mohou důvěřovat lidé i agenti. Ve světě, kde se agenti čím dál víc podílejí na vývoji softwaru, se tenhle sdílený základ stává nezbytným.

Alternativou jsou nekonečné cykly agentů, kteří sebevědomě dělají chyby, a lidí, kteří je opravují. Ground truths tenhle cyklus přerušují tím, že opravy dělají explicitní a trvalé.

Vaši agenti si zaslouží vědět, co je pravda. Řekněte jim to.