Ground Truths: Menambatkan Ejen AI kepada Realiti

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Januari 2026). Lihat halaman pasukan kami untuk angka terkini.

Ejen AI amat berkebolehan. Mereka boleh menaakul, mensintesis, dan menjana. Tetapi mereka mempunyai satu kelemahan asasi: mereka mereka-reka perkara. Bukan dengan niat jahat, tetapi dengan penuh keyakinan. Seorang ejen mungkin mencipta parameter API yang tidak wujud, merujuk konfigurasi yang tidak pernah ditakrifkan, atau menggunakan corak daripada data latihannya yang bercanggah dengan seni bina sebenar anda.

Mitigasi piawai ialah “beri ejen lebih banyak konteks.” Tetapi konteks boleh bercanggah. Dokumentasi menyimpang daripada pelaksanaan. Komen menipu. Malah kod pun boleh mengelirukan apabila dibaca tanpa memahami niat.

Kami memerlukan sesuatu yang lebih eksplisit. Sesuatu yang tidak boleh diabaikan atau disalahtafsir. Sesuatu yang dapat menambatkan ejen kepada realiti yang boleh disahkan.

Kami menamakannya Ground Truths.

Apakah itu Ground Truth?

Satu Ground Truth adalah pernyataan fakta yang eksplisit dan berversi yang mesti dihormati oleh ejen. Ia bukan dokumentasi. Ia bukan komen. Ia adalah entiti kelas pertama dalam sistem dengan:

• Pengecam unik (seperti GT-MAG-015 atau GT-MAG-036)
• Status lifecycle (current, tentative, atau deprecated)
• Skop (seluruh platform, khusus package, atau terikat domain)
• Bukti (laluan fail, URL, atau rujukan yang membuktikan pernyataan itu)
• Panduan ejen (arahan do/avoid yang eksplisit)

Berikut contoh daripada platform code intelligence Maguyva kami:

- 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

Ini bukan prosa. Ia adalah kontrak. Apabila seorang ejen bertemu dengan Ground Truth ini, ia tahu:

1. Lalai adalah deterministik (hasil kosong, bukan tekaan kabur)
2. Terdapat parameter khusus (find_similar, exact_match) dengan gelagat yang ditakrifkan
3. Bukti wujud dalam fail khusus yang boleh disahkan
4. Pernyataan itu telah disahkan pada tarikh tertentu

Anatomi Registri Ground Truth

Ground Truths hidup dalam registri YAML di bawah ai_assets/reference/ground_truths.yaml. Setiap package atau domain boleh mempunyai registrinya sendiri. Strukturnya ialah:

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

Registri itu merangkumi metadata tentang koleksi itu sendiri, konfigurasi render untuk penjanaan dokumentasi, dan pernyataan itu sendiri. Setiap pernyataan mengikuti skema ketat yang disahkan oleh model Pydantic:

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

Bagaimana Ejen Mencapai Ground Truths

Ground Truths didedahkan menerusi pelbagai saluran:

1. Dokumentasi Yang Dirender

Arahan orkestra sync mengubah registri YAML kepada markdown yang boleh dibaca:

uv run orkestra sync

Ini menjana fail GROUND_TRUTHS.md yang disertakan dalam konteks ejen. Output yang dirender mengumpulkan pernyataan mengikut status dan 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. Carian CLI

Ejen dengan akses shell boleh mencari Ground Truths secara programatik:

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

Fungsi carian itu memberi skor kepada padanan merentasi pelbagai medan dengan relevans berpemberat:

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

Apabila ejen dirender daripada takrifan YAML, konteks mereka boleh merujuk registri Ground Truth:

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

Ini memastikan Ground Truths yang relevan dimuatkan sebelum ejen memulakan kerja.

Kategori Ground Truths

Melihat merentasi registri kami, Ground Truths berkumpul kepada beberapa corak:

Prinsip Produk

Kekangan tentang apa produk itu dan apa yang bukan:

“Maguyva bersifat baca-sahaja berhubung repositori pengguna; satu-satunya aset yang tidak boleh dibina semula ialah cache embeddings berbayar.” (GT-MAG-001)

Sempadan Seni Bina

Di mana tanggungjawab berada dan mengapa:

“Sempadan antara pipeline dan Maguyva adalah sengaja: pipeline boleh digunakan semula, Maguyva memegang logik khusus kod, dan CQRS memisahkan penulisan stage daripada bacaan server.” (GT-MAG-006)

Peraturan Anti-Halusinasi

Mandat eksplisit yang mengekalkan kontrak tool bersifat deterministik dan bukan diandaikan:

“Padanan simbol fuzzy adalah opt-in menerusi find_similar=true. Gelagat lalai memulangkan hasil kosong untuk simbol yang tidak wujud; exact_match=true menguatkuasakan padanan ketat dan melumpuhkan semua fallback fuzzy.” (GT-MAG-015)

Gate Kualiti

Piawaian yang mesti dikekalkan:

“Perubahan kepada infrastruktur kongsi (post_filters.py, relationship extractor, handler kongsi) MESTI disahkan terhadap SEMUA bahasa yang disokong menerusi penjanaan manifest penuh sebelum commit. Pengesahan satu bahasa sahaja tidak mencukupi untuk kod kongsi.” (GT-MAG-036)

Corak Kod

Keperluan pelaksanaan:

“Gunakan asyncio.to_thread() untuk kerja terikat-CPU dalam konteks async; corak loop.run_in_executor() yang deprecated tidak sepatutnya digunakan dalam kod baharu.” (GT-MAG-018)

Lifecycle Sesuatu Ground Truth

Ground Truths tidak statik. Ia berkembang menerusi lifecycle yang ditakrifkan:

Tentative

Satu kebenaran yang dicadangkan sedang dinilai. Pernyataan itu direkodkan tetapi mungkin berubah:

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

Current

Satu kebenaran yang disahkan yang mesti dihormati oleh ejen. Bukti telah disahkan:

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

Deprecated

Satu kebenaran yang tidak lagi terpakai. Disimpan untuk rujukan sejarah dengan penunjuk kepada apa yang menggantikannya:

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

Mengapa Bukan Sekadar Dokumentasi?

Dokumentasi berkhidmat untuk tujuan yang berbeza. Ia menjelaskan. Ia mengajar. Ia boleh kabur, boleh menggunakan pengubah suai seperti “secara umum” atau “biasanya.”

Ground Truths tidak boleh kabur. Ia adalah dakwaan. Ia sama ada terpakai atau tidak.

Pertimbangkan perbezaannya:

Dokumentasi: “API secara umum memulangkan hasil kosong apabila simbol tidak dijumpai, walaupun padanan fuzzy mungkin diaktifkan dalam sesetengah konfigurasi.”

Ground Truth: “Gelagat lalai memulangkan hasil kosong untuk simbol yang tidak wujud; exact_match=true menguatkuasakan padanan ketat dan melumpuhkan semua fallback fuzzy.”

Yang pertama berguna untuk manusia yang sedang mempelajari sistem. Yang kedua boleh ditindaki oleh ejen yang membuat keputusan.

Panduan Ejen: Do dan Avoid

Sesetengah Ground Truths merangkumi panduan ejen yang eksplisit:

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

Ini menghapuskan kekaburan. Seorang ejen yang membaca ini tahu bukan sahaja apa yang benar, tetapi tindakan apa yang tersirat oleh kebenaran itu.

Pengesahan dan Penyenggaraan

Ground Truths memerlukan penyenggaraan. Kami menjejaki:

• last_verified: Bila seseorang mengesahkan pernyataan itu masih terpakai
• evidence: Fail yang membuktikan pernyataan itu (boleh disemak kewujudannya)
• source: Dari mana kebenaran itu berasal (pemeriksaan CLI, semakan seni bina, pembelajaran pasca-insiden)

Sesuatu Ground Truth dengan tarikh pengesahan yang basi atau pautan bukti yang rosak adalah isyarat untuk disiasat. Sama ada kebenaran itu masih sah dan memerlukan pengesahan semula, atau realiti telah berubah dan kebenaran itu memerlukan kemas kini.

Contoh Sebenar Daripada Pengeluaran

Sempadan Keselamatan

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

Ground Truth ini menghalang satu kelas “penambahbaikan keselamatan” yang tersasar yang akan merosakkan produk.

Ketepatan Masa-Pengekstrakan

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

Ini datang daripada pengalaman yang menyakitkan. Ejen akan menampal pek bahasa yang gagal dengan menambah penapis validator-sahaja yang menjadikan harness ujian kelihatan lebih hijau, sementara extractor Maguyva sebenar masih memancarkan edge yang salah. Peraturan itu memaksa pembaikan kembali ke laluan sebenar: config YAML, query, atau handler.

Penapisan Berbilang Tier

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

Ini menghalang ejen daripada menambah penapis di tempat yang salah, satu kesilapan lazim yang menyebabkan regresi ketepatan.

Integrasi dengan Sistem Orkestrasi

Ground Truths adalah satu lapisan daripada sistem konteks yang lebih luas:

1. Keputusan Seni Bina (ADR) - Merekod mengapa kami memilih pendekatan A berbanding B
2. Ground Truths - Menyatakan apa yang secara muktamad benar sekarang
3. Corak Domain - Menerangkan cara melakukan sesuatu dengan betul
4. Anti-Corak - Menerangkan apa yang perlu dielakkan dan mengapa

Seorang ejen yang bekerja dalam sistem mempunyai akses kepada kesemua empat-empat. Ground Truths menyediakan tambatan fakta, manakala keputusan menjelaskan sejarah, corak membimbing pelaksanaan, dan anti-corak memberi amaran tentang perangkap.

Mengukur Kesan

Sejak memperkenalkan Ground Truths, kami telah memerhatikan:

• Kitaran “membaiki pembaikan yang berhalusinasi” yang lebih sedikit
• Pembuatan keputusan ejen yang lebih yakin apabila fakta jelas
• Semakan PR yang lebih baik kerana jangkaan bersifat eksplisit
• Masa onboarding yang lebih singkat untuk ejen (dan manusia) baharu

Pelaburan dalam menyenggara Ground Truths berbaloi dengan penyahpepijatan yang berkurangan dan sempadan sistem yang lebih jelas.

Bermula

Untuk menambah satu Ground Truth ke sistem anda:

1. Cipta satu ground_truths.yaml dalam direktori ai_assets/reference/ package anda
2. Takrifkan metadata dan konfigurasi render
3. Tambah pernyataan mengikuti skema
4. Jalankan uv run orkestra sync untuk menjana dokumentasi
5. Sertakan registri itu dalam komposisi konteks ejen

Mulakan dengan fakta yang menyebabkan paling banyak kekeliruan atau kekangan yang paling kerap dilanggar. Itulah Ground Truths anda yang bernilai paling tinggi.

Kesimpulan

Ejen AI akan berhalusinasi. Itulah sifat semula jadinya. Tetapi kita boleh mencipta persekitaran di mana halusinasi dikekang, di mana fakta tertentu tidak boleh dipertikaikan, di mana ejen boleh menyemak andaian mereka berbanding realiti yang disahkan.

Ground Truths bukan penyelesaian yang lengkap. Ia memerlukan penyenggaraan. Ia boleh menjadi basi. Ia menambah overhead kepada proses pembangunan.

Tetapi ia menyediakan sesuatu yang bernilai: perbendaharaan kata fakta yang dikongsi yang dipercayai oleh manusia dan ejen. Dalam dunia di mana ejen semakin banyak mengambil bahagian dalam pembangunan perisian, asas kongsi itu menjadi penting.

Alternatifnya ialah kitaran tanpa henti ejen membuat kesilapan dengan penuh keyakinan dan manusia membetulkannya. Ground Truths memutuskan kitaran itu dengan menjadikan pembetulan itu eksplisit dan berkekalan.

Ejen anda berhak untuk tahu apa yang benar. Beritahu mereka.