Документация как тест. Почему LLM галлюцинирует не из-за себя — а из-за вас
О детерминированной документации, коллапсе суперпозиции и том, почему пустой файл опаснее отсутствующего
LLM галлюцинирует не потому что она сломана. Она галлюцинирует потому что ваша документация — нет.
Точнее: потому что она написана для людей. Люди умеют читать между строк, достраивать из контекста, брать паузу когда что-то непонятно. LLM не берёт паузу. Она заполняет пустоту — тихо, уверенно, правдоподобно. Из своих весов, не из вашей системы.
Это не баг. Это физика.
С чего всё началось
Я работал с большим корпусом технической документации. Сотни файлов, десятки сервисов, каждый со своей пирамидой слоёв. Первый вопрос который возник: как проверить что это работает?
Не “файлы существуют” — это линтер. Не “ссылки не битые” — это тоже линтер. А именно работает: любой агент, прочитав это, придёт к правильному пониманию системы?
Ответ оказался неожиданным. Документацию нужно тестировать — так же как тестируется сама система.
Документационный e2e
В обычном e2e тесте запрос проходит через цепочку сервисов. Проверяем каждый шаг.
В документационном e2e вопрос проходит через цепочку файлов. Проверяем каждый ответ.
Ключевое отличие от линтера: линтер проверяет форму. Документационный e2e проверяет смысл. Файл может существовать, ссылки могут работать — и при этом документация будет нерабочей. Агент прочитает её и построит модель. Неверную. С уверенностью сто процентов.
Принцип который из этого следует: что не написано — не существует. LLM не инферирует, не достраивает, не догадывается из контекста. Если правило есть только в одном файле из двадцати — для всех агентов, читающих остальные девятнадцать, его нет. Если раздел называется “business-logic” но содержит только заголовки без текста — для системы бизнес-логики не существует. Пустой файл хуже отсутствующего: он сообщает “здесь ничего нет” вместо “сюда ещё не дошли”.
Пирамида слоёв и болезнь входной точки
Самая распространённая структурная болезнь любой документации — я называю её гравитация README.
Информация накапливается там где её первым делом открывают. В GitHub-проектах это README. В корпоративных системах — главная страница вики. В личных базах знаний — первый блок дашборда.
Когда всё важное свалено в одном месте — агент читает входную точку, считает что понял всё, и не идёт глубже. Потому что там написано достаточно, чтобы построить модель. Но модель неполная. Агент этого не знает.
Решение — явная пирамида слоёв где каждый уровень расширяет предыдущий, но не повторяет его:
Правило строгое: README — только навигация. Не анонс, не краткое содержание, не избранное. Навигация. Если в README есть бизнес-правило — пирамида сломана, агент построит неполную модель со стопроцентной уверенностью.
Три критических ловушки пирамиды:
Информация на чужом слое. Бизнес-правила в README вместо business-logic.md. Агент не знает что пропускает — он уверен что уже прочитал главное.
Ссылка на пустой файл. README говорит “подробнее → business-logic.md”. Business-logic.md содержит только заголовки. Агент знает что детали есть. Их нет. Разница принципиальная.
Незаполненный шаблон принят за факт. Файл содержит `___` или `{placeholder}`. Агент видит “строку таблицы” и считает поле задокументированным.
18 ловушек галлюцинаций
Галлюцинация — предсказуемый ответ на конкретный паттерн в тексте. Не случайность. Не особенность модели. Структурная неизбежность.
Это означает: можно составить каталог паттернов которые детерминированно вызывают неверный вывод. Не “иногда” — всегда.
Несколько ключевых:
Плавающее местоимение. “Система получает запрос. Она передаёт его на обработку. После этого компонент проверяет права.” При двух и более субъектах в тексте LLM выбирает кто есть кто по своим весам. Исправление: везде явные имена, никаких “она”, “он”, “это”.
Заголовок противоречит телу. Заголовки весят больше в трансформере. Если раздел называется “Синхронная обработка” а внутри описывается очередь — LLM возьмёт заголовок. Читатель-человек заметит. Агент — нет.
Неопределённый модальный глагол. “Компонент может обратиться к внешнему сервису.” Когда? При каком условии? Агент в одном контексте добавит вызов, в другом нет. Недетерминированное поведение закодировано прямо в тексте.
Пассивный залог без актора. “Сообщение нормализуется и передаётся на обработку.” Кто нормализует? Кто передаёт? В системе с десятью сервисами — гарантированно неверный выбор.
Конфабуляция без источника. Агент утверждает конкретный факт о системе. Правдоподобно, согласуется с контекстом — но нигде не написано. Отличается от галлюцинации тем что звучит убедительно. Поймать без проверки невозможно.
Полный каталог — восемнадцать таких ловушек. Прогоняется как чеклист на каждом файле. Это не редактура стиля. Это инженерная верификация: текст либо детерминирован при чтении LLM, либо нет.
Коллапс суперпозиции
Это самая нетривиальная часть — и самая важная.
Два файла описывают одно и то же. Один говорит X, другой говорит Y. Оба написаны в разное время, оба верны со своей точки зрения. Когда LLM встречает такое противоречие — она не останавливается. Не сигнализирует. Она тихо схлопывается: выбирает одну версию и едет дальше с уверенностью сто процентов. Без следа.
Это хуже обычной галлюцинации. Галлюцинация не стыкуется ни с чем — её можно поймать. Коллапс стыкуется с одной из реальных версий. Его почти невозможно заметить.
Решение — COLLAPSE-протокол: явный маркер каждый раз когда агент делает выбор между конкурирующими описаниями.
Четыре уровня:
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