Я собрал карту своего продукта — а она начала давать то, чего я не планировал.

• 1. Что это
• 2. Зачем она нужна
• 3. Из чего состоит
• 4. Что уже собрано и что это дало
• 5. Как собирается — коротко
• 6. Инструкция для агента
• 7. Где применяли
• 8. Как поддерживать

1. Что это

Описание того, что продукт умеет сегодня: какие есть экраны, что на них делает пользователь, какие данные продукт хранит, что уже сделано, а что только обсуждается. Живёт не одним текстом, а папкой связанных файлов — состав в разделе 3. Пишется не по замыслу, а по факту — из кода и обхода живого интерфейса. Документация даёт третий источник: техническая (описания в базе знаний, задачи в трекере) объясняет, зачем функция задумывалась, пользовательские мануалы — как её объясняют клиенту. Но старший источник — код, подтверждённый обходом интерфейса: где документ расходится с продуктом, в карту идёт продукт, а расхождение записывается отдельно.

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

2. Зачем она нужна

Документация устаревает, карта — нет. Требования пишут до разработки, а потом их не правят. Через полгода в них написано одно, а в продукте другое. Карта собирается из того, что реально работает, поэтому по ней можно принимать решения.

Новый человек и агент входят в контекст за часы, а не за недели. Разработчик, аналитик или ИИ-агент читают один файл вместо того, чтобы разбирать код и опрашивать команду.

Видно, чего нет. Когда всё имеющееся выписано в одном месте, дыры становятся заметны сами: настройка есть, а сохранить её нельзя; поле есть, а подсказки нет. Отдельный раздел карты — список таких пробелов со ссылками на задачи.

Трекер обращений показывает не весь продукт. В задачи попадает то, о чём кто-то сообщил: дошёл, написал, объяснил, почему это мешает. Кто не разобрался и молча ушёл, в трекере не появляется никогда. Поэтому список пробелов, собранный по одному трекеру, всегда меньше реального: он описывает продукт глазами тех, у кого хватило сил пожаловаться. Карта собирается от продукта, а не от жалоб, и закрывает эту слепую зону.

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

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

3. Из чего состоит

Карта — это папка из нескольких файлов, а не один текст.

Раскадровка экрана

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

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

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

Пояснение к каждому кадру отвечает на один набор вопросов:

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

Правила, без которых набор кадров не имеет смысла:

• Кадр на каждое отличающееся состояние, а не один «как открылось»: каждый режим формы, каждая вкладка карточки, пустой список, служебные экраны. Кадр тратится там, где меняется состав полей, а не там, где подсвечена другая кнопка.
• Один экран — одна ширина окна и один объект. Иначе половина набора описывает уже другую запись, и сравнивать состояния между собой нельзя.
• Только чтение. Состояния, которые открываются лишь записью на сервере, не выдумываются: они перечислены отдельным списком с причиной, почему кадра нет.
• Пояснение пишется по открытому кадру, а не по имени файла: подписи ровно как в интерфейсе, включая опечатку; заблокированное поле — как заблокированное; пустой список — как пустой.
• Кадр главнее документа. Если он расходится с файлом экрана или с картой, правится документ, а не подпись под кадром. Так нашлось поле, которое убрали из кода, а из описания — нет.
• Перед сдачей — валидатор и рендер в браузере: пропавшие картинки, битые ссылки, одно пояснение, размноженное по десяти блокам, кадры, снятые не на том адресе или с ошибками запросов.

Объём одного экрана поэтому неравномерный: у простого списка — один-два кадра, у формы, вид которой зависит от режима, — полтора-два десятка.

4. Что уже собрано и что это дало

Летом 2026 года мы собрали карты двух продуктов из области около финтеха — около 50 экранов. Сущности и сквозные функции пока описаны у одного продукта из двух: 15 и 23 соответственно. Раскадровки тоже сняты пока у одного: 10 экранов, 64 кадра. Метод один: обход интерфейса плюс чтение кода, поверх — сверка с технической документацией, мануалами и задачами. Обе карты лежат в общем репозитории команды, и агенты всех, кто пишет код, берут их оттуда.

Что это дало за два месяца. Числа и подробности по каждому случаю — в разделе 7.

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

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

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

Тестирование перестало быть узким местом. Разработка шла быстрее, чем тестирование, и договориться не получалось: ни уговоры, ни разбор процесса не помогали. Тестировщики получили карту и агента: приходит задача из трекера — агент разбирает тикет и ветку, гоняет проверки по API и интерфейсу, смотрит логи стенда, пишет отчёт, часть задач сам двигает по статусам.

Итоги интересны динамикой, а не абсолютными цифрами — объём входа плавает, сравнивать «сколько штук» бессмысленно. Отчёт одного из двух тестировщиков за 15 июня – 7 августа 2026 (40 рабочих дней):

• пропускная способность выросла примерно втрое (с 3 задач в день в июне до 10–12 в августе) без роста штата;
• в прежнем объёме работы это около двух свободных дней из пяти;
• на вход/выход у одного человека: было ~15 задач в неделю → стало 45–50 — снова около ×3; на выходе появились ещё отчёты в базе знаний и заведённые баги, которых раньше на этом объёме не успевали;
• из задач, прошедших через агента, больше половины (45 из 81) он довёл до конца цикла сам: протестировал и сменил статус в трекере.

Абсолюты для порядка: 87 рабочих сессий, около 8 800 действий, из них около 5 500 команд в терминале, которые раньше набирали руками — но сами по себе они мало что говорят; важна смена режима.

Ключевой рост дал не «включили ИИ», а оснастка вокруг агента: 10 своих сценариев (проверка запроса на слияние, проверка на предрелизе, точечный ретест, заведение бага, разбор ошибок сервера, логи стенда, «что реально выложено» и др.). Динамика запусков: в июне почти ноль (2), в июле уже 46 только по основному сценарию, за весь период — 108. Эффект — полтора месяца упаковки своего процесса в агента. Побочный выход: набор из восьми автотестов Playwright по продукту писал тот же агент.

По проекту в целом та же динамика в долях от недельного входа (считали по метке в трекере или шаблонному отчёту в комментарии): май без агента — закрывали ~40% пришедшего, очередь +~50% к входу; конец июля с агентом — закрывали ~95%, очередь почти стоит, ~30% закрытых — прогоны агента. Сам тестировщик на дейли сказал, что времени стало хватать и появился запас на другие задачи.

Видны возможности продукта, не описанные нигде. Сверка кода со списком экранов вскрыла серверные запросы, которых не было ни в одном документе.

Беклог перестал быть разбросанным. Раздел «Пробелы продукта» держит в одном месте задачи трекера, идеи из базы знаний и локальные спецификации: что описано и не сделано, что сделано иначе, чем написано.

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

5. Как собирается — коротко

Работу делает ИИ-агент по заданной инструкции, по одному экрану за подход.

1. Смотрит экран глазами пользователя. Открывает тестовый стенд, проходит по вкладкам, снимает состав страницы и скриншоты. Ничего не меняет и не сохраняет — только чтение, чтобы не задеть данные.
2. Читает код. Что страница запрашивает у сервера, какие поля есть у данных, кому что видно. Подписи берёт из файлов с текстами интерфейса, а не придумывает.
3. Сверяет с документацией. Технические описания и задачи в трекере дают замысел и бизнес-контекст, пользовательские мануалы — то, что обещано клиенту. Отсюда же берётся список пробелов: что описано, но не сделано, и наоборот — что сделано иначе, чем написано.
4. Записывает в общем формате — назначение простым языком, содержание, данные, права, связи с другими экранами.
5. Собирает раскадровку — кадр на каждое отличающееся состояние экрана и пояснение к каждому кадру: зачем это состояние, какую работу пользователя закрывает, как сюда попасть, чем отличается от соседних, почему решение такое. Без раскадровки экран не считается описанным.
6. Отделяет факт от догадки. Всё, что не подтверждено интерфейсом или кодом, помечается как требующее проверки. Домысливать запрещено.

Обход одного экрана занимает один рабочий сеанс. Полная карта первого продукта собралась за несколько дней.

Приоритет источников. Главное — как продукт устроен в коде, и это подтверждено обходом через Playwright: экран открыт, поле или кнопка увидены живьём. Дизайн-описания писались до разработки и потом не правились, мануалы отстают от продукта, задачи описывают замысел, а не результат. Поэтому документация в карте — контекст и список расхождений, а не основание для записи «функция работает так». Если код и документ расходятся, в карту идёт код, а расхождение фиксируется отдельной строкой.

6. Инструкция для агента

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

Два типа файлов

Страницы и функции ссылаются друг на друга в обе стороны.

Жёсткое ограничение — только чтение. Разрешены переходы по адресам, вкладки, пагинация, смена периода, разворот блоков, скриншоты, чтение разметки страницы. Запрещено всё, что меняет данные: создать, сохранить, удалить, применить, отправить, загрузить файл. Если без запрещённого действия непонятно, как работает экран, — остановиться и спросить.

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

Шаги

1. Сверка с картой. Найти экран в списке адресов, зафиксировать каноническое название, номер раздела и имя файла. Нет в карте — сказать об этом. Файл уже есть — дополнять, не перезаписывать молча.
2. Обход интерфейса. Готовый шаблон сценария Playwright: вход, переход, снимок структуры — заголовки, вкладки, колонки таблицы, видимые кнопки — и скриншот всей страницы. Редирект, отказ в доступе или пустой экран не додумываем: пишем «доступ ограничен для демонстрационной учётной записи» и достраиваем из кода.
3. Чтение кода. Компонент — сервисы, условия отображения, права, параметры фильтров; шаблон — таблицы, вкладки, переходы; сервис — вызовы API; модели — поля; файлы локализации — точные подписи (источник истины для текста интерфейса); серверная часть — если запрос не виден в клиентском коде.
4. Сверка с документацией. Техническая база знаний, задачи в трекере, пользовательские мануалы. Отсюда берутся бизнес-контекст, раздел «Пробелы продукта» и список мест, где написанное расходится с работающим. Приоритет источников не обсуждается: расхождение решается в пользу кода и записывается отдельной строкой.
5. Сборка файла по скелету: назначение на языке пользователя, фильтры и период, содержание, API, модели, права, расхождения с документацией, связанные функции и страницы, входящие связи.
6. Раскадровка. Съёмка всех состояний экрана при одной ширине окна и на одной сущности, пояснение к каждому кадру по открытому кадру, отдельный список состояний, которые снять нельзя, и причина по каждому. В конце — валидатор и рендер страницы в браузере. Без раскадровки прогон экрана не завершён.
7. Связи. Страница ссылается на раздел карты, карта — на страницу; при появлении новой страницы обновляются уже описанные.
8. Отчёт: что создано, что подтверждено интерфейсом, что взято из кода, что осталось непроверенным.

Два правила, которые дают качество

• Факт и предположение разделены: непроверенное помечается «предположительно, требует проверки».
• Один экран — один чат. Параллельные агенты на несколько экранов не запускаются: расход контекста растёт быстрее пользы.

7. Где применяли

Карта пригодилась не только тем, для чего задумывалась.

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

Разбор обращений в поддержку поверх карты. К карте подключили всё, с чем клиент приходит: переписку и голосовые сообщения в мессенджерах, тикеты трекера, в которых фиксировались доработки. Вышло 21 820 сообщений и 786 обращений за два года.

По этому корпусу вместе с картой и мануалами построили граф связей — через Graphify. Узлы: коды ошибок и симптомы, оборудование, функции продукта, объекты платёжной части; связь — совместная встреча в одном обращении. Смысл не в частоте, а в узловых точках: через какие места проходит диагностика почти любого разговора. Вышло иначе, чем при простом подсчёте тем: самая массовая тема оказалась замкнутой внутри себя, а по-настоящему сквозной — выдача и привязка платёжных реквизитов устройству. Заодно кластеризация развела два кода отказа по разным сообществам и дала гипотезу, что это ошибки разной природы — настройки самого устройства против отказа на стороне внешнего провайдера.

Дальше карта, мануалы и граф вместе дали разбор узких мест на пути клиента. Работа начиналась как переписывание мануалов, а привела к другому выводу: непонятное место закрывается на четырёх слоях, и мануал среди них третий. Слои идут в строгом порядке — от фундамента наверх; на следующий поднимаемся, только если предыдущий вопрос не закрыл:

1. Переделать продукт и процессы — то, что клиент проходит целиком: путь от сайта до запуска устройства, порядок работы внутри компании, устройство самого продукта. Сюда ушёл переписанный путь клиента с задачами на доработку сайта, внутренних процессов и продукта. Самый нижний слой и самый дорогой: если вопрос рождается здесь, его не снимет ни подсказка, ни инструкция.
2. Починить интерфейс — сам экран, чтобы объяснять было нечего, и короткий текст на месте там, где без объяснения не обойтись. Не значок вопроса: значок никто не нажимает.
3. Написать короткий мануал — там, где без объяснения не обойтись. Первую инструкцию, по настройке цен на устройстве, собрали прямо по карте, не отвлекая разработчиков вопросами.
4. Положить вкладыш на один лист — как в коробке нового айфона: с чего начать после распаковки устройства.

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

Тестирование новых эпиков. Карта отдана тестировщикам как вход для агента: приходит эпик из трекера — агент находит по карте затронутые экраны, знает их состав, поля и правила проверки, собирает из этого сценарии и прогоняет их. До этого тестирование было узким местом всей разработки: разработчики сдавали быстрее, чем команда успевала проверять, и переговоры внутри команды ничего не меняли — не хватало не желания, а описания продукта, из которого сценарии собираются механически. Итоги по динамике — в разделе 4: примерно ×3 задач в день и на недельный вход/выход за полтора месяца, около двух свободных дней из пяти в прежнем объёме; рост за счёт упаковки процесса в сценарии агента, а не за счёт «включили ИИ». Абсолютные счётчики тут вторичны.

Разбор настроек одного экрана до уровня команд. Составили соответствие «настройка в интерфейсе → команда, уходящая на устройство → параметры». Описание экрана выросло с 398 до 651 строки, восемь находок разошлись на четыре заведённых бага, три решения «так задумано» и одну удалённую настройку.

Раскадровка вместо дизайнерской. Съёмка десяти экранов дала 64 кадра и заодно шесть находок, которых не видно в коде: на форме добавления стоит заголовок «обновление»; в колонке списка пустое значение выводится с опечаткой; в тексте служебного экрана зашита конкретная дата; во всех режимах на восемь позиций восьмая пара «цена — метка» заблокирована; одна из шестнадцати форм подключения платёжной части осталась без инструкции; незаконченный мастер настройки расходится с основной формой — на одну позицию меньше и опечатка в подписи шага. Из шести пунктов сразу в задачу ушёл один, остальные ждут ответа владельца, задумано ли так. Попутно сработало правило «перед заведением задачи проверь противоречащие открытые»: нашлась висевшая с прошлого года задача убрать из продукта часть способов подключения, и вместе с ней смысл находки менялся; ту задачу отменили. Ещё одна находка пришла из сверки кадра с описанием: поле на втором шаге регистрации давно убрали из кода, а из документа нет.

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

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

Описание собственной работы вовне. Карта — готовое подтверждение объёма и авторства продукта: что сделано, в каком виде и с какой глубиной.

8. Как поддерживать

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