Markdown vs HTML для AI-агентов | Даниил Охлопков

Адаптация статьи Tariq из команды Claude Code · перевод и комментарии Дана Охлопкова

Оригинал: https://x.com/trq212/status/2052809885763747935

Примеры автора: https://thariqs.github.io/html-effectiveness

TL;DR — Markdown был хорош, пока ты сам редактировал файлы. Сейчас файлы пишет агент, ты их читаешь, ревьюишь и шаришь. В этой реальности HTML побеждает по плотности информации, читаемости, шерингу и интерактиву. Цена — токены, время и шумные diff'ы.

Если коротко: Markdown всё ещё норм для коротких заметок, raw-транскриптов и файлов, которые человек будет править руками. Для длинных AI-agent артефактов HTML выигрывает: он даёт визуальную плотность, нормальный шеринг ссылкой/PDF, интерактив и copy-back в Claude Code.

Что поменялось

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

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

Главный сдвиг тут — я перестал редактировать эти файлы руками. Они стали спецификациями, ресёрчами, brainstorming-выходом, отчётами. Когда мне надо что-то поправить, я не лезу в текст — я промпчу Claude. То есть основное преимущество markdown'а (легко редактировать руками) больше не работает в моём флоу.

Я всё ещё храню свой Second Brain в Obsidian в markdown: сырые голосовые, overview.md, tasks.md, проектные заметки, AGENTS.md. Мой текущий паттерн такой: markdown живёт как source of truth, HTML уходит наружу как readable artifact.

Главный поинт: Markdown оптимизирован под того, кто пишет файл. HTML оптимизирован под того, кто читает и шарит. Когда писатель — агент, а ты только читатель — выбор очевиден.

Короткий ответ: когда HTML, когда Markdown

HTML-артефакт — это одноразовый файл или страница, которую агент собирает под конкретное решение: план, ревью, отчёт, прототип, сортировку задач. Человек читает, кликает, принимает решения и экспортит результат обратно в prompt, JSON или markdown.

Почему HTML — 6 причин

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

HTML может представить почти всё, что Claude способен понять:

• Структура документа — заголовки, форматирование (как markdown, только богаче)
• Таблицы — нормальные, с merged cells и стилями вместо убогого markdown table
• Дизайн — через CSS
• Иллюстрации и диаграммы — через SVG
• Интерактив — через HTML + JS + CSS
• Воркфлоу и стрелочки — SVG поверх HTML
• Картинки и видео — нативно
• Пространственные данные — absolute positioning, canvas

Когда модель лишена этого арсенала, она занимается *странным* — рисует ASCII-арт или пытается передать цвет юникод-символами разной плотности (▒▓█). Это уже карго-культ markdown'а; сила формата тут теряется.

2. Читаемость длинных документов

Claude Code пишет всё более длинные планы и спецификации. На практике markdown-файл больше 100 строк я не дочитываю до конца, и команду тоже не заставлю. HTML же можно нормально структурировать визуально — табы, навигация, sticky оглавление, mobile-responsive вёрстка под телефон vs десктоп.

Личный пример. Я делаю research-отчёты по on-chain-аналитике TON — на 200-500 строк, со встроенными SQL-запросами, цифрами, ссылками на Dune-дашборды. В markdown'е их читают по диагонали. С тем же контентом в HTML с SVG-диаграммами потоков и кликабельными ссылками open rate был бы радикально выше: визуальная структура помогает физически дочитать до выводов.

3. Лёгкость шеринга — главный аргумент

Это, по моим ощущениям, самая *недооценённая* часть. Markdown в реальной рабочей жизни шарить почти невозможно:

• Slack не рендерит markdown-аттачи. А HTML-файлы Slack вообще не разрешает прикреплять. Тупик
• Кидаешь .md программисту — он откроет в Cursor / IDE / Obsidian, увидит рендер. Кидаешь непрограммисту — он смотрит на сырую простыню текста с решётками и звёздочками
• Браузеры markdown нативно не рендерят. Открывается как plaintext
• В мобильных мессенджерах вложенный .md — это «открой и почитай», что никто не делает

Поэтому де-факто всегда приходилось делать HTML → PDF через print to PDF или какой-нибудь рендерер. PDF открывается везде — в TG, в Slack, на телефоне, в WhatsApp, в почте.

«Можно же просто конвертить markdown в PDF» — можно. Но получается стоковая, скучная А4-простыня без диаграмм, без структуры, без визуальных акцентов. HTML → PDF выигрывает у Markdown → PDF в каждом раунде.

Итог: HTML — это лучший *исходник* для шеринга. Дальше либо ссылка (если хостинг есть), либо PDF (если нет).

4. Двусторонний интерактив

HTML может *показывать* и *принимать ввод*. Слайдеры для подбора параметров анимации. Drag-and-drop для перетаскивания тикетов между колонками. Live-preview шаблона при редактировании промпта.

Финальный ход — кнопка Copy as JSON или Copy as Prompt, которая собирает результат твоих манипуляций обратно в текст, который ты вставляешь в Claude Code. Получается одноразовый редактор под конкретную задачу: артефакт на 30 минут, который можно выкинуть после решения.

5. Контекст — суперсила Claude Code

Почему именно Claude Code? Потому что у него есть всё:

• Файловая система — может прочитать твой codebase, ai-docs, заметки
• MCP-серверы — Slack, Linear, Coolify, Dune, Telegram
• Git history — кто что менял и когда
• Браузер (через Claude in Chrome) — может полезть и посмотреть

Tariq, например, попросил Claude Code пройтись по его папке с кодом, найти все HTML-файлы, которые он генерил раньше, сгруппировать по типу и сделать обзорный HTML с диаграммами. Это и стало основой иллюстраций к его статье. Официальный обзор Claude Code тоже упирается в этот же паттерн: агент читает кодовую базу, редактирует файлы, запускает команды и подключает внешние инструменты через dev workflow.

6. Это просто кайфово

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

Сравнение в одной таблице

Где Markdown всё ещё лучше

Markdown я бы не хоронил совсем. Он всё ещё лучший формат для source packs, README, raw voice notes, ai-docs, списков задач и файлов, которые часто меняются в git. Если документ должен жить месяцами, нормально diff'аться и редактироваться руками — HTML превращается в боль.

Мой рубеж простой: короткое и машинно-читаемое — markdown; длинное и человеко-читаемое — HTML. Поэтому в моём Obsidian + Claude Code флоу markdown остаётся операционной памятью, а HTML становится интерфейсом для чтения.

Юзкейсы с промптами

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

Когда я начинаю новую задачу, вместо одного markdown-плана я представляю паутину HTML-файлов. Сначала прошу побрейнштормить и сделать explorations нескольких подходов. Потом раскручиваю один из них в макет с примерами кода. Финально — план имплементации.

Промпт-пример: «Не уверен, в какую сторону пилить экран онбординга. Сгенери 6 принципиально разных подходов — варьируй layout, тон, плотность — и выложи их в один HTML-файл сеткой, чтобы я мог сравнивать side-by-side. Подпиши каждый вариант его tradeoff'ом.»

Промпт-пример: «Сделай подробный имплементационный план в HTML. Добавь mockup'ы, нарисуй data flow в SVG, вставь ключевые куски кода которые я захочу проревьюить. Сделай удобным для сканирования.»

Code review и понимание чужого кода

Код в markdown'е читать тяжело. В HTML мы можем рендерить diff'ы с inline-аннотациями, flowchart'ы модулей, color-coded findings по severity.

Промпт-пример: «Помоги мне ревьюить этот PR — сделай HTML-артефакт. Я плохо знаю логику streaming/backpressure, сфокусируйся на ней. Отрендери реальный diff с аннотациями на полях, color-code находки по severity.»

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

HTML невероятно выразителен для дизайна — даже если финальный таргет не веб. Claude может набросать дизайн в HTML, а потом перевести его в React/Swift/whatever. И главное — можно прототипировать *интеракции* вместе со статикой. Про связку design engineering, Figma-to-code и агентов я отдельно писал в разборе AI-инструментов для дизайнеров.

Промпт-пример: «Хочу прототипировать новую кнопку checkout. При клике она проигрывает анимацию и быстро становится фиолетовой. Сделай HTML с несколькими слайдерами (длительность, easing, цвет) чтобы я перепробовал варианты. Кнопка copy чтобы скопировать параметры которые сработали.»

Отчёты, ресёрчи, объяснялки

Claude Code отлично синтезирует инфу из нескольких источников — Slack, codebase, git history, веб — в единый читаемый отчёт.

Промпт-пример (мой кейс, on-chain ресёрч): «Прочитай папку с моим research'ем про buy/sell pressure на одном из TON-маркетплейсов и собери одностраничный HTML-explainer для босса: SVG-схема потока ордеров, 3-4 ключевых SQL-снипета с аннотациями, секция "key findings" вверху, ссылки на Dune-дашборды кликабельные. Оптимизируй под человека, который читает это один раз.»

Кастомные одноразовые редакторы

Самый мощный, на мой взгляд, юзкейс. Когда задачу тяжело описать словами в текстбоксе — Claude собирает throwaway-редактор под неё. Один HTML-файл, который ты выкинешь после использования. Это хорошо ложится на мой текущий цикл с GStack, goal и office hours: агент делает механику, человек остаётся в loop'е через понятный артефакт.

Финальный аккорд всегда один: кнопка export — Copy as JSON, Copy as Markdown, Copy as Prompt — которая превращает результат твоих кликов обратно в текст для Claude.

Промпт-пример: «Мне надо переприоритизировать 30 тикетов из Linear. Сделай HTML где каждый тикет — draggable-карточка по колонкам Now / Next / Later / Cut. Предсортируй по своему лучшему пониманию. Кнопка "copy as markdown" чтобы выгрузить финальный порядок.»

Что ещё попадает в этот паттерн:

• Триаж/сортировка чего угодно (тикеты, тест-кейсы, фидбек)
• Редактирование структурированного конфига (feature flags, env)
• Тюнинг промптов с live-preview
• Кураторство датасетов — approve/reject строки, тегирование
• Аннотация документа/транскрипта/diff'а с экспортом аннотаций
• Подбор значений, которые мучительно описывать словами: цвета, easing-кривые, crop-области, cron-расписания, regex'ы

Честные минусы

За что любим:

• Плотность инфы
• Читаемость длинных документов
• Шеринг ссылкой
• Интерактив + copy-back в промпт
• Контекст из MCP/файлов/git
• Чувство вовлечённости в результат

За что ругаем:

• Токены ×2–4 (но в 1M-контексте Opus 4.7 — норм)
• Время генерации ×2–4
• Git diff'ы шумные, ревьюить тяжело
• Без design system Claude генерит generic-хрень
• Нужен браузер чтобы посмотреть

Если делаешь HTML регулярно — заведи один файл с design system своего проекта/компании. Можно попросить Claude сгенерить его, посмотрев на твой codebase. Дальше каждый новый HTML генеришь со ссылкой на этот design system — и стиль становится консистентным.

Как начать прямо сейчас

Главное — не создавай /html skill. Не надо. Достаточно просто сказать *«сделай HTML-файл»* или *«сделай HTML-артефакт»*. Со временем, может быть, оформишь в скилл — но для начала промпчи from scratch.

Хитрость начинается с понимания, чего ты хочешь от артефакта и как ты будешь его использовать.

FAQ

HTML лучше Markdown для AI-агентов?

Для длинных артефактов — да. Когда агент пишет, а человек читает, HTML даёт больше структуры, визуальной плотности, интерактива и вариантов шеринга. Для коротких заметок и source packs markdown всё ещё проще.

Когда всё-таки использовать Markdown?

Короткая заметка, TODO, промпт, meeting note, raw-транскрипт, source pack для агента, README, файл с частыми git diff'ами. Если документ читаешь только ты и он меньше 100 строк — markdown норм.

HTML-артефакты не слишком дорогие по токенам?

HTML жрёт больше токенов и обычно дольше генерится. Но если итоговый документ реально читают, trade нормальный. Дешёвый markdown-план, который никто не дочитал, тоже стоит денег — просто это не видно в счёте.

Как ревьюить diff'ы HTML?

Это реально больно. Один из главных минусов. Если файл часто меняется — может быть оставь его в markdown.

Что попросить Claude Code, чтобы HTML не выглядел как generic AI slop?

Дай агенту контекст: кто читатель, где документ будет открываться, какие секции обязательны, какие стили проекта использовать, что запрещено. Для рабочих артефактов почти всегда помогает прямой запрет на landing page и декоративный SaaS-дизайн.

Stay in the loop

Финальная мысль автора, которая мне зашла больше всего: реальная причина любви к HTML — это ощущение, что ты в курсе того, что делает агент. Когда я перестал читать длинные markdown-планы, у меня появился страх, что я отдал управление и просто доверяю Claude. С HTML я снова в loop'е — потому что артефакт читать действительно интересно.

Адаптация: Дан Охлопков (@danokhlopkov) · обновлено 2026-05-29 Оригинал: Tariq, Claude Code team · https://x.com/trq212/status/2052809885763747935

← На главную