Claude Code и неожиданная эффективность HTML

Черновик перевода статьи Thariq из X. Источник: x.com/trq212/status/2052809885763747935. Оригинальное название: “Using Claude Code: The Unreasonable Effectiveness of HTML”.

Markdown стал доминирующим форматом файлов, через который агенты общаются с нами. Он простой, переносимый, поддерживает немного rich text и его легко редактировать. Claude даже неожиданно хорошо научился использовать ASCII, чтобы рисовать диаграммы прямо внутри markdown-файлов.

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

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

Я начал предпочитать HTML как формат вывода вместо Markdown и всё чаще вижу, что другие люди в команде Claude Code тоже используют этот подход. Вот почему.

Если хотите начать с примеров, их можно посмотреть здесь: thariqs.github.io/html-effectiveness. Только потом вернитесь и дочитайте, почему это работает.

Почему HTML?

Плотность информации

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

• табличные данные через таблицы;
• дизайн-данные через CSS;
• иллюстрации через SVG;
• фрагменты кода через script-теги;
• интерактивность через HTML-элементы, JavaScript и CSS;
• workflow через SVG и HTML;
• пространственные данные через абсолютное позиционирование и canvas;
• изображения через img-теги.

Я бы даже сказал, что почти любой набор информации, который Claude способен прочитать, можно довольно эффективно представить в HTML. Это делает HTML очень эффективным способом для модели передавать вам глубокую информацию — и для вас её просматривать.

Когда у модели нет возможности делать это, она вынуждена использовать менее эффективные трюки в markdown: ASCII-диаграммы или, мой любимый пример, попытки изображать цвета unicode-символами, как на этом скриншоте из Claude Code.

Визуальная ясность и удобство чтения

По мере того как Claude способен выполнять более сложную работу, он пишет всё более крупные спецификации и планы. На практике я понял, что обычно не читаю markdown-файлы длиннее 100 строк. И уж точно не могу заставить кого-то ещё в организации читать их.

HTML-документы читать гораздо проще. Claude может визуально организовать структуру так, чтобы по ней было удобно перемещаться: вкладки, иллюстрации, ссылки и другие элементы. Документ может даже быть адаптивным, чтобы его можно было читать по-разному в зависимости от устройства.

Простота распространения

Markdown-файлами довольно неудобно делиться: большинство браузеров не рендерят их нативно хорошо. Часто приходится прикладывать их к письмам или сообщениям.

С HTML всё иначе: если вы загрузили файл, например на S3, вы можете просто отправить ссылку. Коллеги откроют его где угодно и смогут легко на него ссылаться.

Вероятность, что кто-то действительно прочитает вашу спецификацию, отчёт или описание PR, гораздо выше, если это HTML.

Двустороннее взаимодействие

HTML позволяет взаимодействовать с документом. Например, можно попросить добавить слайдеры или ручки, чтобы настраивать дизайн или менять параметры алгоритма и смотреть, что получится. Также можно попросить документ дать кнопку, которая копирует сделанные изменения в prompt для Claude Code.

Подробнее о таких двусторонних взаимодействиях можно посмотреть в посте про playgrounds: x.com/trq212/status/2017024445244924382.

Поглощение данных

Почему использовать Claude Code для создания HTML-файлов, а не, например, Claude.ai или Claude Design? Одна из главных причин — объём контекста, который Claude Code может поглотить.

Например, при написании этой статьи я попросил Claude Code пройтись по моей папке с кодом, найти все HTML-файлы, которые я генерировал, сгруппировать и категоризировать их, а затем сделать HTML-файл с диаграммами для каждого типа. Диаграммы в этой статье — прямой результат этого процесса.

Помимо файловой системы, Claude Code может находить дополнительный контекст через ваши MCP — например Slack, Linear и другие, — через браузер, git history и так далее.

Это радостно

Делать HTML-документы с Claude просто веселее. Я чувствую себя более вовлечённым в создание результата, а одного этого уже достаточно.

Как начать

Я немного боюсь, что люди прочитают эту статью и превратят всё в какой-нибудь /html-skill. Возможно, в этом есть ценность, но я хочу подчеркнуть: вам не нужно делать почти ничего особенного, чтобы Claude начал так работать. Можно просто попросить: «сделай HTML-файл» или «сделай HTML-артефакт».

Фокус в том, чтобы понимать, что должен делать артефакт и как вы будете его использовать. Со временем вы можете сделать skill, но на старте я бы советовал просто писать prompt с нуля, чтобы почувствовать разные сценарии применения.

Сценарии использования

Чтобы сделать это конкретнее, я создал много разных HTML-файлов под разные задачи. Все примеры можно посмотреть здесь: thariqs.github.io/html-effectiveness. Ниже — обзор.

Спецификации, планирование и исследование вариантов

HTML — это богатый холст, на котором Claude может разбираться в проблеме. Когда я начинаю работать над задачей, вместо простого markdown-плана я ожидаю получить сеть HTML-файлов. Например, сначала я могу попросить Claude Code провести брейншторм и создать несколько вариантов. Потом — углубить один из них, сделать макеты или фрагменты кода. И наконец, когда направление кажется хорошим, попросить написать план реализации. Когда план меня устраивает, я создаю новую сессию и передаю ей все эти файлы для реализации.

При проверке я также прошу verification-agent прочитать эти файлы — так у него гораздо шире контекст того, что нужно сделать.

Примеры prompt’ов:

• «Я не уверен, в каком направлении делать onboarding screen. Сгенерируй 6 заметно разных подходов — меняй layout, тон и плотность — и разложи их в одном HTML-файле сеткой, чтобы я мог сравнить их рядом. Подпиши, какой tradeoff делает каждый вариант».
• «Создай подробный план реализации в HTML-файле: добавь mockup’ы, покажи data flow и важные фрагменты кода, которые мне стоит посмотреть. Сделай так, чтобы это было легко читать и переваривать».

Для чего использовать:

• поиск разных способов реализовать что-то в коде;
• исследование нескольких визуальных дизайнов.

Code review и понимание кода

Код бывает трудно читать в markdown-файле. Зато в HTML можно рендерить diff’ы, аннотации, flowchart’ы, модули и многое другое. Используйте это, чтобы понять код, который написал агент, провести code review или объяснить PR человеку, который будет его смотреть. Для меня это часто работает лучше стандартного GitHub diff view, и теперь я прикладываю HTML code explainer к каждому своему PR.

Пример prompt’а:

Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.

Для чего использовать:

• создание PR;
• review PR;
• понимание темы в коде.

Дизайн и прототипы

Claude Design основан на HTML, потому что HTML невероятно выразителен для дизайна — даже если конечная поверхность не HTML. Claude может набросать дизайн в HTML, а затем переписать его на нужный язык: React, Swift или что-то ещё.

Также можно прототипировать взаимодействия: анимации, действия и другие варианты поведения. Например, попросить Claude сделать слайдеры и ручки, чтобы точно настроить нужный эффект.

Пример prompt’а:

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

Для чего использовать:

• создание артефактов дизайн-системы;
• настройка компонентов;
• визуализация библиотек компонентов;
• прототипирование приятных анимаций.

Отчёты, исследования и обучение

Claude Code очень хорошо синтезирует информацию из множества источников и превращает её в читабельный отчёт. Можно попросить Claude поискать по Slack, codebase, git history, интернету и так далее — и сгенерировать очень понятный отчёт для себя, руководства или команды.

Это может быть длинный HTML-документ, интерактивный explainer или даже slideshow/deck. Попросите Claude использовать SVG для диаграмм.

Например, для моих постов про prompt caching я попросил Claude подготовить глубокий исследовательский HTML-файл после чтения всей git history по изменениям в prompt caching.

Пример prompt’а:

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

Для чего использовать:

• резюмировать, как работает фича;
• объяснять концепт самому себе;
• еженедельные статус-отчёты руководителю;
• incident reports для leadership;
• SVG-иллюстрации, flowchart’ы, технические диаграммы.

Кастомные интерфейсы редактирования

Иногда трудно описать, чего вы хотите, просто в текстовом поле. В таком случае я прошу Claude собрать одноразовый редактор ровно для той вещи, над которой я работаю. Не продукт и не reusable-инструмент, а один HTML-файл, заточенный под конкретный набор данных.

Фокус почти всегда в том, чтобы закончить экспортом: кнопкой «copy as JSON» или «copy as prompt», которая превращает сделанные вами изменения обратно во что-то, что можно вставить в Claude Code.

Примеры prompt’ов:

• «Мне нужно переприоритизировать эти 30 Linear tickets. Сделай HTML-файл, где каждый ticket — draggable card в колонках Now / Next / Later / Cut. Предварительно отсортируй их по своей лучшей оценке. Добавь кнопку copy as markdown, которая экспортирует финальный порядок с однострочным rationale по каждому bucket».
• «Вот наш feature flag config. Построй form-based editor: сгруппируй флаги по областям, покажи зависимости между ними, предупреждай, если я включаю флаг, prerequisite которого выключен. Добавь кнопку copy diff, которая отдаёт только изменённые ключи».
• «Я настраиваю system prompt. Сделай side-by-side editor: редактируемый prompt слева с подсвеченными переменными, три sample input справа, которые live-рендерят заполненный template. Добавь character/token counter и copy button».

Для чего использовать:

• переупорядочивание, triage или bucket’инг чего угодно: tickets, test cases, feedback;
• редактирование структурированных config’ов: feature flags, env vars, JSON/YAML с ограничениями;
• настройка prompt’ов, шаблонов или copy с live preview;
• курирование datasets: approve/reject rows, tags, export selection;
• аннотирование документа, transcript или diff и экспорт аннотаций;
• выбор значений, которые больно описывать текстом: цвета, easing curves, crop regions, cron schedules, regex’ы.

Частые вопросы

Я много рассказывал людям о переходе на HTML и увидел несколько повторяющихся вопросов.

Разве это не менее эффективно по токенам?

Markdown часто использует меньше токенов, но я обнаружил, что дополнительная выразительность HTML и гораздо более высокая вероятность, что я реально прочитаю результат, дают лучший общий output. С контекстным окном 1MM в Opus 4.7 увеличенный расход токенов почти не ощущается.

Когда ты теперь используешь markdown?

Честно говоря, я почти полностью перестал использовать markdown почти для всего. Хотя, вероятно, я уже на стороне HTML-максималистов.

Как смотреть HTML-файл?

Обычно я просто открываю его локально в браузере — можно попросить Claude открыть его. Или загружаю на S3, если нужна ссылка для шаринга.

Разве генерация HTML не занимает больше времени?

Занимает. HTML может генерироваться в 2–4 раза дольше, чем Markdown. Но по моему опыту результат того стоит.

А что с version control?

Это действительно один из главных минусов HTML: diff’ы HTML шумные и их трудно review’ить по сравнению с Markdown.

Как заставить Claude попадать в мой вкус и не делать уродливо?

Frontend design plugin помогает Claude делать хорошие HTML-файлы. Но чтобы попасть в стиль вашей компании, можно создать один HTML-файл дизайн-системы, указав Claude на codebase. Потом этот файл можно использовать как reference для других HTML-файлов.

Оставаться в контуре

Всё вышесказанное сводится к тому, что главная причина, по которой я использую HTML: я чувствую себя гораздо сильнее «в контуре» работы с Claude. Я начал бояться, что из-за того, что перестал глубоко читать планы, мне придётся просто оставить Claude принимать решения самому.

Но вместо этого я рад сказать, что с HTML я чувствую себя более вовлечённым, чем когда-либо. Надеюсь, у вас будет так же.