# Markdown мёртв — да здравствует HTML

> Адаптация статьи Tariq из команды Claude Code · перевод и комментарии Дана Охлопкова
> Оригинал: https://x.com/trq212/status/2052809885763747935
> Примеры автора: https://thariqs.github.io/html-effectiveness

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

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

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

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

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

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

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

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

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

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

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

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

Claude пишет всё более длинные планы и спецификации. На практике 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. Получается **одноразовый редактор под конкретную задачу** — не продукт, не reusable tool, а артефакт на 30 минут.

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

Почему именно Claude Code, а не claude.ai или Claude Design? Потому что у Claude Code есть всё:

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

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

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

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

| Критерий | Markdown | HTML |
|---|---|---|
| Плотность инфы | Текст + ASCII | Текст + таблицы + SVG + JS + CSS |
| Читаемость 500+ строк | Никто не читает | Навигация, табы, mobile |
| Шеринг (Slack, TG, mail) | Файл-аттач, никто не открывает | Ссылка / PDF из HTML |
| Интерактив | Нет | Слайдеры, drag-drop, copy-кнопки |
| Цвета, иллюстрации | Эмодзи-костыли | Нативно |
| Токены на генерацию | ×1 | ×2–4 |
| Время генерации | ×1 | ×2–4 |
| Git diff | Чистый, читаемый | Шумный, ад |
| Удобно *писать* руками | Тебе | Никому |
| Удобно *читать* | Тебе одному | Всем, включая телефон |

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

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

Когда я начинаю новую задачу, вместо одного 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. И главное — можно прототипировать *интеракции*, а не только статику.

> **Промпт-пример:** «Хочу прототипировать новую кнопку 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-редактор** под неё. Не продукт, не reusable tool. Один HTML-файл, который ты выкинешь после использования.

Финальный аккорд всегда один: кнопка 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

**Это же не token-efficient?**
HTML жрёт больше токенов. Но при 1M-контексте Opus 4.7 это незаметно, а выразительность и шанс что я *дочитаю* — кратно выше. Trade хороший.

**Когда ты ещё используешь markdown?**
Tariq говорит — почти никогда. Я мягче: markdown остаётся для коротких заметок, voice memo расшифровок, ai-docs которые точно никто кроме меня не откроет. Всё что длиннее 100 строк или хоть когда-нибудь пойдёт наружу — HTML.

**Дольше же генерится?**
Да, в 2–4 раза. Окупается читаемостью.

**Как ревьюить diff'ы HTML?**
Это реально больно. Один из главных минусов. Если файл часто меняется — может быть оставь его в markdown.

**Как заставить Claude не делать уродство?**
Frontend design плагин помогает с базовым качеством. Дальше — design system файл, который ты используешь как референс.

---

## Stay in the loop

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

---

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

[← На главную](/)