Архитектурная выверка: когда система читает себя

Я сейчас пишу документацию. Восемьсот с лишним файлов — двадцать восемь сервисов, каждый со своей пирамидой слоёв: README, бизнес-логика, техническое устройство, сценарии, спецификации.

Работать с таким объёмом вручную нереально. Не потому что лень. А потому что человек физически не удерживает восемьсот файлов одновременно. Пишешь тридцатый сервис — и уже не помнишь точно как сформулировал первый. Каждое отдельное утверждение верно. Но где-то написал "может обратиться к сервису", где-то "обращается только если" — и это про одно и то же правило. Оба варианта разумны. Читатель выберет тот который совпадает с его картиной. Уверенно. Молча. Не туда.

Это не проблема качества текста. Это структурная неизбежность при большом объёме: информация которая очевидна автору в момент написания — недостаточно очевидна чтобы убрать пространство интерпретации у читателя.

Я запустил набор специализированных агентов которые читают документацию и составляют карту её собственной неопределённости. Не ищут баги. Не проверяют код. Задают один вопрос: если другой человек или другая машина прочитает это — придёт ли он к той же модели что у меня?

Результаты интересные.

Из двадцати восьми сервисов верхние — Orchestrator, Policy Engine, Workflow Engine — описаны подробно, с детальными flows и примерами. Нижние — Log Aggregator, Database Layer, Unified Config — описаны поверхностно, без спецификаций, иногда без понятного бизнес-смысла.

Это не архитектурное решение. Это психология строительства.

Строишь то что интересно — управление решениями, проверка прав, детерминированные планы. Документируешь то что видно. Фундамент закапывают и идут дальше. До тех пор пока он не перестаёт держать.

В физическом производстве я видел то же самое. Производственный процесс описан подробно — шаги, контроль качества, сроки. Логистика, склад, кладовщики — "ну это понятно, там всё просто". До тех пор пока машина не приехала в точку раз в месяц, а там некому принять и некому расписаться потому что "понятный" процесс никто не формализовал.

Это интереснее.

Orchestrator декларирует: агентность живёт в коде, LLM только инструмент. Верно. Но в сценариях выполнения есть шаг где LLM-компонент классифицирует намерение пользователя, и от уверенности этой классификации зависит весь дальнейший путь. Тоже верно. Граница между "LLM не принимает решений" и "LLM классифицирует с порогом confidence" нигде не проведена явно. Каждый читатель проводит её сам.

Dialog Tool декларирует: живой голос, с личностью, остро и человечно. Верно как декларация. Механика описана как таблица параметров в базе данных — tone, formality_level, humor_level от нуля до ста. Верно как реализация. Где именно параметр тридцать из ста становится "остротой" — не написано.

Log Aggregator в одном месте указывает лимит десять тысяч RPS, в другом тот же лимит но в минуту. Разница в шесть раз. Оба значения написаны одним автором. Система не противоречит сама себе — она содержит два верных описания одного факта с разным уровнем детализации, и читатель тихо выбирает одно.

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

Двадцать пять лет в физическом производстве — это постоянная работа с коллапсами схлопывания, только там они называются иначе.

Писать техническое задание на физическое производство — это глубоко профессиональная задача с очень конкретной ценой ошибки. Если не написал, не додумал, сформулировал двусмысленно — это вылезает косяком при производстве. И виноват только ты. Не исполнитель который "не так понял". Ты — потому что поставить задачу человеку намного сложнее чем объяснить машине. Машина не додумывает из вежливости. Человек додумывает всегда — из опыта, из контекста, из того как он привык. И додумывает по-своему.

Именно из написания таких ТЗ я набил руку думать процессом: как меня поймут, и поймут ли вообще. Каждый регламент, каждое техзадание — это упражнение в устранении пространства интерпретации. Не "напиши подробно", а "напиши так чтобы подробность не оставляла выбора".

Регламент говорит "проверь качество перед отгрузкой". Типограф проверил — качество в норме. Клиент получил тираж и возвращает — оттенок не тот. Оба правы по своим параметрам. Параметры нигде не примирены явно. И это ещё простой случай — когда параметр один и он физический. Сложнее когда параметров несколько и один из них субъективный: оттенок который типограф считает приемлемым, клиент считает браком, а заказчик вообще видит третьим. Все трое смотрят на один объект. Все трое уверены.

Это не проблема людей. Это проблема архитектуры описания.

Когда я начал работать с документацией для LLM — оказалось что это та же задача. Только исполнитель не человек с опытом и интуицией, а модель с весами и статистикой. Механизм схлопывания другой — результат тот же: читает своё, уверена в ста процентах.

Двадцать пять лет написания ТЗ в физике — это и есть фундамент методологии. Просто теперь исполнитель другой, а принцип один.

Раньше такой аудит занимал недели. Надо было самому пройти по всей документации, держать в голове противоречия, сопоставлять версии из разных файлов. Человек устаёт, теряет нить, начинает "основное покрыто".

Сейчас агент проходит двадцать восемь сервисов за один прогон и возвращает карту: вот где написано верно но двусмысленно, вот где два верных утверждения не примирены, вот где фундамент описан хуже чем фасад.

Скорость зайца. Но с нюансами.

LLM тоже ленива. Тоже додумывает. Тоже норовит написать "основное покрыто" и закрыть задачу. Тоже интерпретирует абстрактную инструкцию абстрактно. С ней тоже надо уметь договариваться — правильно ставить задачу, убирать пространство интерпретации, не давать уйти в среднее. Всё то же самое что с людьми, только быстрее и без обиды когда переспрашиваешь третий раз.

Главное отличие: люди додумывают из вежливости и молчат о противоречиях чтобы не выглядеть непонимающими или противоречие не такое яркое для конкретного человека. LLM додумывает из весов и тоже молчит — но хотя бы не обижается когда ловишь за руку. И в отличие от человека которому неловко признать что он не понял ТЗ — модель можно заставить показать где именно она схлопнулась.

Двадцать пять лет договариваться с людьми — хорошая подготовка к тому чтобы договариваться с моделями. Принципы те же. Просто собеседник не устаёт, не уходит в отпуск и не увольняется в самый неподходящий момент.

Архитектурная выверка это не разовая процедура. Это момент когда останавливаешься и спрашиваешь: если новый человек прочитает эту систему завтра — придёт ли он к той же модели что у меня сегодня?

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

Закрыть этот зазор — это и есть архитектурная выверка.