Ground Truths: Menambatkan Agen AI ke Realitas

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Januari 2026). Lihat halaman tim kami untuk angka terkini.

Agen AI sangat kapabel. Mereka bisa bernalar, mensintesis, dan menghasilkan. Tetapi mereka punya kelemahan mendasar: mereka mengarang-ngarang. Bukan dengan niat jahat, tetapi dengan percaya diri. Seorang agen bisa saja mengarang parameter API yang tidak ada, merujuk konfigurasi yang tidak pernah didefinisikan, atau menerapkan pola dari data pelatihannya yang bertentangan dengan arsitektur Anda yang sebenarnya.

Mitigasi standarnya adalah “beri agen lebih banyak konteks.” Tetapi konteks bisa saling bertentangan. Dokumentasi melenceng dari implementasi. Komentar bisa berbohong. Bahkan kode pun bisa menyesatkan jika dibaca tanpa memahami maksudnya.

Kami butuh sesuatu yang lebih eksplisit. Sesuatu yang tidak bisa diabaikan atau disalahtafsirkan. Sesuatu yang menambatkan agen ke realitas yang bisa diverifikasi.

Kami menyebutnya Ground Truths.

Apa itu Ground Truth?

Sebuah ground truth adalah pernyataan fakta yang eksplisit dan terversi yang harus dihormati oleh agen. Ini bukan dokumentasi. Ini bukan komentar. Ini adalah entitas kelas satu dalam sistem dengan:

• Sebuah identifier unik (seperti GT-MAG-015 atau GT-MAG-036)
• Sebuah status lifecycle (current, tentative, atau deprecated)
• Sebuah scope (platform-wide, package-specific, atau domain-bound)
• Bukti (path file, URL, atau referensi yang membuktikan pernyataan tersebut)
• Panduan agen (instruksi do/avoid yang eksplisit)

Berikut contoh dari platform kecerdasan kode 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. Ini kontrak. Ketika seorang agen menjumpai ground truth ini, ia tahu:

1. Default-nya deterministik (hasil kosong, bukan tebakan yang samar)
2. Ada parameter spesifik (find_similar, exact_match) dengan perilaku yang terdefinisi
3. Bukti ada di file-file spesifik yang bisa diverifikasi
4. Pernyataan ini diverifikasi pada tanggal tertentu

Anatomi Registry Ground Truth

Ground truth hidup dalam registry YAML di bawah ai_assets/reference/ground_truths.yaml. Setiap package atau domain bisa punya registry-nya sendiri. Strukturnya adalah:

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

Registry mencakup metadata tentang koleksinya sendiri, konfigurasi render untuk generasi dokumentasi, dan pernyataan-pernyataannya sendiri. Setiap pernyataan mengikuti skema ketat yang divalidasi 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 Agen Mengakses Ground Truth

Ground truth diekspos lewat beberapa jalur:

1. Dokumentasi Ter-render

Perintah orkestra sync mengubah registry YAML menjadi markdown yang bisa dibaca:

uv run orkestra sync

Ini menghasilkan file GROUND_TRUTHS.md yang disertakan dalam konteks agen. Output ter-render mengelompokkan pernyataan berdasarkan 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. Pencarian CLI

Agen dengan akses shell bisa mencari ground truth secara terprogram:

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 pencarian menilai kecocokan di berbagai field dengan relevansi berbobot:

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

Ketika agen di-render dari definisi YAML, konteks mereka bisa merujuk ke registry ground truth:

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

Ini memastikan ground truth yang relevan dimuat sebelum agen mulai bekerja.

Kategori Ground Truth

Melihat ke seluruh registry kami, ground truth mengelompok ke dalam beberapa pola:

Prinsip Produk

Batasan tentang apa yang menjadi dan bukan produk ini:

“Maguyva bersifat read-only terhadap repositori pengguna; satu-satunya aset yang tidak bisa dibangun ulang adalah cache embedding berbayar.” (GT-MAG-001)

Batas Arsitektur

Di mana tanggung jawab berada dan mengapa:

“Batas antara pipeline dan Maguyva itu disengaja: pipeline dapat digunakan ulang, Maguyva memegang logika spesifik-kode, dan CQRS memisahkan penulisan stage dari pembacaan server.” (GT-MAG-006)

Aturan Anti-Halusinasi

Mandat eksplisit yang menjaga kontrak tool tetap deterministik, bukan hasil inferensi:

“Pencocokan simbol fuzzy bersifat opt-in lewat find_similar=true. Perilaku default mengembalikan hasil kosong untuk simbol yang tidak ada; exact_match=true menegakkan pencocokan ketat dan menonaktifkan semua fallback fuzzy.” (GT-MAG-015)

Quality Gate

Standar yang harus dipertahankan:

“Perubahan pada infrastruktur bersama (post_filters.py, ekstraktor relasi, handler bersama) HARUS divalidasi terhadap SEMUA bahasa yang didukung lewat generasi full manifest sebelum commit. Validasi satu bahasa saja tidak cukup untuk kode bersama.” (GT-MAG-036)

Pola Kode

Persyaratan implementasi:

“Gunakan asyncio.to_thread() untuk pekerjaan CPU-bound dalam konteks async; pola loop.run_in_executor() yang sudah usang tidak boleh dipakai di kode baru.” (GT-MAG-018)

Siklus Hidup Sebuah Ground Truth

Ground truth tidak statis. Mereka berevolusi lewat siklus hidup yang terdefinisi:

Tentative

Sebuah truth yang diusulkan dan sedang dievaluasi. Pernyataannya tercatat tetapi bisa 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

Sebuah truth terverifikasi yang harus dihormati agen. Buktinya sudah divalidasi:

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

Deprecated

Sebuah truth yang tidak berlaku lagi. Disimpan untuk referensi historis dengan penunjuk ke 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 punya tujuan yang berbeda. Ia menjelaskan. Ia mengajarkan. Ia boleh samar, boleh memakai kata seperti “umumnya” atau “biasanya.”

Ground truth tidak boleh samar. Mereka adalah pernyataan tegas. Mereka berlaku atau tidak berlaku, titik.

Pertimbangkan perbedaannya:

Dokumentasi: “API umumnya mengembalikan hasil kosong ketika sebuah simbol tidak ditemukan, meski pencocokan fuzzy bisa diaktifkan pada beberapa konfigurasi.”

Ground Truth: “Perilaku default mengembalikan hasil kosong untuk simbol yang tidak ada; exact_match=true menegakkan pencocokan ketat dan menonaktifkan semua fallback fuzzy.”

Yang pertama membantu manusia mempelajari sistem. Yang kedua bisa langsung ditindaklanjuti oleh agen yang mengambil keputusan.

Panduan Agen: Do dan Avoid

Beberapa ground truth menyertakan panduan agen 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 menghilangkan ambiguitas. Seorang agen yang membaca ini tahu bukan hanya apa yang benar, tetapi juga tindakan apa yang tersirat dari kebenaran itu.

Verifikasi dan Pemeliharaan

Ground truth membutuhkan pemeliharaan. Kami melacak:

• last_verified: Kapan seseorang mengonfirmasi pernyataan ini masih berlaku
• evidence: File-file yang membuktikan pernyataan tersebut (bisa diperiksa keberadaannya)
• source: Dari mana truth ini berasal (inspeksi CLI, tinjauan arsitektur, pembelajaran pasca-insiden)

Sebuah ground truth dengan tanggal verifikasi yang basi atau tautan bukti yang rusak adalah sinyal untuk diselidiki. Entah truth-nya masih valid dan butuh verifikasi ulang, atau realitasnya sudah berubah dan truth-nya perlu diperbarui.

Contoh Nyata dari Produksi

Batas Keamanan

- 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 mencegah sekelompok “perbaikan keamanan” yang keliru arah yang justru akan merusak produk.

Akurasi Saat Ekstraksi

- 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 lahir dari pengalaman yang menyakitkan. Agen pernah menambal language pack yang gagal dengan menambahkan filter yang hanya berlaku di validator, yang membuat test harness terlihat lebih hijau, sementara Maguyva extractor yang sesungguhnya di produksi tetap mengemisikan edge yang salah. Aturan ini memaksa perbaikan kembali ke jalur sungguhan: config YAML, query, atau handler.

Filtering Multi-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 mencegah agen menambahkan filter di tempat yang salah, sebuah kesalahan umum yang menyebabkan regresi akurasi.

Integrasi dengan Sistem Orkestrasi

Ground truth adalah satu lapisan dari sistem konteks yang lebih luas:

1. Keputusan Arsitektur (ADR) - Mencatat mengapa kami memilih pendekatan A daripada B
2. Ground Truths - Menyatakan apa yang secara definitif benar saat ini
3. Domain Patterns - Menjelaskan bagaimana melakukan sesuatu dengan benar
4. Anti-Patterns - Menjelaskan apa yang harus dihindari dan mengapa

Seorang agen yang bekerja dalam sistem punya akses ke keempatnya. Ground truth menyediakan jangkar faktual, sementara decision menjelaskan sejarah, pattern memandu implementasi, dan anti-pattern memperingatkan jebakan.

Mengukur Dampak

Sejak memperkenalkan ground truth, kami telah mengamati:

• Lebih sedikit siklus “perbaiki perbaikan yang berhalusinasi”
• Pengambilan keputusan agen yang lebih percaya diri ketika fakta sudah jelas
• Tinjauan PR yang lebih baik karena ekspektasinya eksplisit
• Waktu onboarding yang lebih singkat untuk agen baru (dan manusia baru)

Investasi dalam memelihara ground truth terbayar lewat debugging yang berkurang dan batas sistem yang lebih jelas.

Memulai

Untuk menambahkan sebuah ground truth ke sistem Anda:

1. Buat sebuah ground_truths.yaml di direktori ai_assets/reference/ milik package Anda
2. Definisikan metadata dan konfigurasi render
3. Tambahkan pernyataan yang mengikuti skema
4. Jalankan uv run orkestra sync untuk menghasilkan dokumentasi
5. Sertakan registry-nya dalam komposisi konteks agen

Mulailah dari fakta-fakta yang paling sering menimbulkan kebingungan atau batasan yang paling sering dilanggar. Itulah ground truth Anda yang paling bernilai.

Kesimpulan

Agen AI akan berhalusinasi. Itu sudah sifat dasarnya. Tetapi kita bisa menciptakan lingkungan tempat halusinasi itu dibatasi, tempat fakta-fakta tertentu tidak bisa dinegosiasikan, tempat agen bisa memeriksa asumsi mereka terhadap realitas yang terverifikasi.

Ground truth bukan solusi yang lengkap. Mereka butuh pemeliharaan. Mereka bisa menjadi basi. Mereka menambah overhead pada proses pengembangan.

Tetapi mereka menyediakan sesuatu yang berharga: sebuah kosakata fakta bersama yang bisa dipercaya baik oleh manusia maupun agen. Di dunia tempat agen semakin banyak berpartisipasi dalam pengembangan perangkat lunak, fondasi bersama itu menjadi esensial.

Alternatifnya adalah siklus tanpa akhir dari agen yang membuat kesalahan dengan percaya diri dan manusia yang mengoreksinya. Ground truth memutus siklus itu dengan membuat koreksi-koreksi itu eksplisit dan bertahan lama.

Agen Anda berhak tahu apa yang benar. Beri tahu mereka.