Markdown долго был языком, на котором агенты общались с человеком. Простой, портативный, легко править руками. Но чем больше работы агенты берут на себя, тем сильнее формат буксует: файл длиннее ста строк уже не дочитывают, визуализации просить нельзя, делиться неудобно. HTML снимает эти ограничения — и добавляет интерактивность, которой в Markdown просто нет.
Что это
HTML как формат вывода — это когда кодинг-агент (Claude Code, Codex CLI, Cursor, OpenCode) вместо длинного report.md кладёт в файл report.html: с CSS-стилями, SVG-диаграммами, тегами
Идея простая. Markdown хорош, пока документ короткий и его правят руками. Как только задача становится «сгенерируй спецификацию на 200 строк, чтобы её прочитал тимлид и не уснул» — Markdown заканчивается. Агент умеет в HTML, браузер умеет в HTML, ссылку можно кинуть в чат. Формат перестаёт быть бутылочным горлышком.
HTML — это не замена Markdown, а расширение. Для коротких заметок и PR-описаний Markdown по-прежнему удобнее. Для всего, что длиннее 100 строк и должно быть прочитано, — HTML.
Зачем нужно
- Плотность информации — HTML передаёт то, что Markdown теряет: цвета, отступы, SVG-диаграммы, интерактивные блоки, реальные диффы с подсветкой. Без HTML агент вынужден имитировать цвета юникод-символами или рисовать ASCII-диаграммы.
- Читаемость — Markdown-файл на 100+ строк мало кто дочитывает, тем более в команде. HTML-документ с вкладками, иллюстрациями и адаптивной вёрсткой читают охотнее.
- Простота расшаривания — Markdown не рендерится браузером нативно, его прикладывают вложением. HTML загружается на любой хостинг (S3, Cloudflare Pages, GitHub Pages) и отдаётся ссылкой.
- Интерактивность — слайдеры, переключатели, drag-and-drop, live-превью. Кнопка «скопировать как JSON» возвращает результат обратно в промпт.
- Контекст проекта — кодинг-агент (а не обычный чат) может прочитать файловую систему, найти ранее сгенерированные HTML, сгруппировать их и собрать новый документ с диаграммами по каждому типу. Плюс MCP-серверы, Git-история, Slack — те же источники, что и обычно.
- Радость использования — готовить HTML-документы с агентом это процесс, в который вовлекаешься, а не скучная сдача текста.
Как устроено
С технической стороны всё проще, чем кажется. Агент генерирует один HTML-файл с инлайн-CSS и (опционально)
| Тип данных | Как реализуется в HTML |
|---|---|
| Табличные данные | Таблицы с CSS-стилизацией |
| Дизайн и оформление | CSS-стили, цвета, отступы, типографика |
| Иллюстрации | SVG-графика прямо в документе |
| Фрагменты кода | Тег |
| Интерактивность | HTML-элементы + JavaScript + CSS |
| Архитектура и потоки данных | SVG-диаграммы и HTML-блоки |
| Пространственные данные | Абсолютное позиционирование и |
| Изображения | Теги |
Anthropic поддерживает это в Claude Code нативно: есть режим Artifacts, который превращает результат сессии в живую интерактивную страницу, и официальный скилл web-artifacts-builder (React + Tailwind + shadcn/ui). Codex CLI так же умеет сохранять результат в HTML — через тот же скилл-механизм или просто промпт «сохрани в HTML».
Главное, что нужно понимать: HTML-документ — это обычный файл, который открывается локально в браузере, загружается на статический хостинг или встраивается в Notion/Confluence. Никакой backend не нужен, если интерактивность работает на клиентском JS.
Когда использовать
| Ситуация | Подходит | Почему |
|---|---|---|
| Документ длиннее 100 строк | Да | Markdown перестают читать уже на этом пороге |
| Нужны диаграммы, схемы, визуализации | Да | SVG прямо в HTML, цвета и слои |
| Документ будет читать кто-то кроме автора | Да | HTML проще шарить и он приятнее глазу |
| Нужна интерактивность (слайдеры, переключатели, drag-and-drop) | Да | Markdown этого не умеет в принципе |
| Результат нужно отправить по ссылке | Да | Открыл в браузере → кинул URL |
| Файл будут править руками | Нет | HTML править руками неприятно, лучше остаться на Markdown |
| Документ уйдёт в git как часть кодовой базы | Нет | Шумные диффы, сорс-контроль страдает |
| Короткая заметка или PR-описание | Нет | Markdown быстрее и проще |
| Нужна версионируемость через git-диффы | Нет | HTML-диффы трудночитаемые по сравнению с Markdown |
| Документ строго текстовый (без визуала) | Нет | Выигрыша нет, оверхед по токенам не оправдан |
Пример
Самый простой кейс — попросить агента сделать одноразовый редактор для конфига, у которого в конце всегда есть кнопка экспорта. Так результат не «застревает» в HTML, а возвращается обратно в рабочий контур.
Промпт-шаблон (одноразовый редактор):
Вот наш конфиг фича-флагов: <вставьте JSON или путь к файлу>.
Собери для него HTML-редактор:
- сгруппируй флаги по областям (безопасность, эксперименты, инфра),
- покажи зависимости между флагами,
- предупреди меня, если я включу флаг, у которого выключен пререквизит,
- в конце добавь кнопку "скопировать дифф", которая выдаст только изменённые ключи.
Открой файл локально, чтобы я мог пощёлкать.Промпт-шаблон (дизайн-прототип):
Хочу прототипировать кнопку "оформить заказ": при клике она играет анимацию
и быстро становится фирменного цвета. Сделай HTML-файл с несколькими
слайдерами (длительность анимации, easing, итоговый цвет) и кнопкой
"скопировать параметры", чтобы я мог вставить их обратно в код.Промпт-шаблон (код-ревью):
Помоги провести ревью этого PR — создай HTML-артефакт с его описанием.
Я плохо знаю логику стриминга и backpressure, сфокусируйся на этом.
Отрендери реальный дифф с инлайн-аннотациями на полях, выдели находки
цветом по степени серьёзности и добавь всё, что поможет передать концепцию.Промпт-шаблон (объяснение фичи для команды):
Я не понимаю, как работает наш rate limiter. Прочитай код и собери одну
HTML-страницу-объяснение: диаграмма потока token-bucket, 3–4 ключевых
фрагмента с аннотациями и раздел "подводные камни" внизу.
Оптимизируй для однократного прочтения.Все четыре примера — рабочие сценарии из практики кодинг-агентов. Разница только в том, что в конце каждого либо кнопка экспорта, либо явный «верни результат в виде кода/промпта», иначе документ повиснет мёртвым грузом.
Ограничения
Ограничения
Что учитывать:
Расход токенов выше — HTML расходует больше токенов, чем Markdown, иногда в 2–4 раза.
При контекстном окне 1M+ это редко критично, но на коротких моделях и жёстких лимитах считайте.
Генерация дольше — HTML-документ агент собирает дольше, чем Markdown-аналог.
На сложной странице с диаграммами и интерактивом это минуты, не секунды.
Версионирование страдает — HTML-диффы шумные, в git-репозитории они превращаются в кашу из тегов и экранированных символов.
Для файлов, которые коммитят в репо, держитесь Markdown.
Редактировать руками неприятно — открыть report.html в VS Code и поправить абзац — боль.
Если документ будут дорабатывать люди, а не агент, HTML проигрывает.
Безопасность при шаринге — если в HTML остался с приватными данными (токены, внутренние URL), ссылка в общий чат = утечка.
Следите за инлайн-скриптами и не зашивайте секреты в тело документа.
Хостинг ≠ бесплатность — S3, Cloudflare Pages, GitHub Pages бесплатны до предела, но не все.
Длинный документ с тяжёлым SVG может стоить денег на просмотры, если шарят широко.
Зависимость от браузера — HTML не откроется в терминале, его не прочитает grep, его не возьмёт простой пайплайн.
Если аудитория — только CLI, это минус.
Антипаттерны
Антипаттерны
Чего не делать:
Не пишите HTML-результат в репозиторий без причины — коммитить design-v3.html рядом с src/ плохая идея:
ломает диффы, раздувает репо, создаёт зоопарк артефактов. Артефакты — это выдача, не код.
Не зашивайте секреты в инлайн- — токены, ключи, внутренние URL, персональные данные.
Один шаринг по ссылке — и они утекли. Используйте placeholder и подставляйте значения в рантайме.
Не просите агента «сделать красиво» без референса — без явного примера дизайна агент выдаёт типовое «AI-красиво»:
синие градиенты, скруглённые углы, одинаковые отступы. Сначала покажите эталон, потом просите новый документ.
Не делайте одностраничник на 5 МБ — если агент впихнул 200 SVG-иконок, base64-картинки и три бандла JS в один файл, результат нечитаем.
Дробите или просите облегчённую версию.
Не рассчитывайте на ручную правку HTML — если знаете, что документ будут править люди, остановитесь на Markdown.
Правка HTML руками — это путь к расхождению версий и сломанной вёрстке.
Не забывайте кнопку экспорта — HTML без способа вернуть результат в рабочий контур (копировать как JSON / как промпт / как дифф) висит мёртвым грузом.
Каждый артефакт должен заканчиваться экспортом.
Не шарьте HTML как «документ» в git-репо — это артефакт, а не код.
Если нужно хранить версии, держите их в отдельной папке artifacts/ или во внешнем хранилище, не в основной ветке.
Не путайте артефакт и продакшен — HTML от агента — прототип, референс, объяснитель.
Это не компонент, который пойдёт в релиз. Переписывать его на React/Swift/HTML руками — нормально, а вот копипастить — нет.
Чеклист
Чеклист
Проверка перед запуском:
Длина оправдывает формат — документ действительно длиннее 100 строк или требует визуализации.
Если нет — оставайтесь на Markdown.
Аудитория понимает HTML — все, кому вы шарните ссылку, смогут открыть её в браузере.
Браузер есть у всех, но не все кликнут по HTML-файлу без предупреждения.
Нет секретов в теле документа
инлайн-скрипты, SVG-комментарии, мета-теги проверены на отсутствие токенов, ключей, внутренних URL, персональных данных.
Есть способ экспортировать результат
кнопка «копировать как JSON» / «как промпт» / «как дифф» присутствует, если документ — рабочий артефакт, а не просто отчёт.
Хостинг или локальный просмотр определён — вы знаете, где файл будет жить:
локально, на S3, на Cloudflare Pages, на GitHub Pages. Файл не должен теряться.
Версионирование учтено
если документ будут править, способ хранения версий выбран (внешнее хранилище, не git-репо).
Дизайн-референс есть
для дизайн-прототипов вы показали агенту эталон (один HTML-файл дизайн-системы), а не просили «на твой вкус».
Проверка на мобильном пройдена — адаптивность важна, особенно если шарят в чатах и читают с телефона.
Откройте на узком экране перед отправкой.
Альтернативы рассмотрены — для коротких заметок, PR-описаний и коммитов оставайтесь на Markdown.
HTML — не серебряная пуля, а формат под конкретные задачи.
Ссылки
Ссылки
- Документация: Claude Code — Artifacts
- Репозиторий: anthropics/skills — web-artifacts-builder
- Сайт: Галерея HTML-артефактов
- Документация: Что такое Artifacts в Claude