Ground Truths: Neo AI Agent vào thực tế

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 1/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Các AI agent có năng lực đáng kinh ngạc. Chúng có thể suy luận, tổng hợp, và sinh ra nội dung. Nhưng chúng có một điểm yếu cơ bản: chúng bịa đặt. Không phải với ác ý, mà với sự tự tin. Một agent có thể bịa ra các tham số API không tồn tại, tham chiếu đến các cấu hình chưa từng được định nghĩa, hoặc áp dụng các mẫu từ dữ liệu huấn luyện của nó mâu thuẫn với kiến trúc thực tế của bạn.

Biện pháp giảm thiểu tiêu chuẩn là “cho agent thêm ngữ cảnh.” Nhưng ngữ cảnh có thể mâu thuẫn nhau. Tài liệu trôi dạt khỏi việc triển khai. Comment nói dối. Ngay cả mã nguồn cũng có thể gây hiểu lầm khi đọc mà không hiểu ý đồ.

Chúng tôi cần một thứ gì đó tường minh hơn. Một thứ không thể bị bỏ qua hoặc hiểu sai. Một thứ neo được các agent vào thực tế có thể kiểm chứng.

Chúng tôi gọi chúng là Ground Truth.

Ground Truth là gì?

Một Ground Truth là một phát biểu sự thật tường minh, có phiên bản, mà các agent phải tôn trọng. Đó không phải là tài liệu. Đó không phải là comment. Đó là một thực thể hạng nhất trong hệ thống, với:

• Một định danh duy nhất (như GT-MAG-015 hoặc GT-MAG-036)
• Một trạng thái vòng đời (current, tentative, hoặc deprecated)
• Một phạm vi (toàn nền tảng, riêng cho package, hoặc gắn với domain)
• Bằng chứng (đường dẫn file, URL, hoặc tham chiếu chứng minh phát biểu đó)
• Hướng dẫn cho agent (chỉ dẫn nên làm/nên tránh tường minh)

Đây là một ví dụ từ nền tảng trí tuệ mã nguồn Maguyva của chúng tôi:

- 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

Đây không phải là văn xuôi. Đó là một hợp đồng. Khi một agent gặp Ground Truth này, nó biết:

1. Mặc định là tất định (kết quả rỗng, không phải đoán mò mờ nhạt)
2. Có các tham số cụ thể (find_similar, exact_match) với hành vi đã được định nghĩa
3. Bằng chứng tồn tại trong các file cụ thể có thể được xác minh
4. Phát biểu này đã được xác minh vào một ngày cụ thể

Giải phẫu một Registry Ground Truth

Ground Truth sống trong các registry YAML dưới ai_assets/reference/ground_truths.yaml. Mỗi package hoặc domain có thể có registry riêng. Cấu trúc như sau:

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 bao gồm metadata về chính bộ sưu tập đó, cấu hình render để sinh tài liệu, và bản thân các phát biểu. Mỗi phát biểu tuân theo một schema nghiêm ngặt được xác thực bởi các 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

Agent truy cập Ground Truth bằng cách nào

Ground Truth được phơi bày qua nhiều kênh:

1. Tài liệu đã render

Lệnh orkestra sync biến đổi các registry YAML thành markdown dễ đọc:

uv run orkestra sync

Điều này sinh ra các file GROUND_TRUTHS.md được đưa vào ngữ cảnh của agent. Đầu ra đã render nhóm các phát biểu theo trạng thái và danh mục:

## 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. Tìm kiếm qua CLI

Các agent có quyền truy cập shell có thể tìm kiếm Ground Truth theo lập trình:

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

Hàm tìm kiếm chấm điểm các khớp trên nhiều trường với độ liên quan có trọng số:

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. Soạn ngữ cảnh (Context Composition)

Khi các agent được render từ định nghĩa YAML, ngữ cảnh của chúng có thể tham chiếu đến các registry Ground Truth:

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

Điều này đảm bảo các Ground Truth liên quan được nạp trước khi agent bắt đầu công việc.

Các loại Ground Truth

Nhìn qua các registry của chúng tôi, Ground Truth tập trung thành vài mẫu:

Nguyên tắc sản phẩm

Các ràng buộc về việc sản phẩm là gì và không phải là gì:

“Maguyva chỉ đọc (read-only) đối với các repo của người dùng; tài sản duy nhất không thể xây dựng lại được là cache embedding đã trả phí.” (GT-MAG-001)

Ranh giới kiến trúc

Trách nhiệm nằm ở đâu và tại sao:

“Ranh giới giữa Pipeline và Maguyva là có chủ đích: pipeline có thể tái sử dụng, Maguyva nắm giữ logic đặc thù cho mã nguồn, và CQRS tách các lượt ghi giai đoạn khỏi các lượt đọc của server.” (GT-MAG-006)

Quy tắc chống ảo giác

Các chỉ thị tường minh giữ cho hợp đồng công cụ mang tính tất định thay vì suy luận:

“So khớp symbol mờ (fuzzy) là tùy chọn, kích hoạt qua find_similar=true. Hành vi mặc định trả về kết quả rỗng cho các symbol không tồn tại; exact_match=true ép buộc so khớp nghiêm ngặt và tắt mọi phương án dự phòng mờ.” (GT-MAG-015)

Cổng chất lượng

Các tiêu chuẩn phải được duy trì:

“Các thay đổi đối với hạ tầng dùng chung (post_filters.py, các trình trích xuất quan hệ, các handler dùng chung) PHẢI được xác thực trên TẤT CẢ các ngôn ngữ được hỗ trợ thông qua việc sinh manifest đầy đủ trước khi commit. Xác thực trên một ngôn ngữ duy nhất là không đủ đối với mã dùng chung.” (GT-MAG-036)

Mẫu mã

Các yêu cầu triển khai:

“Dùng asyncio.to_thread() cho công việc nặng CPU trong ngữ cảnh async; mẫu loop.run_in_executor() đã lỗi thời không nên được dùng trong mã mới.” (GT-MAG-018)

Vòng đời của một Ground Truth

Ground Truth không tĩnh. Chúng tiến hóa qua một vòng đời được định nghĩa rõ ràng:

Tentative (Tạm thời)

Một sự thật được đề xuất, đang trong quá trình đánh giá. Phát biểu được ghi lại nhưng có thể thay đổi:

- 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 (Hiện hành)

Một sự thật đã được xác minh mà các agent phải tôn trọng. Bằng chứng đã được xác thực:

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

Deprecated (Đã lỗi thời)

Một sự thật không còn áp dụng nữa. Được giữ lại để tham khảo lịch sử kèm con trỏ đến thứ đã thay thế nó:

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

Tại sao không chỉ dùng tài liệu?

Tài liệu phục vụ một mục đích khác. Nó giải thích. Nó dạy. Nó có thể mơ hồ, có thể dùng các từ định tính như “nhìn chung” hoặc “thường thì.”

Ground Truth không thể mơ hồ. Chúng là các khẳng định. Chúng hoặc áp dụng hoặc không.

Hãy xem xét sự khác biệt:

Tài liệu: “API nhìn chung trả về kết quả rỗng khi không tìm thấy symbol, mặc dù so khớp mờ có thể được bật trong một số cấu hình.”

Ground Truth: “Hành vi mặc định trả về kết quả rỗng cho các symbol không tồn tại; exact_match=true ép buộc so khớp nghiêm ngặt và tắt mọi phương án dự phòng mờ.”

Cái đầu tiên hữu ích cho con người khi học hệ thống. Cái thứ hai có thể hành động được đối với các agent khi ra quyết định.

Hướng dẫn cho agent: Nên làm và nên tránh

Một số Ground Truth bao gồm hướng dẫn tường minh cho 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"

Điều này loại bỏ sự mơ hồ. Một agent đọc điều này biết không chỉ điều gì là đúng, mà còn biết sự thật đó ngụ ý hành động gì.

Xác minh và bảo trì

Ground Truth cần được bảo trì. Chúng tôi theo dõi:

• last_verified: Khi nào ai đó xác nhận phát biểu vẫn còn đúng
• evidence: Các file chứng minh phát biểu đó (có thể kiểm tra sự tồn tại)
• source: Sự thật bắt nguồn từ đâu (kiểm tra qua CLI, rà soát kiến trúc, bài học sau sự cố)

Một Ground Truth với ngày xác minh đã cũ hoặc liên kết bằng chứng bị hỏng là một tín hiệu cần điều tra. Hoặc sự thật đó vẫn còn đúng và cần xác minh lại, hoặc thực tế đã thay đổi và sự thật đó cần được cập nhật.

Ví dụ thực tế từ môi trường production

Ranh giới bảo mật

- 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 này ngăn chặn một nhóm các “cải tiến bảo mật” bị hiểu sai sẽ làm hỏng sản phẩm.

Độ chính xác tại thời điểm trích xuất

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

Điều này đến từ một kinh nghiệm đau đớn. Các agent từng vá các gói ngôn ngữ đang lỗi bằng cách thêm các bộ lọc chỉ-dành-cho-validator khiến bộ khai thác test trông xanh hơn, trong khi trình trích xuất Maguyva thực tế vẫn phát ra sai edge. Quy tắc này buộc các bản sửa phải quay lại đường thực: cấu hình YAML, truy vấn, hoặc handler.

Lọc đa tầng

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

Điều này ngăn các agent thêm bộ lọc sai chỗ, một lỗi phổ biến từng gây ra hồi quy độ chính xác.

Tích hợp với hệ thống Orchestration

Ground Truth là một tầng trong một hệ thống ngữ cảnh rộng hơn:

1. Quyết định kiến trúc (ADR) - Ghi lại vì sao chúng tôi chọn phương án A thay vì B
2. Ground Truth - Phát biểu điều gì chắc chắn đúng ngay lúc này
3. Mẫu Domain - Mô tả cách làm đúng
4. Anti-Pattern - Mô tả điều cần tránh và tại sao

Một agent làm việc trong hệ thống có quyền truy cập cả bốn thứ này. Ground Truth cung cấp neo sự thật, trong khi các quyết định giải thích lịch sử, các mẫu hướng dẫn triển khai, và các anti-pattern cảnh báo về cạm bẫy.

Đo lường tác động

Kể từ khi đưa Ground Truth vào sử dụng, chúng tôi đã quan sát thấy:

• Ít hơn các chu trình “sửa cái bản sửa bị ảo giác”
• Việc ra quyết định của agent tự tin hơn khi sự thật đã rõ ràng
• Rà soát PR tốt hơn vì kỳ vọng đã tường minh
• Thời gian onboarding giảm cho cả agent mới (và con người)

Khoản đầu tư vào việc bảo trì Ground Truth mang lại lợi ích trong việc giảm debug và làm rõ ranh giới hệ thống.

Bắt đầu

Để thêm một Ground Truth vào hệ thống của bạn:

1. Tạo một ground_truths.yaml trong thư mục ai_assets/reference/ của package của bạn
2. Định nghĩa metadata và cấu hình render
3. Thêm các phát biểu tuân theo schema
4. Chạy uv run orkestra sync để sinh tài liệu
5. Đưa registry vào phần soạn ngữ cảnh của agent

Bắt đầu với những sự thật gây ra nhiều nhầm lẫn nhất hoặc những ràng buộc bị vi phạm thường xuyên nhất. Đó là những Ground Truth có giá trị cao nhất của bạn.

Kết luận

Các AI agent sẽ ảo giác. Đó là bản chất của chúng. Nhưng chúng ta có thể tạo ra những môi trường nơi ảo giác bị kiềm chế, nơi một số sự thật nhất định không thể thương lượng, nơi các agent có thể đối chiếu giả định của mình với thực tế đã được xác minh.

Ground Truth không phải là một giải pháp hoàn chỉnh. Chúng cần được bảo trì. Chúng có thể trở nên lỗi thời. Chúng thêm chi phí vào quy trình phát triển.

Nhưng chúng cung cấp một thứ có giá trị: một vốn từ vựng chung về sự thật mà cả con người và agent đều có thể tin tưởng. Trong một thế giới nơi agent ngày càng tham gia nhiều hơn vào việc phát triển phần mềm, nền tảng chung đó trở nên thiết yếu.

Phương án thay thế là những chu trình bất tận của việc agent mắc lỗi một cách tự tin và con người phải sửa lại chúng. Ground Truth phá vỡ chu trình đó bằng cách làm cho các bản sửa trở nên tường minh và bền vững.

Agent của bạn xứng đáng được biết điều gì là đúng. Hãy nói cho chúng biết.