Mga Batayang Katotohanan: Pag-anchor ng mga AI Agent sa Realidad

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Enero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Talagang mahusay ang mga AI agent. Kaya nilang mangatwiran, mag-synthesize, at gumawa. Pero may fundamental na kahinaan sila: nanggagawa-gawa sila ng mga bagay. Hindi dahil may masamang intensyon, kundi confidenteng ginagawa nila ito. Puwedeng mag-imbento ang isang agent ng mga API parameter na wala talaga, mag-reference ng mga configuration na hindi naman na-define, o mag-apply ng mga pattern mula sa training data nito na sumasalungat sa totoong architecture mo.

Ang standard na solusyon, “bigyan ang agent ng mas maraming context.” Pero puwedeng magkasalungat ang context. Lumalayo ang documentation mula sa implementation. Nagsisinungaling ang mga comment. Kahit ang code, puwedeng makapagligaw kung babasahin nang walang pag-unawa sa intent.

Kailangan namin ng mas explicit na bagay. Isang bagay na hindi maaaring balewalain o maling maintindihan. Isang bagay na mag-a-anchor sa mga agent papunta sa napatunayang realidad.

Tinatawag namin itong mga batayang katotohanan.

Ano ang isang Ground Truth?

Ang isang ground truth ay isang explicit, versioned na pahayag ng katotohanan na dapat igalang ng mga agent. Hindi ito documentation. Hindi ito isang comment. Ito ay isang first-class entity sa system na may:

• Isang unique identifier (tulad ng GT-MAG-015 o GT-MAG-036)
• Isang lifecycle status (current, tentative, o deprecated)
• Isang scope (platform-wide, package-specific, o domain-bound)
• Evidence (mga file path, URL, o reference na nagpapatunay sa pahayag)
• Agent guidance (explicit na do/avoid na mga instruction)

Narito ang isang halimbawa mula sa aming 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

Hindi ito prose. Isa itong kontrata. Kapag naranasan ng isang agent ang ground truth na ito, alam nito:

1. Deterministic ang default (walang laman na resulta, hindi fuzzy na hula)
2. May mga specific na parameter (find_similar, exact_match) na may defined na behavior
3. May ebidensyang nasa mga specific na file na puwedeng ma-verify
4. Na-verify ang pahayag sa isang specific na petsa

Ang Anatomiya ng isang Ground Truth Registry

Nakatira ang mga ground truth sa mga YAML registry sa ilalim ng ai_assets/reference/ground_truths.yaml. Bawat package o domain, puwedeng may sariling registry. Ganito ang structure:

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

Kasama sa registry ang metadata tungkol sa koleksyon mismo, render configuration para sa pagbuo ng documentation, at ang mga pahayag mismo. Bawat pahayag ay sumusunod sa isang mahigpit na schema na na-validate ng mga Pydantic model:

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

Paano nag-a-access ang mga agent sa mga batayang katotohanan

Ini-expose ang mga ground truth sa iba’t ibang channel:

1. Naka-render na Dokumentasyon

Ginagawa ng command na orkestra sync ang mga YAML registry papunta sa mababasang markdown:

uv run orkestra sync

Nagbubunga ito ng mga file na GROUND_TRUTHS.md na kasama sa agent context. Ini-group ng rendered output ang mga pahayag ayon sa status at kategorya:

## 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. Paghahanap sa CLI

Puwedeng mag-search ang mga agent na may shell access ng ground truths nang programmatic:

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

Nagbibigay ng score ang search function sa mga match sa iba’t ibang field gamit ang weighted relevance:

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. Komposisyon ng Konteksto

Kapag rendered ang mga agent mula sa mga YAML definition, puwedeng mag-reference ang context nila sa mga ground truth registry:

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

Sinisiguro nito na nakaload na ang mga relevant na ground truth bago magsimula ng trabaho ang agent.

Mga Kategorya ng mga batayang katotohanan

Kapag tiningnan ang aming mga registry, nag-cluster ang mga ground truth sa ilang pattern:

Mga prinsipyo ng produkto

Mga hangganan sa kung ano ang produkto at kung ano ito hindi:

“Read-only ang Maguyva pagdating sa mga repository ng user; ang tanging non-rebuildable na asset ay ang paid embeddings cache.” (GT-MAG-001)

Mga Hangganan ng Arkitektura

Saan nakatira ang mga responsibilidad at bakit:

“Sinadya ang mga hangganan ng pipeline at Maguyva: reusable ang pipeline, hawak ng Maguyva ang code-specific na logic, at ihinihiwalay ng CQRS ang stage writes mula sa server reads.” (GT-MAG-006)

Mga tuntunin laban sa hallucination

Explicit na mandato na nagpapanatiling deterministic sa halip na inferred ang mga tool contract:

“Opt-in ang fuzzy symbol matching sa pamamagitan ng find_similar=true. Nagbabalik ang default na behavior ng walang laman na resulta para sa mga hindi umiiral na symbol; pinapatupad ng exact_match=true ang strict matching at dini-disable ang lahat ng fuzzy fallback.” (GT-MAG-015)

Mga gate ng kalidad

Mga standard na kailangang mapanatili:

“Ang mga pagbabago sa shared infrastructure (post_filters.py, relationship extractors, shared handlers) AY DAPAT ma-validate laban sa LAHAT ng suportadong wika sa pamamagitan ng full manifest generation bago mag-commit. Hindi sapat ang single-language validation para sa shared code.” (GT-MAG-036)

Mga Pattern ng Code

Mga implementation requirement:

“Gamitin ang asyncio.to_thread() para sa CPU-bound na trabaho sa async contexts; hindi dapat gamitin ang deprecated na pattern na loop.run_in_executor() sa bagong code.” (GT-MAG-018)

Ang Lifecycle ng isang Ground Truth

Hindi static ang mga ground truth. Umuunlad sila sa pamamagitan ng isang defined na lifecycle:

Tentatibo

Isang iminumungkahing katotohanan na sinusuri pa. Naitala ang pahayag pero puwede pa itong magbago:

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

Kasalukuyan

Isang na-verify na katotohanan na dapat igalang ng mga agent. Na-validate na ang ebidensya:

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

Deprecated (Hindi na Ginagamit)

Isang katotohanan na hindi na umaapply. Iniingatan para sa historical reference kasama ang pointer sa pumalit dito:

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

Bakit Hindi Documentation na Lang?

Ibang layunin ang pinaglilingkuran ng documentation. Nagpapaliwanag ito. Nagtuturo ito. Puwede itong maging vague, puwedeng gumamit ng mga qualifier tulad ng “generally” o “typically.”

Hindi puwedeng maging vague ang mga ground truth. Mga assertion sila. Umaapply sila o hindi.

Tingnan ang pagkakaiba:

Documentation: “Karaniwang nagbabalik ang API ng walang laman na resulta kapag hindi nahanap ang isang symbol, bagaman puwedeng naka-enable ang fuzzy matching sa ilang configuration.”

Ground Truth: “Nagbabalik ang default na behavior ng walang laman na resulta para sa mga hindi umiiral na symbol; pinapatupad ng exact_match=true ang strict matching at dini-disable ang lahat ng fuzzy fallback.”

Ang una, kapaki-pakinabang para sa mga taong natututo sa system. Ang ikalawa, actionable para sa mga agent na gumagawa ng desisyon.

Agent Guidance: Gawin at Iwasan

May kasamang explicit na agent guidance ang ilang ground truth:

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

Tinatanggal nito ang ambiguity. Kapag binasa ito ng isang agent, alam nito hindi lang kung ano ang totoo, kundi pati kung anong aksyon ang ipinapahiwatig ng katotohanang iyon.

Verification at Maintenance

Kailangan ng maintenance ang mga ground truth. Sinusubaybayan namin:

• last_verified: Kailan may nagkumpirma na may bisa pa rin ang pahayag
• evidence: Mga file na nagpapatunay sa pahayag (puwedeng ma-check kung umiiral)
• source: Saan nagmula ang katotohanan (CLI inspection, architecture review, post-incident learning)

Ang isang ground truth na may lumang verification date o sirang evidence link, isang senyales na dapat imbestigahan. Alinman, may bisa pa rin ang katotohanan at kailangan lang ng re-verification, o nagbago na ang realidad at kailangang i-update ang katotohanan.

Mga Tunay na Halimbawa Mula sa Production

Hangganan ng seguridad

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

Pinipigilan ng ground truth na ito ang isang klase ng maling-akalang “security improvements” na sisira sa produkto.

Katumpakan sa oras ng extraction

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

Nagmula ito sa masakit na karanasan. Nagta-tapal ang mga agent ng mga nabibigong language pack sa pamamagitan ng pagdagdag ng validator-only na filter na nagpapaganda lang sa itsura ng test harness, habang ang live Maguyva extractor ay tuloy pa ring naglalabas ng maling edges. Pinipilit ng tuntunin na ibalik ang mga fix sa totoong path: YAML config, queries, o handlers.

Multi-tier na pagsala

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

Pinipigilan nito ang mga agent na magdagdag ng filter sa maling lugar, isang karaniwang pagkakamali na nagdulot ng accuracy regressions.

Integration sa Orchestration System

Isang layer lang ang ground truths sa mas malawak na context system:

1. Mga desisyon sa arkitektura (ADRs) - Naitatala kung bakit pinili ang approach A kaysa sa B
2. Mga batayang katotohanan - Sinasabi kung ano ang tiyak na totoo ngayon
3. Domain Patterns - Inilalarawan kung paano gawin nang tama ang mga bagay
4. Anti-Patterns - Inilalarawan kung ano ang iwasan at bakit

May access ang isang agent na nagtatrabaho sa system sa lahat ng apat. Ang ground truths ang nagbibigay ng factual anchor, habang ipinapaliwanag ng mga desisyon ang kasaysayan, ginagabayan ng mga pattern ang implementation, at binababalaan ng mga anti-pattern ang mga posibleng patibong.

Pagsukat ng Impact

Mula nang ipinakilala ang ground truths, naobserbahan namin:

• Mas kaunting “ayusin ang hinallucinate na fix” na cycle
• Mas confident na desisyon ng agent kapag malinaw ang mga katotohanan
• Mas magandang PR review dahil explicit ang mga inaasahan
• Mas maikling onboarding time para sa mga bagong agent (at mga tao)

Nagbabayad ang investment sa pagpapanatili ng ground truths sa pamamagitan ng mas kaunting debugging at mas malinaw na system boundaries.

Pagsisimula

Para magdagdag ng ground truth sa system mo:

1. Gumawa ng ground_truths.yaml sa loob ng directory ng package mo na ai_assets/reference/
2. I-define ang metadata at render configuration
3. Magdagdag ng mga pahayag na sumusunod sa schema
4. Patakbuhin ang uv run orkestra sync para bumuo ng documentation
5. Isama ang registry sa agent context composition

Simulan sa mga katotohanan na nagdudulot ng pinakamaraming kalituhan o sa mga hangganan na pinakamadalas nilalabag. Iyon ang mga pinakamahalagang ground truth mo.

Konklusyon

Mag-hahallucinate ang mga AI agent. Iyon ang kalikasan nila. Pero puwede kaming gumawa ng mga environment kung saan pinaghihigpitan ang hallucination, kung saan hindi na napag-uusapan ang ilang katotohanan, kung saan puwedeng i-check ng mga agent ang mga assumption nila laban sa napatunayang realidad.

Hindi kumpletong solusyon ang ground truths. Kailangan nila ng maintenance. Puwede silang maging luma. Nagdaragdag sila ng overhead sa development process.

Pero nagbibigay sila ng mahalagang bagay: isang shared vocabulary ng mga katotohanan na puwedeng pagkatiwalaan ng parehong tao at agent. Sa isang mundo kung saan lalo nang sumasali ang mga agent sa software development, nagiging mahalaga ang shared foundation na iyon.

Ang alternatibo, walang katapusang cycle ng mga agent na confidenteng nagkakamali at mga taong nagtatama nito. Sinisira ng ground truths ang cycle na iyon sa pamamagitan ng paggawang explicit at matatag sa mga pagwawasto.

Karapat-dapat malaman ng mga agent mo kung ano ang totoo. Sabihin mo sa kanila.