Документация как тест. Почему LLM галлюцинирует не из-за себя — а из-за вас

О детерминированной документации, коллапсе суперпозиции и том, почему пустой файл опаснее отсутствующего

LLM галлюцинирует не потому что она сломана. Она галлюцинирует потому что ваша документация — нет.

Точнее: потому что она написана для людей. Люди умеют читать между строк, достраивать из контекста, брать паузу когда что-то непонятно. LLM не берёт паузу. Она заполняет пустоту — тихо, уверенно, правдоподобно. Из своих весов, не из вашей системы.

Это не баг. Это физика.

С чего всё началось

Я работал с большим корпусом технической документации. Сотни файлов, десятки сервисов, каждый со своей пирамидой слоёв. Первый вопрос который возник: как проверить что это работает?

Не “файлы существуют” — это линтер. Не “ссылки не битые” — это тоже линтер. А именно работает: любой агент, прочитав это, придёт к правильному пониманию системы?

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

Документационный e2e

В обычном e2e тесте запрос проходит через цепочку сервисов. Проверяем каждый шаг.

В документационном e2e вопрос проходит через цепочку файлов. Проверяем каждый ответ.

Обычный e2e: запрос → сервис A → сервис B → результат тест: каждый сервис вернул правильное? Документационный e2e: вопрос → файл A → файл B → ответ тест: каждый файл даёт правильный, полный, консистентный ответ?

Ключевое отличие от линтера: линтер проверяет форму. Документационный e2e проверяет смысл. Файл может существовать, ссылки могут работать — и при этом документация будет нерабочей. Агент прочитает её и построит модель. Неверную. С уверенностью сто процентов.

Принцип который из этого следует: что не написано — не существует. LLM не инферирует, не достраивает, не догадывается из контекста. Если правило есть только в одном файле из двадцати — для всех агентов, читающих остальные девятнадцать, его нет. Если раздел называется “business-logic” но содержит только заголовки без текста — для системы бизнес-логики не существует. Пустой файл хуже отсутствующего: он сообщает “здесь ничего нет” вместо “сюда ещё не дошли”.

Пирамида слоёв и болезнь входной точки

Самая распространённая структурная болезнь любой документации — я называю её гравитация README.

Информация накапливается там где её первым делом открывают. В GitHub-проектах это README. В корпоративных системах — главная страница вики. В личных базах знаний — первый блок дашборда.

Когда всё важное свалено в одном месте — агент читает входную точку, считает что понял всё, и не идёт глубже. Потому что там написано достаточно, чтобы построить модель. Но модель неполная. Агент этого не знает.

Решение — явная пирамида слоёв где каждый уровень расширяет предыдущий, но не повторяет его:

README.md → один абзац + ссылка. Если больше 7 строк — это уже следующий слой. business-logic.md → зачем, для кого, по каким правилам. Без технических деталей. service-logic.md → компоненты, архитектура, таблица взаимодействий. flows.md → пошаговые сценарии с конкретными данными. Читается как тест-кейс. specs → точные поля, типы, форматы. Только факты, без объяснений.

Правило строгое: README — только навигация. Не анонс, не краткое содержание, не избранное. Навигация. Если в README есть бизнес-правило — пирамида сломана, агент построит неполную модель со стопроцентной уверенностью.

Три критических ловушки пирамиды:

Информация на чужом слое. Бизнес-правила в README вместо business-logic.md. Агент не знает что пропускает — он уверен что уже прочитал главное.

Ссылка на пустой файл. README говорит “подробнее → business-logic.md”. Business-logic.md содержит только заголовки. Агент знает что детали есть. Их нет. Разница принципиальная.

Незаполненный шаблон принят за факт. Файл содержит `___` или `{placeholder}`. Агент видит “строку таблицы” и считает поле задокументированным.

18 ловушек галлюцинаций

Галлюцинация — предсказуемый ответ на конкретный паттерн в тексте. Не случайность. Не особенность модели. Структурная неизбежность.

Это означает: можно составить каталог паттернов которые детерминированно вызывают неверный вывод. Не “иногда” — всегда.

Несколько ключевых:

Плавающее местоимение. “Система получает запрос. Она передаёт его на обработку. После этого компонент проверяет права.” При двух и более субъектах в тексте LLM выбирает кто есть кто по своим весам. Исправление: везде явные имена, никаких “она”, “он”, “это”.

Заголовок противоречит телу. Заголовки весят больше в трансформере. Если раздел называется “Синхронная обработка” а внутри описывается очередь — LLM возьмёт заголовок. Читатель-человек заметит. Агент — нет.

Неопределённый модальный глагол. “Компонент может обратиться к внешнему сервису.” Когда? При каком условии? Агент в одном контексте добавит вызов, в другом нет. Недетерминированное поведение закодировано прямо в тексте.

Пассивный залог без актора. “Сообщение нормализуется и передаётся на обработку.” Кто нормализует? Кто передаёт? В системе с десятью сервисами — гарантированно неверный выбор.

Конфабуляция без источника. Агент утверждает конкретный факт о системе. Правдоподобно, согласуется с контекстом — но нигде не написано. Отличается от галлюцинации тем что звучит убедительно. Поймать без проверки невозможно.

Полный каталог — восемнадцать таких ловушек. Прогоняется как чеклист на каждом файле. Это не редактура стиля. Это инженерная верификация: текст либо детерминирован при чтении LLM, либо нет.

Коллапс суперпозиции

Это самая нетривиальная часть — и самая важная.

Два файла описывают одно и то же. Один говорит X, другой говорит Y. Оба написаны в разное время, оба верны со своей точки зрения. Когда LLM встречает такое противоречие — она не останавливается. Не сигнализирует. Она тихо схлопывается: выбирает одну версию и едет дальше с уверенностью сто процентов. Без следа.

Это хуже обычной галлюцинации. Галлюцинация не стыкуется ни с чем — её можно поймать. Коллапс стыкуется с одной из реальных версий. Его почти невозможно заметить.

Решение — COLLAPSE-протокол: явный маркер каждый раз когда агент делает выбор между конкурирующими описаниями.

[COLLAPSE:RED] ВЫБРАНО: версия из файла A АЛЬТЕРНАТИВА: версия из файла B ПРИЧИНА: более поздний источник, но противоречие требует разрешения человеком

Четыре уровня:

RED — принципиальное противоречие. Стоп. Не продолжать до разрешения человеком.

YELLOW — детали расходятся. Разные формулировки одного факта. Продолжить, пометить.

GRAY — терминологическое расхождение. Разные слова для одного понятия.

UNRESOLVED — расхождение замечено, источник не установлен. Минимальный маркер лучше тишины.

Принцип: любой выбор между двумя версиями — маркер. Неважно насколько очевиден правильный вариант. Если выбор был сделан — он должен быть виден. Это превращает невидимую ошибку в явную точку для разрешения.

Специализация против универсальности

Первый соблазн: один умный агент который читает всё, анализирует всё, исправляет всё.

Проблема: один агент — одна точка ятрогении. Ятрогения: лечишь одно, ломаешь рядом стоящее. Агент который одновременно читает, анализирует и исправляет — перегружен. Делает всё посредственно. И у него слишком много степеней свободы для ошибки.

Система работает через специализацию:

Читатель — только читает и строит модель. Не ищет ошибки. Зеркало: что отразилось — то отразится у любого агента.

Верификатор — прогоняет чеклист ловушек, эмитирует COLLAPSE-маркеры. Не исправляет.

Хирург — читает отчёт верификатора, вносит точечные правки. Не переписывает.

Зеркало — проверяет симметрию: каждая связь описана с обеих сторон?

Наполнитель — только добавляет. Никогда не правит существующее.

Каждое ограничение — убранная степень свободы для ошибки. Агент который “только читает” физически не может ничего сломать. Агент который “только добавляет” — тоже.

Количество агентов не ограничено. Принцип один: одна ответственность, явные ограничения, никаких тихих решений без маркеров.

Ятрогения в промптах

Жёсткие ограничения в промптах заставляют агента давить информацию чтобы влезть в формат.

“Топ-5 проблем” — агент нашёл двенадцать, сообщил пять. Семь исчезли. Не потому что неважные — потому что лимит.

“Кратко” — теряются нюансы. Нюанс это не украшение, это деталь которая меняет вывод.

“Ровно 15 файлов” — агент прочитал двадцать восемь, сообщил о пятнадцати. Остальные закрыл как “вспомогательные”. Это не анализ. Это галлюцинация о содержимом непрочитанных файлов.

Правило: ограничивай тип вывода, не объём. “Пиши по шаблону” — да. “Ровно N пунктов” — никогда.

И главное: в системе нет неважных файлов. “Основное покрыто” — это не вывод, это рационализация неполного чтения. Неполный анализ не называется анализом.

Определение “документация прошла e2e”

Документация прошла если:

1. На все ключевые вопросы есть однозначные ответы в правильных файлах

2. Ответы консистентны — одно и то же описано одинаково везде

3. Граф связей симметричен — каждая связь описана с обеих сторон

4. Поток прослеживается от входа до выхода

5. Терминология едина — одно понятие, одно слово, везде

6. Нет сирот — каждый файл отвечает на чей-то вопрос

7. Нет пустых файлов на которые ведут ссылки

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

Почему это работает за пределами IT

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

Двадцать пять лет физического производства — это постоянная работа с теми же паттернами. Плавающие местоимения в техзаданиях. Заголовки которые противоречат телу в регламентах. Коллапс суперпозиции когда два исполнителя читают один документ и делают по-разному — и оба правы по своим параметрам.

Разница одна: в физическом производстве цена ошибки считается в деньгах и сроках. В документации для LLM цена считается в галлюцинациях которые не видно.

Паттерны нарушений везде одни:

- Слепые пятна: один участник не знает что делает другой

- Несимметричная осведомлённость: A знает о B, B не знает об A

- Коллапс: два документа описывают одно по-разному

- Конфабуляция: уверенное утверждение без источника

Везде одно определение “работает”: однозначные ответы, консистентность, симметрия, единая терминология.

Меняется контекст. Принцип один.

Вместо заключения

Это не инструмент. Не фреймворк который можно поставить и использовать.

Это методология — набор принципов из которых каждый строит реализацию под свой домен, свой объём, свои инструменты.

Главный принцип остаётся во всех реализациях: документация либо детерминирована, либо нет. Промежуточного состояния нет. Если два читателя — человек или машина — приходят к разным моделям, задача не решена.

Линтер проверяет форму. Этот метод проверяет смысл.

-----

Методология открыта: github.com/MMM-AI-10/doc-pipeline