Всем привет! Скажу честно: я как программист очень устал читать горы текста, которые выдают ИИ-кодинг-агенты. Это прямо больно. В частности, когда ты просишь создать файл plan.md, в котором необходимо описать, что нужно сделать, чтобы написать код с нуля или добавить новую фичу в уже существующий проект, я получаю простыню текста в формате Markdown. Ни прототипов интерфейсов, ни диаграмм, которые визуально объясняют, как всё работает и выглядит. Читать - тоска зелёная. Вот куда интереснее смотреть на прототипы UI-интерфейса и диаграммы со стрелочками, которые показывают, как всё работает. Как говорят, лучше один раз увидеть, чем сто раз услышать - пардон, прочитать.
Почему так происходит, как ни крути LLM заточены для понимания текста и соответственно на выходе они тоже с удовольствием выдают текстовые описания. Но вот в чем проблема - то что выдает ИИ приходится изучать и одобрять или просить вносить правки человеку. А человек склонен к визуализации и простоте подачи информации. Читать тонны текста ну очень утомительно и потом еще в уме выстраивать некую абстрактную картинку как это работает или выглядит тоже тяжко - требует концентрации и затрат психической энергии.
Поэтому возникла идея повернуть LLM к бедному программисту лицом, а к лесу задом. Нужно, чтобы и человеку было понятно, и картинок было побольше, а ИИ просто потом по таким plan.md делал свою работу. В общем, всем очевидно, что Markdown-формат для агентов как родной язык. Кстати, хочу заметить: это самый популярный формат среди людей, потому что его легко читать и писать. Но вот для UI-прототипов есть draw.io, Pencil и Figma, но там JSON-формат, который явно не заточен под то, чтобы человек легко и просто писал его руками с нуля. Читать еще более-менее. Но писать такое себе.
Есть, конечно, PlantUML Salt, но, судя по всему, он был добавлен в проект, заточенный под UML, а сюда попытались добавить прототипирование UI. В общем, не то решение. В итоге я нашел Wireframe (вайрфрейм) - схематичный прототип пользовательского интерфейса. По сути, это черновой набросок того, как будет выглядеть экран приложения или сайта. Пожалуй, самая известная реализация - Balsamiq, но там опять JSON-формат. Но мне повезло, и я нашел open-source-проект WireMark, где формат выглядит вот так вкусно и понятно как для человека, так и для LLM:
Wireframe #login mobile Stack column gap=2 padding=3 Typography h4 "Авторизация" TextField "Email" TextField "Пароль" Button "Войти" contained
Что легко рендерится в скетч интерфейса в SVG и выглядит вот так:
Потом были муки выбора: что взять за основу для UML-подобных диаграмм или блок-схем? С одной стороны, есть PlantUML с текстовым DSL и тяжелой связью с виртуальной Java-машиной. Но, с другой стороны, Mermaid более популярный и повсеместный, да и LLM легко и непринужденно по умолчанию выдают диаграммы и блок-схемы в его формате. К тому же GitHub поддерживает Mermaid непосредственно в Markdown с 2022 года. В общем, зачем бороться со стандартом де-факто?
В итоге я добавил в AGENTS.md (CLAUDE.md) вот такую секцию:
Правила работы с .md-файлами
Используй Wiremark https://docs.wiremark.dev/wiremark-llm.md для UI-прототипов и Mermaid для диаграмм, объясняющих, как работает код.
При создании планов разработки (например,
plan.md) делай упор на UI-прототипы и диаграммы, а не на текстовые описания, чтобы человеку было проще визуально понять, как выглядит и работает проект.Когда создаешь UI-прототипы с помощью блоков Wireframe, не объединяй несколько экранных форм в один блок. Для каждой экранной формы создавай отдельный блок Wireframe.
В итоге ИИ-агенты Codex, Claude Code и Pi стали создавать plan.md не в виде горы текста, а в виде наглядного, понятного и визуально читаемого набора диаграмм, схем и скетчей пользовательского интерфейса. Но осталась проблема: далеко не все вьюверы или IDE поддерживают Wiremark и Mermaid, встроенные в Markdown. То есть увидеть красивые картинки вместо текстового описания на DSL обычно не получается. Поэтому я сделал open-source-проект, который решает эту проблему.
Доступны два режима работы. Запуск в терминале, например:
blueprint4llm plan.md --out=plan.html blueprint4llm plan.md --out=plan.pdf --format=pdf
Берет на вход plan.md и выдает plan.pdf или plan.html, где диаграммы, схемы и скетчи пользовательского интерфейса уже встроены в документ.
Второй режим - локальный сервер предпросмотра:
blueprint4llm plan.md --serve
После запуска в терминале появится адрес, обычно http://127.0.0.1:8080/. Открываешь его в браузере и видишь готовую страницу с диаграммами и прототипами. Когда сохраняешь изменения в plan.md, документ пересобирается, а страница в браузере обновляется сама. PDF актуальной версии можно скачать прямо оттуда.
Этот режим нужен, когда план еще пишется и его приходится часто менять: не надо после каждой правки заново запускать экспорт и вручную открывать результат. Можно держать предпросмотр рядом с редактором и сразу проверять, как выглядят новые блоки Wiremark и Mermaid.
Примеры разных plan.md и как они выглядят в HTML/PDF можно посмотреть здесь: https://github.com/evgenyigumnov/blueprint4llm/tree/main/examples
Исходный код моей тулзы доступен по адресу https://github.com/evgenyigumnov/blueprint4llm. Вы можете легко установить ее или прислать пулл-реквест с новыми фичами или багфиксами.
