# Ground Truths: ยึดโยง AI Agent ไว้กับความเป็นจริง

Canonical source: https://maguyva.ai/th/blog/ground-truths-anchoring-ai-to-reality

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-13 · Author: Maguyva Team

> AI agent หลอนได้อย่างมั่นใจ Ground Truths คือข้อเท็จจริงที่มีเวอร์ชันและขอบเขตชัดเจน ซึ่งยึดโยงพฤติกรรมของ agent ไว้กับความเป็นจริง นี่คือวิธีที่เราสร้างและบังคับใช้มัน

> *ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (มกราคม 2026) ดู[หน้าทีม](/th/team)ของเราสำหรับตัวเลขปัจจุบัน*

AI agent มีความสามารถอย่างน่าทึ่ง มันให้เหตุผล สังเคราะห์ และสร้างสรรค์ได้ แต่มันมีจุดอ่อนพื้นฐาน: มันสร้างเรื่องขึ้นมาเอง ไม่ได้ตั้งใจร้าย แต่ทำอย่างมั่นใจ agent อาจสร้าง API พารามิเตอร์ที่ไม่มีอยู่จริง อ้างอิงการตั้งค่าที่ไม่เคยถูกนิยาม หรือใช้รูปแบบจากข้อมูลฝึกของมัน ที่ขัดแย้งกับสถาปัตยกรรมจริงของคุณ

แนวทางบรรเทาปัญหาที่ใช้กันทั่วไปคือ "ให้บริบทกับ agent มากขึ้น" แต่บริบทอาจขัดแย้งกันเองได้ เอกสารเบี่ยงเบนไปจากการอิมพลีเมนต์จริง คอมเมนต์โกหกได้ แม้แต่โค้ดก็ทำให้เข้าใจผิดได้เมื่ออ่านโดยไม่เข้าใจเจตนา

เราต้องการสิ่งที่ชัดเจนกว่านั้น สิ่งที่ไม่สามารถถูกมองข้ามหรือตีความผิดได้ สิ่งที่จะยึดโยง agent ไว้กับความเป็นจริงที่ตรวจสอบได้

เราเรียกมันว่า Ground Truths

## Ground Truth คืออะไร?

ground truth คือข้อความข้อเท็จจริงที่ชัดเจนและมีเวอร์ชัน ซึ่ง agent ต้องเคารพ มันไม่ใช่เอกสาร มันไม่ใช่คอมเมนต์ มันคือเอนทิตีชั้นหนึ่งในระบบที่มี:

- **ตัวระบุที่ไม่ซ้ำกัน** (เช่น `GT-MAG-015` หรือ `GT-MAG-036`)
- **สถานะวงจรชีวิต** (current, tentative หรือ deprecated)
- **ขอบเขต** (ทั้งแพลตฟอร์ม, เฉพาะแพ็กเกจ หรือผูกกับโดเมน)
- **หลักฐาน** (path ของไฟล์, URL หรือการอ้างอิงที่พิสูจน์ข้อความนั้น)
- **คำแนะนำสำหรับ agent** (คำสั่ง do/avoid ที่ชัดเจน)

นี่คือตัวอย่างจากแพลตฟอร์มโค้ดอินเทลลิเจนซ์ Maguyva ของเรา:

```yaml
- 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
```

นี่ไม่ใช่ร้อยแก้ว มันคือสัญญา เมื่อ agent พบ ground truth นี้ มันจะรู้ว่า:
1. ค่าเริ่มต้นเป็นแบบกำหนดแน่นอน (ผลลัพธ์ว่างเปล่า ไม่ใช่การเดาจากการจับคู่โดยประมาณ)
2. มีพารามิเตอร์เฉพาะ (`find_similar`, `exact_match`) พร้อมพฤติกรรมที่นิยามไว้
3. มีหลักฐานอยู่ในไฟล์เฉพาะที่สามารถตรวจสอบได้
4. ข้อความถูกยืนยันในวันที่ระบุ

## โครงสร้างของ Ground Truth รีจิสทรี

ground truth อาศัยอยู่ใน YAML รีจิสทรี ภายใต้ `ai_assets/reference/ground_truths.yaml` แต่ละแพ็กเกจ หรือโดเมนสามารถมีรีจิสทรีของตัวเองได้ โครงสร้างคือ:

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

รีจิสทรีประกอบด้วย metadata เกี่ยวกับตัวชุดเอง, การตั้งค่าการเรนเดอร์สำหรับสร้างเอกสาร และข้อความเอง แต่ละข้อความปฏิบัติตาม schema ที่เข้มงวดซึ่งตรวจสอบด้วย Pydantic โมเดล:

```python
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
```

## Agent เข้าถึง Ground Truth ได้อย่างไร

ground truth ถูกเปิดผ่านหลายช่องทาง:

### 1. เอกสารที่เรนเดอร์แล้ว

คำสั่ง `orkestra sync` แปลง YAML รีจิสทรีให้เป็น markdown ที่อ่านได้:

```bash
uv run orkestra sync
```

สิ่งนี้สร้างไฟล์ `GROUND_TRUTHS.md` ที่ถูกรวมเข้าในบริบทของ agent ผลลัพธ์ที่เรนเดอร์แล้วจะจัดกลุ่มข้อความตามสถานะและหมวดหมู่:

```markdown
## 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

agent ที่เข้าถึง shell ได้สามารถค้นหา ground truth แบบโปรแกรมได้:

```bash
uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current
```

ฟังก์ชันค้นหาให้คะแนนการจับคู่ข้ามหลายฟิลด์ด้วยน้ำหนักถ่วง:

```python
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. การประกอบบริบท

เมื่อ agent ถูกเรนเดอร์จากคำนิยาม YAML บริบทของมันสามารถอ้างอิง ground truth รีจิสทรีได้:

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

สิ่งนี้ทำให้แน่ใจว่า ground truth ที่เกี่ยวข้องถูกโหลดก่อนที่ agent จะเริ่มทำงาน

## หมวดหมู่ของ Ground Truth

เมื่อพิจารณารีจิสทรีทั้งหมดของเรา ground truth จะรวมกลุ่มเป็นรูปแบบหลายอย่าง:

### หลักการผลิตภัณฑ์
ข้อจำกัดว่าผลิตภัณฑ์คืออะไรและไม่ใช่อะไร:

> "Maguyva เป็นแบบอ่านอย่างเดียวต่อรีโพซิทอรีของผู้ใช้ สินทรัพย์เดียวที่สร้างขึ้นใหม่ไม่ได้คือแคชเอ็มเบดดิ้งที่ต้องชำระเงิน" (GT-MAG-001)

### ขอบเขตสถาปัตยกรรม
ความรับผิดชอบอยู่ที่ไหนและเพราะเหตุใด:

> "ขอบเขตระหว่าง pipeline กับ Maguyva ตั้งใจไว้แบบนี้: pipeline นำกลับมาใช้ใหม่ได้, Maguyva เก็บตรรกะเฉพาะโค้ด และ CQRS แยกการเขียนของสเตจออกจากการอ่านของเซิร์ฟเวอร์" (GT-MAG-006)

### กฎป้องกันการหลอน
คำสั่งที่ชัดเจนซึ่งรักษาให้สัญญาเครื่องมือเป็นแบบกำหนดแน่นอนแทนการอนุมาน:

> "การจับคู่สัญลักษณ์แบบโดยประมาณเป็นแบบเลือกเปิดใช้เองผ่าน `find_similar=true` พฤติกรรมเริ่มต้นคืนผลลัพธ์ว่างเปล่าสำหรับสัญลักษณ์ที่ไม่มีอยู่จริง `exact_match=true` บังคับให้จับคู่แบบเข้มงวดและปิดทางเลือกสำรองที่ใช้การจับคู่โดยประมาณทั้งหมด" (GT-MAG-015)

### เกณฑ์คุณภาพ
มาตรฐานที่ต้องรักษาไว้:

> "การเปลี่ยนแปลงโครงสร้างพื้นฐานที่ใช้ร่วมกัน (post_filters.py, ตัวดึงความสัมพันธ์, ตัวจัดการที่ใช้ร่วมกัน) ต้องได้รับการตรวจสอบกับ *ทุก* ภาษาที่รองรับผ่านการสร้าง full manifest ก่อน commit การตรวจสอบภาษาเดียวไม่เพียงพอสำหรับโค้ดที่ใช้ร่วมกัน" (GT-MAG-036)

### รูปแบบโค้ด
ข้อกำหนดการอิมพลีเมนต์:

> "ใช้ `asyncio.to_thread()` สำหรับงานที่หนัก CPU ในบริบท async รูปแบบ `loop.run_in_executor()` ที่เลิกใช้แล้วไม่ควรถูกใช้ในโค้ดใหม่" (GT-MAG-018)

## วงจรชีวิตของ Ground Truth

ground truth ไม่คงที่ มันวิวัฒนาการผ่านวงจรชีวิตที่นิยามไว้:

### Tentative
ความจริงที่เสนอไว้ภายใต้การประเมิน ข้อความถูกบันทึกไว้แต่อาจเปลี่ยนแปลงได้:

```yaml
- 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
ความจริงที่ยืนยันแล้วซึ่ง agent ต้องเคารพ หลักฐานได้รับการตรวจสอบแล้ว:

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

### Deprecated
ความจริงที่ไม่ใช้แล้ว ถูกเก็บไว้เพื่ออ้างอิงทางประวัติศาสตร์พร้อมตัวชี้ไปยังสิ่งที่มาแทนที่:

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

## เหตุใดจึงไม่ใช้แค่เอกสาร?

เอกสารรับใช้จุดประสงค์ที่ต่างกัน มันอธิบาย มันสอน มันคลุมเครือได้ ใช้คำอย่าง "โดยทั่วไป" หรือ "มักจะ" ได้

ground truth คลุมเครือไม่ได้ มันคือการยืนยัน มันเป็นจริงหรือไม่เป็นจริง

พิจารณาความแตกต่าง:

**เอกสาร:** "API มักจะคืนผลลัพธ์ว่างเปล่าเมื่อไม่พบสัญลักษณ์ แม้ว่าการจับคู่แบบโดยประมาณอาจถูกเปิดใช้ในการตั้งค่าบางแบบ"

**Ground Truth:** "พฤติกรรมเริ่มต้นคืนผลลัพธ์ว่างเปล่าสำหรับสัญลักษณ์ที่ไม่มีอยู่จริง `exact_match=true` บังคับให้จับคู่แบบเข้มงวดและปิดทางเลือกสำรองที่ใช้การจับคู่โดยประมาณทั้งหมด"

อย่างแรกมีประโยชน์สำหรับมนุษย์ที่เรียนรู้ระบบ อย่างที่สองสามารถนำไปปฏิบัติได้สำหรับ agent ที่กำลังตัดสินใจ

## คำแนะนำสำหรับ Agent: สิ่งที่ควรทำและควรหลีกเลี่ยง

ground truth บางอย่างมีคำแนะนำสำหรับ agent ที่ชัดเจน:

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

สิ่งนี้ขจัดความคลุมเครือ agent ที่อ่านสิ่งนี้จะรู้ไม่เพียงแค่ว่าอะไรเป็นจริง แต่ยังรู้ว่าความจริงนั้นหมายความว่าต้องทำอะไร

## การยืนยันและการบำรุงรักษา

ground truth ต้องการการบำรุงรักษา เราติดตาม:

- **last_verified**: เวลาที่มีการยืนยันว่าข้อความยังคงเป็นจริง
- **evidence**: ไฟล์ที่พิสูจน์ข้อความ (สามารถตรวจสอบว่ามีอยู่จริงได้)
- **source**: ความจริงมาจากไหน (การตรวจสอบด้วย CLI, การรีวิวสถาปัตยกรรม, บทเรียนหลังเหตุการณ์)

ground truth ที่มีวันยืนยันเก่าหรือลิงก์หลักฐานที่เสีย คือสัญญาณให้ตรวจสอบ ข้อเท็จจริงนั้นอาจยังใช้ได้และต้องยืนยันซ้ำ หรืออาจเปลี่ยนไปแล้วและต้องอัปเดต

## ตัวอย่างจริงจากโปรดักชัน

### ขอบเขตความปลอดภัย
```yaml
- 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 นี้ป้องกัน "การปรับปรุงความปลอดภัย" ที่เข้าใจผิดประเภทหนึ่ง ซึ่งจะทำลายผลิตภัณฑ์

### ความแม่นยำ ณ เวลาแตกโครงสร้าง
```yaml
- 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.
```

สิ่งนี้มาจากประสบการณ์ที่เจ็บปวด agent เคยแพตช์แพ็กภาษาที่ล้มเหลวด้วยการเพิ่มตัวกรองที่ทำงานเฉพาะในวาลิเดเตอร์ที่ทำให้ชุดทดสอบดูเขียวขึ้น ในขณะที่ตัวสกัด Maguyva ตัวจริงยังคงปล่อย edge ที่ผิดอยู่ กฎนี้บังคับให้การแก้ไขกลับไปยังเส้นทางจริง: การตั้งค่า YAML, คิวรี หรือตัวจัดการ

### การกรองหลายชั้น
```yaml
- 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).
```

สิ่งนี้ป้องกัน agent จากการเพิ่มตัวกรองในจุดที่ผิด ซึ่งเป็นความผิดพลาดทั่วไปที่เคยทำให้ความแม่นยำถดถอย

## การผสานรวมกับระบบออร์เคสเตรชัน

ground truth คือชั้นหนึ่งของระบบบริบทที่กว้างกว่า:

1. **การตัดสินใจเชิงสถาปัตยกรรม (ADR)** - บันทึกว่าทำไมเราจึงเลือกวิธี A แทน B
2. **Ground Truths** - ระบุว่าอะไรเป็นจริงแน่นอนในตอนนี้
3. **รูปแบบโดเมน** - อธิบายวิธีทำสิ่งต่างๆ ให้ถูกต้อง
4. **Anti-Patterns** - อธิบายสิ่งที่ควรหลีกเลี่ยงและเพราะเหตุใด

agent ที่ทำงานในระบบสามารถเข้าถึงทั้งสี่อย่างได้ ground truth มอบจุดยึดข้อเท็จจริง ในขณะที่การตัดสินใจอธิบายประวัติศาสตร์ รูปแบบชี้นำการอิมพลีเมนต์ และ Anti-Patterns เตือนถึงข้อผิดพลาด

## การวัดผลกระทบ

นับตั้งแต่นำ ground truth มาใช้ เราได้สังเกตเห็น:

- วงจร "แก้ไขสิ่งที่หลอนขึ้นมา" น้อยลง
- การตัดสินใจของ agent มั่นใจมากขึ้นเมื่อข้อเท็จจริงชัดเจน
- การรีวิว PR ที่ดีขึ้นเพราะความคาดหวังชัดเจน
- เวลาออนบอร์ด agent ใหม่ลดลง (รวมถึงสมาชิกทีมที่เป็นมนุษย์)

การลงทุนในการบำรุงรักษา ground truth คุ้มค่าในการลดการดีบักและทำให้ขอบเขตระบบชัดเจนขึ้น

## เริ่มต้นใช้งาน

ในการเพิ่ม ground truth ให้ระบบของคุณ:

1. สร้าง `ground_truths.yaml` ในไดเรกทอรี `ai_assets/reference/` ของแพ็กเกจของคุณ
2. นิยาม metadata และการตั้งค่าการเรนเดอร์
3. เพิ่มข้อความตาม schema
4. รัน `uv run orkestra sync` เพื่อสร้างเอกสาร
5. รวมรีจิสทรีเข้าในการประกอบบริบทของ agent

เริ่มด้วยข้อเท็จจริงที่ก่อความสับสนมากที่สุด หรือข้อจำกัดที่ถูกละเมิดบ่อยที่สุด นั่นคือ ground truth ที่มีคุณค่าสูงสุดของคุณ

## บทสรุป

AI agent จะหลอน นั่นคือธรรมชาติของมัน แต่เราสามารถสร้างสภาพแวดล้อมที่การหลอนถูกจำกัดได้ ที่ข้อเท็จจริงบางอย่างต่อรองไม่ได้ ที่ agent สามารถตรวจสอบสมมติฐานของตัวเองกับความเป็นจริงที่ยืนยันแล้วได้

ground truth ไม่ใช่ทางออกที่สมบูรณ์ มันต้องการการบำรุงรักษา มันสามารถล้าสมัยได้ มันเพิ่มภาระให้กระบวนการพัฒนา

แต่มันมอบสิ่งที่มีคุณค่า: คำศัพท์ร่วมของข้อเท็จจริงที่ทั้งมนุษย์และ agent สามารถไว้วางใจได้ ในโลกที่ agent เข้ามามีส่วนร่วมในการพัฒนาซอฟต์แวร์มากขึ้นเรื่อยๆ รากฐานที่ใช้ร่วมกันนั้นกลายเป็นสิ่งจำเป็น

ทางเลือกอื่นคือวงจรไม่รู้จบของ agent ที่ทำผิดพลาดอย่างมั่นใจ และมนุษย์คอยแก้ไข ground truth ทำลายวงจรนั้นด้วยการทำให้การแก้ไขชัดเจนและคงทน

agent ของคุณสมควรรู้ว่าอะไรเป็นจริง บอกพวกมัน