Базові істини: прив'язування AI-агентів до реальності

Числа в цьому дописі відображають стан системи на момент публікації (січень 2026). Актуальні цифри дивіться на нашій сторінці команди.

AI-агенти надзвичайно здібні. Вони вміють міркувати, синтезувати та генерувати. Але в них є фундаментальна слабкість: вони вигадують. Не зловмисно, а впевнено. Агент може вигадати параметри API, яких не існує, послатися на конфігурації, які ніколи не визначалися, або застосувати патерни з даних навчання, що суперечать вашій реальній архітектурі.

Стандартне пом’якшення — «дати агенту більше контексту». Але контекст може суперечити сам собі. Документація розходиться з реалізацією. Коментарі брешуть. Навіть код може ввести в оману, якщо його читати без розуміння наміру.

Нам потрібно було щось конкретніше. Щось, що не можна проігнорувати чи неправильно витлумачити. Щось, що прив’язувало б агентів до перевірюваної реальності.

Ми називаємо їх базовими істинами (Ground Truths).

Що таке базова істина?

Базова істина (ground truth) — це явне, версійоване твердження факту, яке агенти зобов’язані поважати. Це не документація. Це не коментар. Це повноцінна сутність у системі з:

• Унікальним ідентифікатором (на кшталт GT-MAG-015 чи GT-MAG-036)
• Статусом життєвого циклу (поточний, попередній чи застарілий)
• Сферою дії (уся платформа, конкретний пакет чи домен)
• Доказами (шляхи до файлів, URL чи посилання, що доводять твердження)
• Настановами для агента (явні інструкції «робити/уникати»)

Ось приклад з нашої платформи інтелекту коду 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

Це не проза. Це контракт. Коли агент натрапляє на цю базову істину, він знає:

1. Поведінка за замовчуванням детермінована (порожні результати, а не нечіткі здогадки)
2. Є конкретні параметри (find_similar, exact_match) з визначеною поведінкою
3. Докази існують у конкретних файлах, які можна перевірити
4. Твердження було перевірене конкретної дати

Анатомія реєстру базових істин

Базові істини живуть у 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..."
    ...

Реєстр містить метадані про саму колекцію, конфігурацію рендерингу для генерації документації та самі твердження. Кожне твердження підпорядковується суворій схемі, валідованій моделями 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

Як агенти отримують доступ до базових істин

Базові істини надаються через кілька каналів:

1. Відрендерена документація

Команда orkestra sync перетворює YAML-реєстри на читабельний markdown:

uv run orkestra sync

Це генерує файли GROUND_TRUTHS.md, які включаються в контекст агента. Відрендерений вивід групує твердження за статусом і категорією:

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

Агенти з доступом до shell можуть шукати базові істини програмно:

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. Композиція контексту

Коли агенти рендеряться з YAML-визначень, їхній контекст може посилатися на реєстри базових істин:

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

Це гарантує, що відповідні базові істини завантажуються до того, як агент почне роботу.

Категорії базових істин

Поглянувши на наші реєстри, можна побачити, що базові істини групуються в кілька патернів:

Принципи продукту

Обмеження щодо того, чим продукт є, а чим не є:

«Maguyva доступний лише для читання щодо репозиторіїв користувачів; єдиний актив, який неможливо відновити — це платний кеш ембеддингів». (GT-MAG-001)

Архітектурні межі

Де живуть обов’язки і чому:

«Межі між pipeline та Maguyva навмисні: pipeline перевикористовуваний, Maguyva утримує специфічну для коду логіку, а CQRS відокремлює записи етапів від читань сервера». (GT-MAG-006)

Правила проти галюцинацій

Явні мандати, що утримують контракти інструментів детермінованими, а не виведеними:

«Нечітке зіставлення символів опційне через find_similar=true. Поведінка за замовчуванням повертає порожні результати для символів, яких не існує; exact_match=true примушує суворе зіставлення і вимикає всі нечіткі резервні варіанти». (GT-MAG-015)

Гейти якості

Стандарти, які потрібно підтримувати:

«Зміни до спільної інфраструктури (post_filters.py, екстрактори зв’язків, спільні обробники) МАЮТЬ бути валідовані проти УСІХ підтримуваних мов через генерацію повного маніфесту перед комітом. Валідація однієї мови недостатня для спільного коду». (GT-MAG-036)

Патерни коду

Вимоги до реалізації:

«Використовуйте asyncio.to_thread() для CPU-навантаженої роботи в асинхронних контекстах; застарілий патерн loop.run_in_executor() не слід використовувати в новому коді». (GT-MAG-018)

Життєвий цикл базової істини

Базові істини не статичні. Вони еволюціонують через визначений життєвий цикл:

Попередня (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)

Перевірена істина, яку агенти зобов’язані поважати. Докази валідовано:

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

Чому не просто документація?

Документація слугує іншій меті. Вона пояснює. Вона навчає. Вона може бути розпливчастою, може використовувати уточнення на кшталт «зазвичай» чи «як правило».

Базові істини не можуть бути розпливчастими. Це твердження. Вони або застосовуються, або ні.

Розгляньмо різницю:

Документація: «API зазвичай повертає порожні результати, коли символ не знайдено, хоча нечітке зіставлення може бути увімкнене в деяких конфігураціях».

Базова істина: «Поведінка за замовчуванням повертає порожні результати для символів, яких не існує; exact_match=true примушує суворе зіставлення і вимикає всі нечіткі резервні варіанти».

Перше корисне для людей, які вивчають систему. Друге придатне до дії для агентів, які ухвалюють рішення.

Настанови для агента: робити й уникати

Деякі базові істини містять явні настанови для агента:

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

Це усуває неоднозначність. Агент, що це читає, знає не лише те, що є правдою, а й те, які дії ця правда передбачає.

Перевірка та підтримка

Базові істини потребують підтримки. Ми відстежуємо:

• last_verified: коли хтось підтвердив, що твердження досі справджується
• evidence: файли, що доводять твердження (можна перевірити на існування)
• source: звідки походить істина (перевірка через CLI, архітектурний огляд, висновки після інциденту)

Базова істина із застарілими датами перевірки чи розбитими посиланнями на докази — сигнал для розслідування. Або істина все ще дійсна й потребує повторної перевірки, або реальність змінилася й істину потрібно оновити.

Реальні приклади з продакшну

Межа безпеки

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

Ця базова істина запобігає класу помилкових «покращень безпеки», які зламали б продукт.

Точність на момент вилучення

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

Це прийшло з болючого досвіду. Агенти виправляли мовні пакети, що падали, додаючи фільтри лише на рівні валідатора, які робили тестовий харнес зеленішим на вигляд, тоді як живий екстрактор Maguyva все ще видавав неправильні ребра. Правило змушує повертати виправлення в реальний шлях: конфігурацію 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).

Це не дозволяє агентам додавати фільтри в неправильному місці — поширена помилка, що спричиняла регресії точності.

Інтеграція з системою оркестрації

Базові істини — це один шар ширшої системи контексту:

1. Архітектурні рішення (ADR) — фіксують, чому ми обрали підхід A, а не B
2. Базові істини — стверджують, що є безумовно правдивим прямо зараз
3. Доменні патерни — описують, як робити щось правильно
4. Антипатерни — описують, чого уникати і чому

Агент, що працює в системі, має доступ до всіх чотирьох. Базові істини дають фактичний якір, тоді як рішення пояснюють історію, патерни спрямовують реалізацію, а антипатерни попереджають про пастки.

Вимірювання впливу

Відколи ми впровадили базові істини, ми спостерігаємо:

• Менше циклів «виправити галюциновану правку»
• Впевненіше ухвалення рішень агентами, коли факти чіткі
• Кращі перегляди PR, бо очікування явні
• Скорочений час онбордингу для нових агентів (і людей)

Інвестиція в підтримку базових істин окупається зменшеним обсягом налагодження та чіткішими межами системи.

Початок роботи

Щоб додати базову істину до вашої системи:

1. Створіть ground_truths.yaml у теці ai_assets/reference/ вашого пакета
2. Визначте метадані та конфігурацію рендерингу
3. Додайте твердження за схемою
4. Запустіть uv run orkestra sync, щоб згенерувати документацію
5. Включіть реєстр у композицію контексту агента

Почніть з фактів, що спричиняють найбільше плутанини, або обмежень, які порушують найчастіше. Це ваші найцінніші базові істини.

Висновок

AI-агенти галюцинуватимуть. Така їхня природа. Але ми можемо створювати середовища, де галюцинації обмежені, де певні факти не підлягають обговоренню, де агенти можуть звіряти свої припущення з перевіреною реальністю.

Базові істини — не повне рішення. Вони потребують підтримки. Вони можуть застарівати. Вони додають накладні витрати до процесу розробки.

Але вони дають щось цінне: спільний словник фактів, якому можуть довіряти і люди, і агенти. У світі, де агенти дедалі більше беруть участь у розробці програмного забезпечення, ця спільна основа стає необхідною.

Альтернатива — нескінченні цикли, коли агенти впевнено помиляються, а люди їх виправляють. Базові істини розривають цей цикл, роблячи виправлення явними й стійкими.

Ваші агенти заслуговують знати, що є правдою. Скажіть їм.