Ground Truths: zakotwiczanie agentów AI w rzeczywistości

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Agenci AI są niezwykle zdolni. Potrafią rozumować, syntetyzować i generować. Ale mają fundamentalną słabość: zmyślają. Nie złośliwie, ale z pełnym przekonaniem. Agent może wymyślić parametry API, które nie istnieją, odwołać się do konfiguracji, które nigdy nie zostały zdefiniowane, albo zastosować wzorce ze swoich danych treningowych, które są sprzeczne z Twoją rzeczywistą architekturą.

Standardowym środkiem zaradczym jest „daj agentowi więcej kontekstu”. Ale kontekst może być sprzeczny. Dokumentacja odbiega od implementacji. Komentarze kłamią. Nawet kod może wprowadzać w błąd, gdy czyta się go bez zrozumienia intencji.

Potrzebowaliśmy czegoś bardziej jednoznacznego. Czegoś, czego nie da się zignorować ani błędnie zinterpretować. Czegoś, co zakotwiczy agentów w weryfikowalnej rzeczywistości.

Nazywamy je Ground Truths.

Czym jest Ground Truth?

Ground truth to jednoznaczne, wersjonowane stwierdzenie faktu, którego agenci muszą przestrzegać. To nie dokumentacja. To nie komentarz. To pełnoprawna jednostka w systemie z:

• Unikalnym identyfikatorem (takim jak GT-MAG-015 czy GT-MAG-036)
• Statusem cyklu życia (aktualny, tymczasowy lub przestarzały)
• Zakresem (obejmujący całą platformę, specyficzny dla pakietu lub związany z domeną)
• Dowodem (ścieżki plików, adresy URL lub referencje, które potwierdzają stwierdzenie)
• Wskazówkami dla agenta (jednoznaczne instrukcje rób/unikaj)

Oto przykład z naszej platformy inteligencji kodu 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

To nie jest proza. To kontrakt. Gdy agent natrafia na ten ground truth, wie że:

1. Domyślne zachowanie jest deterministyczne (puste wyniki, nie rozmyte zgadywanie)
2. Istnieją konkretne parametry (find_similar, exact_match) o zdefiniowanym zachowaniu
3. Dowody istnieją w konkretnych plikach, które można zweryfikować
4. Stwierdzenie zostało zweryfikowane w konkretnej dacie

Anatomia rejestru Ground Truths

Ground truths żyją w rejestrach YAML pod ai_assets/reference/ground_truths.yaml. Każdy pakiet lub domena może mieć swój własny rejestr. Struktura wygląda tak:

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

Rejestr zawiera metadane o samej kolekcji, konfigurację renderowania na potrzeby generowania dokumentacji oraz same stwierdzenia. Każde stwierdzenie podlega ścisłemu schematowi walidowanemu przez modele 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

Jak agenci uzyskują dostęp do Ground Truths

Ground truths są udostępniane przez wiele kanałów:

1. Wyrenderowana dokumentacja

Polecenie orkestra sync przekształca rejestry YAML w czytelny markdown:

uv run orkestra sync

Generuje to pliki GROUND_TRUTHS.md, które są włączane do kontekstu agenta. Wyrenderowany wynik grupuje stwierdzenia według statusu i kategorii:

## 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. Wyszukiwanie CLI

Agenci z dostępem do powłoki mogą przeszukiwać ground truths programowo:

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

Funkcja wyszukiwania ocenia dopasowania w wielu polach z ważoną trafnością:

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

Gdy agenci są renderowani z definicji YAML, ich kontekst może odwoływać się do rejestrów ground truths:

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

To zapewnia, że odpowiednie ground truths są wczytane, zanim agent zacznie pracę.

Kategorie Ground Truths

Patrząc na nasze rejestry, ground truths skupiają się w kilku wzorcach:

Zasady produktowe

Ograniczenia dotyczące tego, czym produkt jest, a czym nie jest:

„Maguyva jest tylko do odczytu w odniesieniu do repozytoriów użytkowników; jedynym zasobem, którego nie da się odbudować, jest płatny cache embeddingów.” (GT-MAG-001)

Granice architektury

Gdzie leżą odpowiedzialności i dlaczego:

„Granice pipeline’u i Maguyva są celowe: pipeline jest wielokrotnego użytku, Maguyva przechowuje logikę specyficzną dla kodu, a CQRS oddziela zapisy etapów od odczytów serwera.” (GT-MAG-006)

Zasady antyhalucynacyjne

Jednoznaczne mandaty utrzymujące kontrakty narzędzi deterministycznymi, a nie wywnioskowanymi:

„Rozmyte dopasowywanie symboli jest opcjonalne (opt-in) przez find_similar=true. Domyślne zachowanie zwraca puste wyniki dla nieistniejących symboli; exact_match=true wymusza ścisłe dopasowywanie i wyłącza wszystkie rozmyte fallbacki.” (GT-MAG-015)

Bramki jakości

Standardy, które muszą być utrzymywane:

„Zmiany we współdzielonej infrastrukturze (post_filters.py, ekstraktory relacji, współdzielone handlery) MUSZĄ być zwalidowane względem WSZYSTKICH obsługiwanych języków przez generowanie pełnego manifestu przed commitem. Walidacja jednego języka jest niewystarczająca dla kodu współdzielonego.” (GT-MAG-036)

Wzorce kodu

Wymagania implementacyjne:

„Używaj asyncio.to_thread() do pracy obciążającej CPU w kontekstach asynchronicznych; przestarzały wzorzec loop.run_in_executor() nie powinien być używany w nowym kodzie.” (GT-MAG-018)

Cykl życia Ground Truth

Ground truths nie są statyczne. Ewoluują przez zdefiniowany cykl życia:

Tymczasowy

Proponowana prawda w trakcie oceny. Stwierdzenie jest zapisane, ale może się zmienić:

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

Aktualny

Zweryfikowana prawda, której agenci muszą przestrzegać. Dowody zostały zwalidowane:

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

Przestarzały

Prawda, która już nie ma zastosowania. Zachowana jako odniesienie historyczne ze wskazaniem tego, co ją zastąpiło:

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

Dlaczego nie zwykła dokumentacja?

Dokumentacja służy innemu celowi. Wyjaśnia. Uczy. Może być niejednoznaczna, może używać kwalifikatorów takich jak „ogólnie” czy „zazwyczaj”.

Ground truths nie mogą być niejednoznaczne. To są asercje. Albo mają zastosowanie, albo nie.

Rozważ tę różnicę:

Dokumentacja: „API zazwyczaj zwraca puste wyniki, gdy symbol nie zostanie znaleziony, choć w niektórych konfiguracjach może być włączone rozmyte dopasowywanie.”

Ground Truth: „Domyślne zachowanie zwraca puste wyniki dla nieistniejących symboli; exact_match=true wymusza ścisłe dopasowywanie i wyłącza wszystkie rozmyte fallbacki.”

Pierwsze jest pomocne dla ludzi uczących się systemu. Drugie jest gotowe do działania dla agentów podejmujących decyzje.

Wskazówki dla agenta: rób i unikaj

Niektóre ground truths zawierają jednoznaczne wskazówki dla agenta:

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

To usuwa niejednoznaczność. Agent czytający to wie nie tylko, co jest prawdą, ale jakie działania ta prawda implikuje.

Weryfikacja i utrzymanie

Ground truths wymagają utrzymania. Śledzimy:

• last_verified: kiedy ktoś potwierdził, że stwierdzenie wciąż się utrzymuje
• evidence: pliki, które potwierdzają stwierdzenie (można sprawdzić ich istnienie)
• source: skąd pochodzi prawda (inspekcja CLI, przegląd architektury, wnioski po incydencie)

Ground truth z nieaktualnymi datami weryfikacji lub zerwanymi linkami do dowodów jest sygnałem do zbadania. Albo prawda wciąż jest ważna i wymaga ponownej weryfikacji, albo rzeczywistość się zmieniła i prawda wymaga aktualizacji.

Prawdziwe przykłady z produkcji

Granica bezpieczeństwa

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

Ten ground truth zapobiega klasie błędnie pojętych „usprawnień bezpieczeństwa”, które zepsułyby produkt.

Dokładność w czasie ekstrakcji

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

To wynikło z bolesnego doświadczenia. Agenci łatali zawodzące pakiety językowe, dodając filtry działające tylko w walidatorze, które sprawiały, że harness testowy wyglądał na bardziej zielony, podczas gdy działający ekstraktor Maguyva wciąż emitował złe krawędzie. Ta zasada zmusza naprawy z powrotem na prawdziwą ścieżkę: konfigurację YAML, zapytania lub handlery.

Filtrowanie wielopoziomowe

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

To zapobiega dodawaniu przez agentów filtrów w niewłaściwym miejscu — częstemu błędowi, który powodował regresje dokładności.

Integracja z systemem orkiestracji

Ground truths to jedna warstwa szerszego systemu kontekstu:

1. Decyzje architektoniczne (ADR) - Zapisują, dlaczego wybraliśmy podejście A zamiast B
2. Ground Truths - Stwierdzają, co jest jednoznacznie prawdziwe teraz
3. Wzorce domenowe - Opisują, jak robić rzeczy poprawnie
4. Antywzorce - Opisują, czego unikać i dlaczego

Agent pracujący w systemie ma dostęp do wszystkich czterech. Ground truths dostarczają faktycznej kotwicy, decyzje wyjaśniają historię, wzorce prowadzą implementację, a antywzorce ostrzegają przed pułapkami.

Mierzenie wpływu

Od czasu wprowadzenia ground truths zaobserwowaliśmy:

• Mniej cykli „napraw halucynowaną naprawę”
• Bardziej pewne decyzje agentów, gdy fakty są jasne
• Lepsze przeglądy PR, ponieważ oczekiwania są jednoznaczne
• Skrócony czas wdrażania nowych agentów (i ludzi)

Inwestycja w utrzymanie ground truths zwraca się w postaci mniejszej liczby debugowań i wyraźniejszych granic systemu.

Jak zacząć

Aby dodać ground truth do swojego systemu:

1. Utwórz ground_truths.yaml w katalogu ai_assets/reference/ swojego pakietu
2. Zdefiniuj metadane i konfigurację renderowania
3. Dodaj stwierdzenia zgodnie ze schematem
4. Uruchom uv run orkestra sync, aby wygenerować dokumentację
5. Uwzględnij rejestr w kompozycji kontekstu agenta

Zacznij od faktów, które powodują najwięcej zamieszania, lub ograniczeń, które są najczęściej łamane. To Twoje najbardziej wartościowe ground truths.

Podsumowanie

Agenci AI będą halucynować. To ich natura. Ale możemy tworzyć środowiska, w których halucynacja jest ograniczona, w których pewne fakty są nienegocjowalne, w których agenci mogą sprawdzić swoje założenia względem zweryfikowanej rzeczywistości.

Ground truths nie są kompletnym rozwiązaniem. Wymagają utrzymania. Mogą stać się nieaktualne. Dodają narzut do procesu rozwoju.

Ale dają coś wartościowego: wspólne słownictwo faktów, któremu ludzie i agenci mogą zaufać. W świecie, w którym agenci coraz częściej uczestniczą w tworzeniu oprogramowania, ten wspólny fundament staje się niezbędny.

Alternatywą są niekończące się cykle agentów popełniających pewne siebie błędy i ludzi je korygujących. Ground truths przerywają ten cykl, czyniąc korekty jednoznacznymi i trwałymi.

Twoi agenci zasługują na to, by wiedzieć, co jest prawdą. Powiedz im.