Ground Truths: обоснованные истины, заземляющие AI-агентов в реальности

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

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

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

Нам было нужно что-то более явное. Что-то, что нельзя было бы проигнорировать или неверно истолковать. Что-то, что заземляло бы агентов в проверяемой реальности.

Мы называем это обоснованными истинами (Ground Truths).

Что такое обоснованная истина?

Обоснованная истина — это явное, версионируемое утверждение факта, которое агенты обязаны уважать. Это не документация. Это не комментарий. Это полноценная сущность в системе, обладающая:

• Уникальным идентификатором (вроде 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

Агенты с доступом к шеллу могут искать обоснованные истины программно:

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)

Жизненный цикл обоснованной истины

Обоснованные истины не статичны. Они проходят через определённый жизненный цикл:

Предварительная

Предлагаемая истина на стадии оценки. Утверждение записано, но может измениться:

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

Текущая

Проверенная истина, которую агенты обязаны уважать. Доказательства прошли валидацию:

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

Устаревшая

Истина, которая больше не применяется. Сохраняется для исторической справки со ссылкой на то, что её заменило:

- 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-агенты будут галлюцинировать. Такова их природа. Но мы можем создавать среды, в которых галлюцинации ограничены, где определённые факты не подлежат обсуждению, где агенты могут сверять свои предположения с проверенной реальностью.

Обоснованные истины — не полное решение. Они требуют поддержки. Они могут устаревать. Они добавляют накладные расходы в процесс разработки.

Но они дают нечто ценное: общий словарь фактов, которому могут доверять и люди, и агенты. В мире, где агенты всё активнее участвуют в разработке ПО, этот общий фундамент становится необходимым.

Альтернатива — бесконечные циклы, в которых агенты уверенно ошибаются, а люди их исправляют. Обоснованные истины разрывают этот цикл, делая исправления явными и долговечными.

Ваши агенты заслуживают знать, что истинно. Скажите им.