ИИ додумывает за вас: почему это опасно и как Mermaid-диаграммы спасают проект

Тема: Проблема додумывания в ИИ-агентах и визуализация с помощью Mermaid · Использование Mermaid-диаграмм для контроля решений ИИ

Кратко

ИИ-агенты додумывают невысказанные требования, что может привести к ошибкам в коде. Статья предлагает использовать визуализацию с помощью Mermaid-диаграмм (sequence, flowchart, class, ER, state, mindmap) для быстрой проверки решений. Исследование Visa Research подтверждает, что без визуализации инженеры тратят много времени на понимание действий агента.

Главное

  • ИИ-агенты склонны додумывать невысказанные требования, что ведет к скрытым ошибкам.
  • Визуализация с помощью Mermaid-диаграмм позволяет за 5 секунд проверить логику агента.
  • Sequence diagram — первая диаграмма для выявления лишних шагов и сервисов.
  • Из 26 типов диаграмм Mermaid реально нужны 5-6: flowchart, sequence, class, ER, state, mindmap.
  • Работа с агентом должна включать короткий цикл: дал задачу -> визуализация -> проверка -> корректировка.
  • Современные инструменты (AgentVision) добавляют агентам способность визуально проверять результат.

Когда вы просите нейросеть написать код или спроектировать архитектуру, она не останавливается на том, что вы сказали. Она делает то, что вы не сказали. Каждый агент — мастер додумывания. Он берёт ваше неполное описание, пробегает по миллионам примеров в обучающей выборке и выдаёт «наиболее вероятное» завершение. И в девяти случаях из десяти это действительно то, что нужно. Но десятый случай — это ночь дебага, внезапный баг в проде или потерянные деньги.

Парадокс в том, что максимальный риск при работе с ИИ — не в его прямых ошибках. Ошибки компиляции или синтаксические ляпы агенты исправляют сами за пару итераций. Настоящая опасность — в тех компонентах решения, которые мы не предъявили как требования. Агент взял и добавил «наиболее вероятное». И это «наиболее вероятное» лишь вероятно, но не правильно.

Почему читать спекы бесполезно

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

Именно поэтому нужна визуализация класса bird’s-eye view. Взгляд сверху, который за пять секунд показывает, что именно собрался сделать агент. Не строки кода — а схему, граф, логику целиком. Только так можно быстро проверить: не додумал ли он чего-то лишнего, не пошёл ли по неверному пути, соответствует ли его решение вашим (возможно, невысказанным) ожиданиям.

Лень, перегрев и бессонные ночи

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

Я через это проходил. Не раз. Визуализация — единственный способ поймать такие проблемы за пять секунд. Если поленился нарисовать — готовься к ночи исправлений. Проверено на собственной шкуре.

Исследования подтверждают: проблема не единична. В работе 2025 года «Illuminating LLM Coding Agents» исследователи из Visa Research показали, что ML-инженеры тратят огромное количество времени на то, чтобы просто понять, что именно сделал кодовый агент. Без визуализации отследить эволюцию кода, сравнить итерации и выявить проблемные места практически невозможно. Агент недетерминирован — один и тот же промпт может породить совершенно разные архитектуры.

26 диаграмм, из которых агенты знают 2–3

Хорошая новость в том, что для быстрой проверки не нужно осваивать UML или рисовать Visio. Mermaid — текстовый язык диаграмм — поддерживается практически всеми агентами «из коробки». GitHub, Claude, VS Code, Notion — везде есть рендеринг Mermaid.

Плохая новость: в Mermaid доступно 26 типов диаграмм (по разным подсчётам — от 22 до 26), но агенты сами применяют лишь 2–3: flowchart и sequenceDiagram. Всё. Остальное лежит мёртвым грузом — и в промптах, и в головах разработчиков.

Так какие диаграммы реально стоит использовать?

Первым делом — sequence diagram

Я уже отвечаю на вопрос, который задал сам себе: какую диаграмму просить у агента первой? По моему опыту — sequence diagram . Это сценарий взаимодействия. Он показывает, кто кому и что отправляет, в каком порядке, какие данные передаются. Именно здесь агент допускает самые опасные «додумывания»: добавляет лишний шаг, вводит несуществующий сервис, придумывает API, которого нет.

Sequence diagram — это рентгеновский снимок логики. Если он не совпадает с тем, что у вас в голове — стоп. Требуйте от агента объяснений.

Обязательный набор: что должен знать каждый

Из 26 типов реально нужны пять-шесть. Остальные — либо для специфических задач, либо сырые (beta-версии, которые не везде рендерятся).

Обязательно:

Бесполезный балласт для большинства разработчиков: Pie chart (проценты и так видны), Quadrant chart (приоритеты — это не про код), Timeline, Kanban (для управления задачами есть другие инструменты), Packet diagram (для сетевых протоколов — удел единиц). C4Context и Requirement diagram — вещь, но нестабильная: requirementDiagram, как отмечают в сообществе Mermaid, до сих пор не поддерживается даже в GitHub и VS Code.

Принцип: не доверяй — проверяй через картинку

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

Современные инструменты уже идут дальше. Появляются системы вроде AgentVision, которые добавляют агентам «глаза» — они не только генерируют код, но и визуально проверяют результат, находят перегруженные элементы, ломаные макеты, ошибки в SVG. Но это следующий уровень. Пока хотя бы научитесь просить Mermaid у того агента, который уже стоит у вас в терминале.

P.S. А вы проверяете задумки ИИ визуально или доверяетесь его «наиболее вероятно»? Сколько раз это вас подводило?

Фрагменты

ИИ-агенты — это модели, которые берут неполное описание и выдают наиболее вероятное завершение, додумывая невысказанные требования.

Mermaid — текстовый язык диаграмм, поддерживаемый GitHub, Claude, VS Code, Notion.

Проблема не в прямых ошибках ИИ, а в невысказанных компонентах, которые агент добавляет как 'наиболее вероятное'.

Если поленился нарисовать диаграмму — готовься к ночи исправлений.

Работа с агентом: дал задачу — попросил визуализировать — проверил за 30 секунд — скорректировал — пошёл дальше.

Sequence diagram — это рентгеновский снимок логики, который показывает, кто кому и что отправляет.

Из 26 типов диаграмм Mermaid агенты сами применяют лишь 2-3: flowchart и sequenceDiagram.

Обязательный набор: flowchart, sequence, class, ER, state, mindmap.

Бесполезный балласт: Pie chart, Quadrant chart, Timeline, Kanban, Packet diagram.

Исследование Visa Research 'Illuminating LLM Coding Agents' показало, что ML-инженеры тратят много времени на понимание действий агента без визуализации.

Вопросы и ответы

Какую диаграмму Mermaid нужно просить у агента первой?
Sequence diagram, так как она показывает сценарий взаимодействия и ловит самые опасные додумывания.
Почему бесполезно читать сгенерированные ИИ спеки?
ИИ генерирует с чудовищной скоростью; читать самому — всё равно что искать иголку в стоге сена, который растёт на глазах.
Какие диаграммы Mermaid обязательны для проверки?
Flowchart, sequence, class, ER, state, mindmap.

Комментарии

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

  2. Нет, я предлагаю решать проблему «я тебе верю» тем что «покажи мне почему я должен тебе верить»

  3. То есть вы предлагаете доверять не нейросети, а своей способности её перепроверить Тоже неплохой фокус

  4. Своим мыслям надо доверять, да, иначе дело совсем плохо

  5. Разбивать на подзадачи и ставить агенты верификаторы ?

  6. Агенты верификаторы могут обходиться также как тесты

  7. Любопытно, что агент, додумывая требования, по сути решает задачу импутации пропущенных данных - только на уровне архитектуры, а не признаков. Это похоже на то, как если бы Mermaid-диаграмму генерировали не из текста, а из среднего по всем проектам пользователя. И удивляться потом, что в схеме появился лишний сервис для логирования

  8. Да они часто даже не так плохо додумывают. Просто один раз плохо перекрывает все хорошо)

  9. ну ок, идея с sequence диаграммой звучит вайбово, но по факту ты просто меняешь доверие агенту на доверие своему скиллу читать схемы. а если я в 3 ночи и глаза слипаются?

  10. Себе надо доверять, иногда.