Ground Truths: tekoälyagenttien ankkurointi todellisuuteen

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso tiimisivumme ajantasaiset luvut.

Tekoälyagentit ovat huomattavan kyvykkäitä. Ne osaavat päätellä, syntetisoida ja generoida. Mutta niillä on perustavanlaatuinen heikkous: ne keksivät asioita. Ei pahantahtoisesti, vaan itsevarmasti. Agentti saattaa keksiä API-parametreja, joita ei ole olemassa, viitata konfiguraatioihin, joita ei koskaan määritelty, tai soveltaa malleja koulutusdatastaan, jotka ovat ristiriidassa todellisen arkkitehtuurisi kanssa.

Vakiokorjaus on “anna agentille lisää kontekstia”. Mutta konteksti voi olla ristiriitainen. Dokumentaatio ajautuu erilleen toteutuksesta. Kommentit valehtelevat. Jopa koodi voi harhauttaa, jos sitä luetaan ymmärtämättä tarkoitusta.

Tarvitsimme jotain eksplisiittisempää. Jotain, mitä ei voisi jättää huomiotta tai tulkita väärin. Jotain, joka ankkuroisi agentit todennettavaan todellisuuteen.

Kutsumme niitä Ground Truthiksi.

Mikä on Ground Truth?

Ground truth on eksplisiittinen, versioitu tosiasiaväite, jota agenttien täytyy kunnioittaa. Se ei ole dokumentaatiota. Se ei ole kommentti. Se on ensiluokkainen entiteetti järjestelmässä, jolla on:

• Yksilöllinen tunniste (kuten GT-MAG-015 tai GT-MAG-036)
• Elinkaaren tila (nykyinen, alustava tai vanhentunut)
• Laajuus (koko alustan kattava, pakettikohtainen tai toimialuesidonnainen)
• Todisteet (tiedostopolut, URL-osoitteet tai viittaukset, jotka todistavat väitteen)
• Agenttiohjeistus (eksplisiittiset tee/vältä-ohjeet)

Tässä on esimerkki Maguyva-koodiälyalustaltamme:

- 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

Tämä ei ole proosaa. Se on sopimus. Kun agentti kohtaa tämän ground truthin, se tietää:

1. Oletusarvo on deterministinen (tyhjät tulokset, ei epämääräisiä arvauksia)
2. On tiettyjä parametreja (find_similar, exact_match) määritellyllä käyttäytymisellä
3. Todisteita on olemassa tietyissä tiedostoissa, jotka voidaan varmentaa
4. Väite varmennettiin tiettynä päivänä

Ground Truth -rekisterin anatomia

Ground truthit elävät YAML-rekistereissä kohdassa ai_assets/reference/ground_truths.yaml. Jokaisella paketilla tai toimialueella voi olla oma rekisterinsä. Rakenne on:

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

Rekisteri sisältää metadataa itse kokoelmasta, renderöintikonfiguraation dokumentaation generointia varten sekä itse väitteet. Jokainen väite noudattaa tiukkaa skeemaa, jonka Pydantic-mallit validoivat:

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

Miten agentit pääsevät käsiksi ground truthiin

Ground truthit paljastetaan useiden kanavien kautta:

1. Renderöity dokumentaatio

Komento orkestra sync muuntaa YAML-rekisterit luettavaksi markdowniksi:

uv run orkestra sync

Tämä generoi GROUND_TRUTHS.md-tiedostoja, jotka sisällytetään agentin kontekstiin. Renderöity tuloste ryhmittelee väitteet tilan ja kategorian mukaan:

## 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-haku

Agentit, joilla on shell-pääsy, voivat hakea ground truthia ohjelmallisesti:

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

Hakufunktio pisteyttää osumat useissa kentissä painotetulla relevanssilla:

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

Kun agentit renderöidään YAML-määrittelyistä, niiden konteksti voi viitata ground truth -rekistereihin:

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

Tämä varmistaa, että relevantit ground truthit ladataan ennen kuin agentti aloittaa työn.

Ground truthien kategoriat

Kun tarkastelemme rekisterejämme, ground truthit ryhmittyvät useisiin malleihin:

Tuoteperiaatteet

Rajoitteet sille, mitä tuote on ja mitä se ei ole:

“Maguyva on kirjoitussuojattu käyttäjän repositorioiden suhteen; ainoa uudelleenrakennuskelvoton resurssi on maksullinen upotuscache.” (GT-MAG-001)

Arkkitehtuurin rajat

Missä vastuut sijaitsevat ja miksi:

“Putken ja Maguyvan rajat ovat tarkoituksellisia: putki on uudelleenkäytettävä, Maguyva pitää sisällään koodikohtaisen logiikan, ja CQRS erottaa vaiheen kirjoitukset palvelimen luvuista.” (GT-MAG-006)

Anti-hallusinaatiosäännöt

Eksplisiittiset toimeksiannot, jotka pitävät työkalusopimukset deterministisinä pääteltyjen sijaan:

“Sumea symbolivastaavuus on opt-in find_similar=true:n kautta. Oletuskäyttäytyminen palauttaa tyhjiä tuloksia olemattomille symboleille; exact_match=true pakottaa tarkan vastaavuuden ja poistaa käytöstä kaikki sumeat varajärjestelyt.” (GT-MAG-015)

Laatuportit

Standardit, joita täytyy ylläpitää:

“Muutokset jaettuun infrastruktuuriin (post_filters.py, suhdepoimijat, jaetut käsittelijät) TÄYTYY validoida KAIKKIA tuettuja kieliä vasten täyden manifestin generoinnilla ennen committia. Yhden kielen validointi ei riitä jaetulle koodille.” (GT-MAG-036)

Koodimallit

Toteutusvaatimukset:

“Käytä asyncio.to_thread() CPU-sidonnaiselle työlle asynkronisissa konteksteissa; vanhentunutta loop.run_in_executor()-mallia ei tule käyttää uudessa koodissa.” (GT-MAG-018)

Ground truthin elinkaari

Ground truthit eivät ole staattisia. Ne kehittyvät määritellyn elinkaaren kautta:

Alustava

Ehdotettu totuus arvioinnin alla. Väite on kirjattu, mutta se saattaa muuttua:

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

Nykyinen

Varmennettu totuus, jota agenttien täytyy kunnioittaa. Todisteet on validoitu:

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

Vanhentunut

Totuus, joka ei enää päde. Säilytetty historiallisena viitteenä osoittimella siihen, mikä sen korvasi:

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

Miksi ei vain dokumentaatiota?

Dokumentaatio palvelee eri tarkoitusta. Se selittää. Se opettaa. Se voi olla epämääräistä, se voi käyttää täsmentäjiä kuten “yleensä” tai “tyypillisesti”.

Ground truthit eivät voi olla epämääräisiä. Ne ovat väitteitä. Ne joko pätevät tai eivät.

Tarkastele eroa:

Dokumentaatio: “API palauttaa yleensä tyhjiä tuloksia, kun symbolia ei löydy, vaikka sumea vastaavuus saattaa olla käytössä joissakin konfiguraatioissa.”

Ground Truth: “Oletuskäyttäytyminen palauttaa tyhjiä tuloksia olemattomille symboleille; exact_match=true pakottaa tarkan vastaavuuden ja poistaa käytöstä kaikki sumeat varajärjestelyt.”

Ensimmäinen on hyödyllinen ihmisille, jotka opettelevat järjestelmää. Toinen on toimintakelpoinen agenteille, jotka tekevät päätöksiä.

Agenttiohjeistus: tee ja vältä

Jotkin ground truthit sisältävät eksplisiittistä agenttiohjeistusta:

- 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ä poistaa epäselvyyden. Tämän lukeva agentti tietää, ei vain mikä on totta, vaan mitä toimia se totuus edellyttää.

Varmennus ja ylläpito

Ground truthit vaativat ylläpitoa. Seuraamme:

• last_verified: milloin joku vahvisti väitteen yhä pätevän
• evidence: tiedostot, jotka todistavat väitteen (voidaan tarkistaa olemassaolon suhteen)
• source: mistä totuus on peräisin (CLI-tarkastus, arkkitehtuurikatselmus, insidentin jälkeinen oppiminen)

Ground truth, jonka varmennuspäivämäärät ovat vanhentuneet tai todistelinkit rikki, on signaali tutkia asiaa. Joko totuus on yhä voimassa ja tarvitsee uudelleenvarmennuksen, tai todellisuus on muuttunut ja totuus tarvitsee päivityksen.

Todellisia esimerkkejä tuotannosta

Turvallisuusraja

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

Tämä ground truth estää luokan harhaanjohtavia “turvallisuusparannuksia”, jotka rikkoisivat tuotteen.

Poiminta-ajan tarkkuus

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

Tämä syntyi tuskallisesta kokemuksesta. Agentit paikkasivat epäonnistuvia kielipaketteja lisäämällä vain validaattorille suunnattuja suodattimia, jotka saivat testivaljaan näyttämään vihreämmältä, kun taas elävä Maguyva-poimija yhä lähetti vääriä reunoja. Sääntö pakottaa korjaukset takaisin todelliselle polulle: YAML-konfiguraatioon, kyselyihin tai käsittelijöihin.

Monitasoinen suodatus

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

Tämä estää agentteja lisäämästä suodattimia väärään paikkaan, mikä on yleinen virhe, joka aiheutti tarkkuusregressioita.

Integrointi orkestrointijärjestelmään

Ground truthit ovat yksi kerros laajemmassa kontekstijärjestelmässä:

1. Arkkitehtoniset päätökset (ADR:t) - kirjaavat, miksi valitsimme lähestymistavan A tavan B sijaan
2. Ground Truthit - toteavat, mikä on ehdottomasti totta juuri nyt
3. Toimialuemallit - kuvaavat, miten asiat tehdään oikein
4. Anti-mallit - kuvaavat, mitä välttää ja miksi

Järjestelmässä työskentelevällä agentilla on pääsy kaikkiin neljään. Ground truthit tarjoavat tosiasiallisen ankkurin, kun taas päätökset selittävät historiaa, mallit ohjaavat toteutusta ja anti-mallit varoittavat sudenkuopista.

Vaikutuksen mittaaminen

Ground truthien käyttöönoton jälkeen olemme havainneet:

• Vähemmän “korjaa hallusinoitu korjaus” -kiertoja
• Itsevarmempaa agentin päätöksentekoa, kun tosiasiat ovat selkeitä
• Parempia PR-katselmuksia, koska odotukset ovat eksplisiittisiä
• Lyhentynyt perehdytysaika uusille agenteille (ja ihmisille)

Ground truthien ylläpitoon investoiminen maksaa itsensä takaisin vähentyneenä vianetsintänä ja selkeämpinä järjestelmärajoina.

Aloittaminen

Ground truthin lisäämiseksi järjestelmääsi:

1. Luo ground_truths.yaml pakettisi ai_assets/reference/-hakemistoon
2. Määrittele metadata ja renderöintikonfiguraatio
3. Lisää väitteet skeeman mukaisesti
4. Aja uv run orkestra sync dokumentaation generoimiseksi
5. Sisällytä rekisteri agentin kontekstin kokoonpanoon

Aloita tosiasioista, jotka aiheuttavat eniten sekaannusta, tai rajoitteista, joita rikotaan useimmin. Ne ovat arvokkaimmat ground truthisi.

Yhteenveto

Tekoälyagentit tulevat hallusinoimaan. Se on niiden luonto. Mutta voimme luoda ympäristöjä, joissa hallusinaatio on rajoitettua, joissa tietyt tosiasiat ovat neuvottelemattomia, joissa agentit voivat tarkistaa oletuksensa varmennettua todellisuutta vasten.

Ground truthit eivät ole täydellinen ratkaisu. Ne vaativat ylläpitoa. Ne voivat vanhentua. Ne lisäävät yleiskustannuksia kehitysprosessiin.

Mutta ne tarjoavat jotain arvokasta: jaetun tosiasioiden sanaston, johon sekä ihmiset että agentit voivat luottaa. Maailmassa, jossa agentit osallistuvat yhä enemmän ohjelmistokehitykseen, tuosta jaetusta perustasta tulee välttämätön.

Vaihtoehto on loputon kierto agenteista, jotka tekevät itsevarmoja virheitä, ja ihmisistä, jotka korjaavat ne. Ground truthit katkaisevat tuon kierron tekemällä korjauksista eksplisiittisiä ja pysyviä.

Agenttisi ansaitsevat tietää, mikä on totta. Kerro heille.