МАЯК: сначала документация, потом кнопки

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

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

Позже я увидел и саму проблему целиком: между аналитиком и тестировщиком нет конвейера. Требования живут в Confluence, тест-план — в голове и Excel, а посередине — ручной труд с копипастой.
Вот этот разрыв я и придумал как закрыть.

Дальше — история того, как я это делал: вскрытием собственного концепта и 58 специализированными блоками в финале.

Я собрал конвейер «ТЗ → канонизация → тест-дизайн → прогон» из 58 специализированных блоков с гейтами доверия: каждый критерий приёмки заземляется цитатой из исходника, серые зоны превращаются в вопросы, а не в угаданную конкретику, повторы бесплатны за счёт кэша. Проверил на синтетическом ТЗ с заложенными болезнями: 9 ловушек из 10 поймал автомат, десятую — человек с вопросником от машины; 26 вопросов стейкхолдерам за 90 секунд, 20 серых зон, 37 BDD-сценариев за 26 минут. Где платформа врёт и что не доработано — тоже в тексте.

Летом щёлкнуло

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

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

Суть: возложить на модель создание чернового варианта документации, который остаётся валидировать.
Так быстрее погружаешься в задачу и сразу выходишь на границу «тестирование / доработка документации» — процесс становится параллельным, а не последовательным.
Живёшь в последовательной парадигме — попадаешь в цикл: новая задача уже готова, а документацию написать полноценно не успеваешь (говорю исключительно про себя).

Июль: первый блин

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

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

Тут всё получилось не так радужно, не увидел прямой перспективы в концепте, отложил его "На подумать".

После Конференции: вскрытие

Сходив на очередную Конференцию я увидел, что идеи и задачи в целом схожи в комьюнити, и захотелось попробовать себя: как у меня получится реализовать задуманное.

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

Тут задача была куда нетривиальнее: разобрать на блоки и подблоки техническое задание.
Из первичных четырёх блоков система выросла в 32 блока тестирования и 26 аналитики.

Из четырёх блоков — 58

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

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

На макроуровне — экосистема из двух платформ и общей инфраструктуры, конвейер «ТЗ → тесты».

BA Co-Pilot — инструменты бизнес-аналитика: канонизация требований в EARS, User Stories (INVEST) и Use Cases, матрица CRUD с аудитом жизненного цикла сущностей, стресс-тест противоречий между разделами ТЗ, поиск «белых пятен» с готовым опросным листом для стейкхолдера, мастер-глоссарий и онбординг-паспорт для новых участников.

QA Platform — четыре ступени: Requirements Hub (критерии приёмки, серые зоны) → Test Design Hub (тест-кейсы, чек-листы, Gherkin BDD, трассируемость) → Automation Hub (Playwright TS/Python, AST-линтер, контур Self-Healing) → Execution & Triage (прогон в песочнице, триаж, черновики действий для Jira).

Сверху это скреплено мостом и обвязкой:

• мост BA → QA: канонизированная спецификация запускается в QA-конвейер без ручного переноса; мульти-ТЗ режим — анализ портфеля из 2–10+ ТЗ с выявлением межсистемных коллизий и «оборванных» цепочек;

• интеграции: Confluence (двунаправленная конвертация Wiki/XHTML ⇄ Markdown, публикация артефактов), Jira (черновики задач с маппингом приоритетов), Mattermost-бот, экспорт в Excel и Word (тест-планы в фирменном стиле), REST-шлюз на FastAPI с асинхронными задачами — всё это умеет подниматься в Docker одной командой;

• любая модель через OpenAI-совместимый API: облачные провайдеры или полностью локальный контур (Ollama / vLLM) — данные наружу не уходят в принципе;

• кэш ответов LLM: повторный анализ того же документа не расходует токены, прогоны воспроизводимы;

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

Форматы на входе: .docx, .doc, .txt, .md, .rtf, .pdf, для BA — ещё и веб-архивы Confluence (.mhtml). Запуск — двойным кликом по батнику, drag&drop файла на батник, консолью или через Docker.

В архиве версий теперь целый выводок предшественников; на каком по счёту «МАЯК» я остановился, честно, уже не скажу — имя осталось, потому что задача та же:
быть ориентиром в тумане требований.

Почему я не верю одному промпту

Зачем конвейер, если можно скормить ТЗ модели и попросить тест-план?
А потому что в этой задаче LLM галлюцинирует уверенно и красиво:

• модель «додумывает» требование, которого в ТЗ нет, и строит на него полноценный тест-кейс — выглядит безупречно;

• в сводке красуется «покрытие 100%», хотя часть критериев вообще не извлеклась, а часть извлеклась из воздуха;

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

• один и тот же промпт в двух сессиях даёт разные наборы кейсов, и понять, что изменилось, невозможно.

Отсюда принцип, на котором стоит вся платформа: 
LLM предлагает — гейты проверяют — человек смотрит только то, что не сошлось.

Это моя вторая статья про недоверие к моделям: в ScanReader я не верил модели на чтении документов; МАЯК — про то же недоверие, но на создании.

Конвейер: сверху и в разрезе

Сверху — пять ступеней:

ТЗ (.docx/.pdf/.mhtml/...)
  → BA Co-Pilot: канонизация EARS, глоссарий, CRUD, вопросники
  → мост BA → QA
  → QA: Блок 1 (требования) → Блок 2 (тест-дизайн) → Блок 3 (автотесты) → Блок 4 (прогон и триаж)
  → артефакты: Markdown, Word, Excel, Gherkin .feature, версии для Confluence

Путь одного документа по конвейеру — артефакт за артефактом:

В разрезе — та самая микросервисность. Те самые 32 блока тестирования и 26 аналитики раскрываются в узлы графов и их суб-шаги: у каждого — собственная задача, собственное состояние, собственный контракт данных.
Фрагменты зафиксированных последовательностей (топологии графов):

Блок 1: scout → reader (map-reduce слияние чанков) → ambiguity_checker → package_assembler
Блок 2: architect → traceability → checklist → bdd → e2e_journey → assembler
Блок 3: generator → linter (AST) → self-healing роутер → assembler
Блок 4: runner → triage → rag_embedder → git_manager → jira_slack → assembler
BA:     gap_detector → ears_standardizer → domain_clustering → glossary →
        story_usecase → consistency_guard → process_visualizer → assembler

Петля Self-Healing из Блока 3 — крупным планом:

Контракты данных всех узлов — типобезопасные Pydantic v2-схемы, порядок вызовов зафиксирован инвариантами (осознанный выбор: предсказуемость конвейера важнее «гибкости на бегу»), ответы LLM проходят обязательную очистку и валидацию. Добавлять новые блоки и собирать из них разные сценарии (block1, block2, combo, full) можно без риска для остального конвейера — реестр плагинов толерантен даже к сломанным модулям (они попадают в load_errors, не убивая процесс). Ровно та наращиваемость, которой не хватало монолиту.

Каждый запуск пишет артефакты в изолированную папку сессии (дата_Название_ТЗ), прогоны не затирают друг друга.
Если LLM недоступен — платформа честно сообщает об этом и работает на кэше, а не выдумывает результат.

Как МАЯК говорит «не знаю»

Собственно, чего я жду от машины, которой не доверяю: чтобы она честно говорила, что именно проверено, а что нет. Платформа никогда не говорит «100% подтверждено» — и вот чем это обеспечивается:

• заземление требований: каждый критерий приёмки обязан подтверждаться цитатой из исходного текста ТЗ. Цитата не нашлась — требование помечается, а не молча пропускается;

• серые зоны не маскируются: неоднозначные места ТЗ превращаются в вопросы к стейкхолдеру, а не в угаданную конкретику;

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

• строгий режим: при сбоях LLM запрещены синтетические fallback-данные; пустой ввод — гарантированная ошибка вместо «успеха с пустыми результатами».

Барьеры до кода — как устроены гейты:

Статусы прогона — это то, как Маяк взаимодействует с человеком:

Появление статусов — от исхода исполнения:

Проверка на себе: ТЗ с секретиками

Прежде чем писать это, я прогнал платформу на себе.
Взял синтетическое ТЗ «Система заказа гостевых пропусков» — написал с нуля, без клиентских данных, 3,3 тысячи символов — и заложил туда болезни живых ТЗ: противоречие по времени отмены (один пункт разрешает отмену «до начала визита», другой блокирует её за 15 минут), «быстро», «по возможности», «несколько» и безразмерный «большой поток».
Такое ТЗ не жалко показать целиком, поэтому дальше — живые фрагменты вывода, а не пересказ.

Все 32 критерия заземлены цитатами из исходника — ни один не выдуман.
Покрытие критериев тест-кейсами — 81,2%, и платформа сама предупреждает о шести непокрытых, вместо «100% готово».

Коллизия по отмене — как её видит платформа (AMB-12 из отчёта, дословно):

В окне 15 мин–2 часа отмена требует подтверждения администратора, но не определено: что происходит при молчании администратора до начала визита (заявка активна, гость приезжает — дедлок); может ли администратор аннулировать пропуск в последние 15 минут, когда отмена «блокируется системой»; и то, что блокировка «на уровне интерфейса» не защищает от прямого вызова API — ограничение обходится на серверной стороне.

Вопрос стейкхолдеру: 
Утвердите финальную матрицу отмены: (а) более 2 ч — сотрудник отменяет сам; 15 мин–2 ч — подтверждение администратора, при молчании N минут — эскалация или автоматическая отмена; менее 15 мин — только аннулирование администратором? (б) Подтвердите, что правило 15 минут валидируется на сервере.

BDD из границы «2 часа» (дословно из .feature):

Сценарий: [TC-3] Отмена за 1 ч 59 мин до визита: заявка переходит в «Отменена» только после подтверждения администратора
  Дано Заявка №103 (гость Сидоров Сидор Сидорович, визит сегодня в 15:00, статус «Новая»). Системное время — 13:01 (до визита 1 час 59 минут — верхняя граница класса «менее 2 часов»). Доступен администратор системы.
  Когда Сотрудник открывает «Мои заявки» и нажимает «Отменить заявку» для №103
  Тогда Система отображает сообщение «Отмена менее чем за 2 часа до визита требует подтверждения администратора»
  И До подтверждения администратором статус заявки №103 не меняется на «Отменена»
  И После подтверждения администратором статус заявки №103 — «Отменена»

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

Два вопроса из опросного листа (из 26, дословно):

Архитектору (SLA): Каковы точные числовые NFR: целевое время отклика API (P95/P99, мс), число одновременных пользователей и пиковый RPS в дни конференций? — «быстро» и «устойчиво при большом потоке» неизмеримы: проектировать инфраструктуру не на что.

Юристу/DPO: Какие ПДн гостей обрабатываются, на каком правовом основании, где хранятся и включена ли система в реестр операторов ПДн? — обработка без основания — прямой риск по 152-ФЗ.

А теперь честное, без чего цифры выше — враньё.
Первое: закладка «большой поток» QA-блоком не поймана — формулировка не выглядит неоднозначной, пока не спросишь «сколько именно»; поднял её опросный лист.
Считаю честно: 9 ловушек из 10 — автомат, десятая — человек с вопросником от машины на руках.
Второе: BA-канонизация местами обогащает текст — в коллизию SLA доставки письма она сама дописала «1 минуту», которой в ТЗ нет (в исходнике только «не позднее 5 минут»), а нумерация требований местами поехала (дубли REQ-26/27).
Я нашёл это только сверкой с исходником.
Вывод тот же, что во всей статье: машина ускоряет, финальная истина — ревью человеком.

Цифры без фанфар

• 862 автоматических теста с гейтом покрытия ≥ 85% (фактически 87.69%) на четырёх зонах платформы. Важно: это покрытие кода самого инструмента — оно говорит о том, что платформа не разваливается при рефакторингах, а не о «правильности» ваших тест-планов;

• полный сьют прогоняется за 20 минут; каждый старый баг в платформе закрыт регресс-тестом;

• это внутренние измерения зрелости кода, а не сравнение с рынком — открытого бенчмарка «ТЗ → тест-дизайн» в природе нет;

• экономию токенов даёт кэш: повторный анализ неизменённого документа бесплатен;

• 200+ реальных ТЗ через платформу — счёт набит не синтетикой, а папками сессий: каждое честное «не сошлось» оборачивалось правкой, и версии платформы итерировались по живым проколам;

• пилот на коллегах внутри компании — по итогам внесены коррективы. Это не цифра зрелости кода, а проверка на людях: где платформа удобна и где мешает, знаю не из догадок.

Кто что получает

1. Аналитик — вопросы, а не загадку. Белые пятна и противоречия ТЗ собираются в опросный лист — на созвон с Product Owner выходишь с конкретикой.

2. QA-инженер — исключения, а не всё подряд. Серые зоны помечены, трассируемость «критерий → кейс» есть у каждого пункта, покрытие чек-листа считается отдельной метрикой и не подменяет покрытие тест-кейсами.

3. Руководитель — портфель целиком. Мульти-ТЗ анализ: коллизии между системами, оборванные цепочки, сводный Master Test Plan по десяткам документов.

4. Новый участник — онбординг за вечер. Онбординг-паспорт и глоссарий проекта генерируются из тех же ТЗ.

5. Интегратор — без ритуалов. Артефакты публикуются в Confluence, приоритеты маппятся в Jira, отчёты уходят тредами в Mattermost.

И сразу про ожидания, чтобы никто не иллюзировал: «замены аналитика», «замены QA», «100% качества требований», «готовых к продакшену автотестов без ревью» и «работы на любом ТЗ» — не будет.
Реалистичная картина: машина извлекает, канонизирует и проверяет согласованность, человек разбирает серые зоны и принимает решения.

А что у соседей

Прямого аналога — системы, которая идёт от ТЗ через канонизацию требований к тест-дизайну с гейтами доверия — я не нашёл ни в open source, ни в SaaS.
Искал честно; звёздность GitHub указана на октябрь 2026, проверяется руками.
Соседи по задачам:

Картина, в общем, забавная.
Аналоги продают тот же объём, но за заоблачные деньги и без генерации от ТЗ.
Свежая волна OSS — spec-kit, browser-use — сильнее нас каждый в своей вертикали (спеки, живое исполнение), но решает соседние задачи и останавливается там, где начинается наша работа.
Пустой остаётся именно связка: ТЗ → канонизация → тест-дизайн → прогон, с честными статусами и локальным контуром.
Вклад проекта — не «ещё одна GPT-обёртка», а эта связка плюс enterprise-интеграции. При этом внутри — обычные открытые компоненты.

Каков итог всего этого?

Пробуйте, дерзайте - самые сумасбродные мысли реализуемы)
Вопрос лишь в вашем упорстве и желании получить результат - но результат не просто для галочки, а воспроизводимый, контролируемый

Так же прикладываю 2 своих открытых библиотеки:

Отрисовка схем, починка, контроль - через неё собственно и отрисованы все схемы, которые вы видите https://github.com/Riper21/MermaidGuard

Создание матриц трассируемости, тест-дизайна - он так же есть внутри проекта, его результаты вы видите ниже https://github.com/Riper21/TestCraft