ИИ на пути к документации, которая всегда актуальна

Мы предлагаем автодокументацию на базе Кольца Автотестов. Жанр — быль: всё, что дальше, было на самом деле.

Можно ли просто попросить модель?

«Сделай пользовательскую документацию для этой программы и поддерживай её в актуальном состоянии».

Напишет. Быстро и гладко.

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

А проверить нечем. По старой документации хотя бы видно, что она старая.

А если система большая?

Тогда не напишет и этого. Окно даже у больших моделей — десятки тысяч строк кода, а биллинг или ERP — сотни тысяч, иногда миллионы.

Хотя дело не в окне. Агент не читает всё подряд, он ходит по коду выборочно, как человек. Не собирается другое — сквозная картина. Сценарий проходит через несколько модулей, через асинхронные стыки и через настройку, и этой связности в коде нигде не записано: она была в голове у того, кто писал.

Логи? Они покажут, какими путями ходят чаще. Ранжировать помогут, проверить правильность — нет: частым бывает и обходной путь, придуманный пользователями от безысходности.

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

А как её пишут сегодня?

Руками. Человек открывает работающую систему, проходит сценарий, снимает копии экрана, вставляет в документ и подписывает: «нажмите Сохранить». Один раз, ближе к сдаче.

Потом система меняется, а документ — нет.

Почему же его не поправят?

Потому что ничего не происходит. Неверная документация не роняет ни сборку, ни прод, не гасит лампочку, никого не будит ночью.

А когда пользователь не находит нужной кнопки, он звонит в поддержку — не автору руководства. До автора сигнал не доходит вовсе.

Что должно случиться, чтобы расхождение стало заметным?

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

Такая штука давно есть и называется автотест.

Так пусть ИИ и напишет автотесты?

Напишет. И по коду восстановит поведение, и по логам увидит, какими путями ходят пользователи.

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

Разработчик, когда изменяет код системы, знает, как это поменяет и сценарий работы. Записать его в эту минуту в автотест стоит почти ничего.

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

Вокруг Кодовой Базы получается как бы очень полезное и даже волшебное кольцо. Отсюда и название, с намеренной отсылкой к Толкину: одно кольцо, чтобы править всеми.

А кто пишет автотест — тот же, кто код?

Для человека — да. И не потому, что так велит TDD, а потому, что сценарий у него в голове ровно в эту минуту. Передавать его другому дорого и с потерями.

А с агентами у нас наоборот: один пишет автотесты, другой пишет код, который должен им соответствовать. И они спорят между собой, пока не сойдутся.

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

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

И что, кто-то так делает?

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

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

Сколько это стоит?

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

И пишет уже не на языке разработки. Хватает нескольких доступных примеров — переписки, записи разговора с ключевым специалистом, пары готовых инструкций — чтобы модель подхватила словарь и отраслевой сленг конкретной организации. Тот самый ubiquitous language, на котором говорит BizOps, она составляет себе сама и довольно быстро.

И не только текст. Из того же прохождения сценария получается и видеодокументация — теми же словами, только вслух.

А насколько сожмёт ИИ сами эти тридцать процентов — вопрос открытый и самый интересный.

И при чём тут тогда ИИ?

Раньше документацию читал человек. Теперь по ней работает ещё и агент, и ему нужно ровно то же самое — что в этой предметной области означает слово «правильно», в исполняемом виде.

Если по-матричному: не надо поручать людям машинную работу. Машинное здесь — пройти сценарий, снять экраны, собрать текст, держать его свежим. Отсюда и «авто» в автодокументации: её делает компьютер. Человеческое — знать, что значит «правильно», и объявить сценарий образцовым.

Guardrails мы переводим как «направляющие». И по смыслу это рельсы и есть: они не столько не дают съехать, сколько задают путь.

А первый кричал: «Куда хотим, туда едем И можем, если надо, свернуть» Второй отвечал, что поезд проедет Лишь там, где проложен путь

— «Разговор в поезде», Машина времени, 1983 (текст песни)

Кольцо и есть проложенный путь: сценарии объявлены, выполняются и проверяются.

Так сделаем мы эту сказку былью — или не в этот раз?

Сентябрь 2026. Текст собран из трёх голосовых записей и доведён вместе с ИИ-соавтором.