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

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

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 ที่ชัดเจน)

นี่คือตัวอย่างจากแพลตฟอร์ม code intelligence Maguyva ของเรา:

- 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 แต่ละแพ็กเกจ หรือโดเมนสามารถมีรีจิสทรีของตัวเองได้ โครงสร้างคือ:

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 โมเดล:

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 ที่อ่านได้:

uv run orkestra sync

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

## 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 แบบโปรแกรมได้:

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

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

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 รีจิสทรีได้:

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

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

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

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

หลักการผลิตภัณฑ์

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

“Maguyva เป็นแบบอ่านอย่างเดียวต่อ repository ของผู้ใช้ สินทรัพย์เดียวที่สร้างขึ้นใหม่ไม่ได้คือแคชเอ็มเบดดิ้งที่ต้องชำระเงิน” (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

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

- 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 ต้องเคารพ หลักฐานได้รับการตรวจสอบแล้ว:

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

Deprecated

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

- 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 ที่ชัดเจน:

- 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 ที่มีวันยืนยันเก่าหรือลิงก์หลักฐานที่เสีย คือสัญญาณให้ตรวจสอบ ไม่ว่าความจริงจะยังใช้ได้และต้องยืนยันซ้ำ หรือความจริงนั้นเปลี่ยนไปแล้วและต้องอัปเดต

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

ขอบเขตความปลอดภัย

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

ความแม่นยำ ณ เวลาแตกโครงสร้าง

- 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, คิวรี หรือตัวจัดการ

การกรองหลายชั้น

- 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 ของคุณสมควรรู้ว่าอะไรเป็นจริง บอกพวกมัน