Markdown стал стандартным форматом для общения агентов с разработчиком. Простой, портативный, поддерживает базовое форматирование, легко редактируется. Claude даже научился делать ASCII-диаграммы внутри markdown-файлов.
Но по мере того, как агенты становятся мощнее, markdown начинает ощущаться тесным. Файл длиннее ста строк уже трудно читать. Хочется нормальных визуализаций, цвета, диаграмм — и возможности легко поделиться результатом.
К тому же я всё реже редактирую эти файлы руками. Чаще использую их как спецификации, референсы, брейнсторм-артефакты. Когда правки нужны, их вносит Claude — и тогда одно из главных преимуществ markdown исчезает.
Я перешёл на HTML как основной выходной формат. Вот почему.
(примеры можно посмотреть здесь: https://thariqs.github.io/html-effectiveness — возвращайтесь читать дальше)
Почему HTML
Информационная ёмкость
HTML передаёт куда больше информации, чем markdown. Помимо стандартной структуры с заголовками и форматированием, он умеет:
таблицы для табличных данных
CSS для дизайн-данных
SVG для иллюстраций
<script>для кодаJavaScript + CSS для интерактивных элементов
SVG и HTML для схем процессов
абсолютное позиционирование и canvas для пространственных данных
<img>для изображений
Практически любую информацию, которую Claude может прочитать, можно достаточно эффективно выразить в HTML. Без этой возможности модель вынуждена идти на компромиссы — ASCII-диаграммы, оценка цвета через unicode-символы.
Читаемость
Чем сложнее задачи агента, тем длиннее становятся спецификации и планы. На практике я не читаю markdown-файлы длиннее ста строк. Уговорить коллег читать их — ещё сложнее.
HTML-документ гораздо проще воспринимать. Claude может организовать структуру визуально: вкладки, иллюстрации, навигация. Документ может быть адаптивным — один макет для десктопа, другой для телефона.
Если статья понравится — приглашаю в канал AI for Devs. Каждый день публикую похожие материалы: модели, агенты, практические кейсы и новости из мира AI.
Простота шаринга
Markdown трудно расшарить: браузеры не рендерят его нативно, приходится прикладывать файлом к письму или сообщению.
HTML достаточно залить на S3 — и отправить ссылку. Вероятность того, что коллега откроет и прочитает спецификацию в виде HTML-файла, значительно выше.
Двусторонняя интерактивность
HTML позволяет взаимодействовать с документом: слайдеры, переключатели, настройка алгоритма в реальном времени. Можно попросить Claude добавить кнопку «скопировать как промпт» — и изменения сразу готовы к вставке обратно в Claude Code.
Почему Claude Code, а не сlaude.ai или Claude Design?
Главная причина — контекст. Claude Code может проиндексировать всю кодовую базу, прочитать файловую систему, Slack через MCP, историю git, браузер через Claude in Chrome.
Например, для этой статьи я попросил Claude Code пройтись по папке с кодом, найти все сгенерированные HTML-файлы, сгруппировать их по типам и собрать один HTML-файл с диаграммами для каждой категории. Схемы в этой статье — прямой результат той команды.
Радость от процесса
Создавать HTML-документы с Claude просто приятнее, чем работать с markdown. Это само по себе достаточная причина.
Как начать?
Не нужно никакого специального скилла или шаблона. Достаточно написать «сделай HTML-файл» или «сделай HTML-артефакт». Главное — понимать, что должен делать артефакт и как вы будете им пользоваться.
Сценарии использования
Все примеры можно посмотреть здесь: https://thariqs.github.io/html-effectiveness
Спецификации, планирование, исследование
HTML — богатый холст для проработки задачи. Вместо одного markdown-плана я строю сеть HTML-файлов: сначала брейнсторм с несколькими вариантами, потом расширение одного из них с мокапами и кодом, в конце — план реализации.
Пример промпта:
Я не уверен, какое направление взять для экрана онбординга. Сгенерируй 6 принципиально разных подходов — варьируй layout, тон и плотность информации — и оформи их как один HTML-файл в виде сетки для сравнения. Подпиши каждый с указанием компромисса.
Code Review и понимание кода
В HTML можно рендерить диффы с аннотациями, блок-схемы, модули. Я прикладываю HTML-объяснение к каждому PR — часто нагляднее стандартного github-диффа.
Пример промпта:
Помоги мне проревьюить этот PR: создай HTML-артефакт с его описанием. Я плохо знаком со streaming/backpressure-логикой, сосредоточься на ней. Отрендери реальный дифф с inline-аннотациями на полях, цветовым кодированием по серьёзности проблем.
Дизайн и прототипы
Claude Design построен на HTML, потому что HTML предельно выразителен для дизайна — даже если конечный продукт не HTML. Claude набрасывает дизайн в HTML, потом переписывает в React, Swift или что нужно.
Пример промпта:
Я хочу прототипировать новую кнопку checkout: при клике — анимация, потом быстро меняет цвет на фиолетовый. Создай HTML-файл с несколькими слайдерами и опциями для подбора параметров анимации. Добавь кнопку копирования для параметров, которые подойдут.
Отчёты, исследование, обучение
Claude Code умеет синтезировать информацию из разных источников — Slack, кодовая база, история git, интернет — и упаковывать в читаемый отчёт: длинный HTML-документ, интерактивный экспейнер или даже слайдшоу.
Пример промпта:
Я не понимаю, как на самом деле работает наш rate limiter. Прочитай код и сделай один HTML-экспейнер: диаграмма token bucket flow, 3–4 ключевых аннотированных фрагмента кода и раздел «подводные камни» внизу.
Кастомные интерфейсы редактирования
Иногда словами сложно описать, что нужно. В таких случаях я прошу Claude собрать одноразовый редактор под конкретную задачу. Не продукт, не переиспользуемый инструмент — один HTML-файл, сделанный ровно под эти данные.
Финал всегда один: кнопка экспорта — «скопировать как JSON» или «скопировать как промпт».
Пример промпта:
Мне нужно пересортировать 30 Linear-тикетов. Сделай HTML-файл с каждым тикетом как перетаскиваемой карточкой по колонкам Now / Next / Later / Cut. Предварительно отсортируй по своему усмотрению. Добавь кнопку «скопировать как markdown» с итоговым порядком и однострочным обоснованием по каждому разделу.
Частые вопросы
Это же менее токен-эффективно? Да, HTML тратит больше токенов. Но повышенная выразительность и то, что я реально читаю документ, дают лучший итоговый результат. С контекстным окном в 1M токенов у Opus 4.7 расход уже не ощущается.
Когда вы всё-таки используете markdown? Честно — почти нигде. Но я, наверное, крайний HTML-максималист.
Как открыть HTML-файл? Открываю в браузере локально (можно попросить Claude открыть). Если нужна ссылка — заливаю на S3.
Это же дольше генерируется? Да, в 2–4 раза медленнее markdown. Результат стоит ожидания.
А версионирование? Главный минус HTML. Диффы шумные и плохо читаются по сравнению с markdown.
Как добиться, чтобы не было некрасиво? Плагин frontend design помогает Claude делать качественные HTML-файлы. Для корпоративного стиля — попросите Claude создать один design system HTML-файл на основе вашей кодовой базы и использовать его как референс.
Главная причина, по которой я перешёл на HTML — я снова чувствую себя в курсе происходящего. Когда перестаёшь читать планы, начинаешь просто доверять агенту. С HTML я снова читаю, вижу, участвую. Именно это мне было нужно.
Русскоязычное сообщество про AI в разработке
Друзья! Перевод этой статьи подготовила команда ТГК «AI for Devs» — канала, где мы рассказываем про AI-агентов, плагины для IDE, делимся практическими кейсами и свежими новостями из мира ИИ. Подписывайтесь, чтобы быть в курсе и ничего не упустить!
