LLM-readable документация: как писать про компоненты чтобы AI не изобретал велосипед

В мае 2026 в реальном job posting Senior Product Designer появилось требование которого год назад не существовало: «Создавать и поддерживать документацию системы читаемую дизайнерами, инженерами и LLM вроде Claude».

LLM как третья аудитория документации — не будущее, уже настоящее.

## Три аудитории, три разных потребности

Дизайнер понимает контекст. «Используй Primary Button для главного действия» — понятно без объяснений. Опыт подсказывает что такое «главное действие» и как выглядит это на практике.

Разработчик нуждается в точном синтаксисе. Нужен правильный пропс, правильное значение, правильный импорт. Контекст при этом тоже улавливает и может додумать детали.

AI-агент не понимает контекст и не додумывает. Если написано «использовать кнопку для действий» — AI заполняет «действие» из обучающих данных. Обычно это любое нажатие, включая навигацию. Нужны явные правила: «Button/Primary — только для CTA (сохранить, отправить, создать). Не для навигации — для этого Link».

## Пять принципов LLM-readable документации

### 1. Явность вместо подразумевания

Всё что люди понимают «по умолчанию» — написать явно.

Плохо: «Используйте Button для интерактивных действий пользователя».

Хорошо: «Используйте Button/Primary для единственного главного CTA на экране: сохранить изменения, отправить форму, создать объект, перейти к следующему шагу. Не использовать для навигации между страницами — для этого Link или NavItem».

Разница: «действие» для AI расплывчато. Список конкретных примеров — нет.

### 2. Запреты работают лучше разрешений

AI расширительно интерпретирует разрешения. Запреты — нет.

«Используй для действий» → AI использует для всего интерактивного. «Не для навигации» → AI не использует для навигации. Период.

Секция «Запрещено» с альтернативами — один из самых ценных элементов документации для AI.

### 3. Таблицы вместо прозы для параметров

Таблица пропсов читается за секунды. Проза требует интерпретации.

| Проп     | Тип                                              | Default   | Описание              |
|----------|--------------------------------------------------|-----------|-----------------------|
| variant  | "primary" \| "secondary" \| "ghost" \| "danger" | "primary" | Визуальный вариант    |
| size     | "sm" \| "md" \| "lg"                             | "md"      | Размер                |
| disabled | boolean                                           | false     | Неактивное состояние  |
| loading  | boolean                                           | false     | Состояние загрузки    |
| icon     | ReactNode                                         | —         | Иконка слева от текста|

### 4. Примеры с явными маркерами ✅ и ❌

// ✅ Правильно — единственная Primary на экране
<Button variant="primary" size="md">Сохранить изменения</Button>

// ✅ Правильно — Secondary рядом с Primary
<Button variant="secondary">Отмена</Button>
<Button variant="primary">Сохранить</Button>

// ❌ Неправильно — два Primary на одном экране
<Button variant="primary">Сохранить</Button>
<Button variant="primary">Опубликовать</Button>

// ❌ Неправильно — Primary для навигации
<Button variant="primary" onClick={() => navigate('/dashboard')}>
  На главную
</Button>
// Правильно для навигации: <Link href="/dashboard">На главную</Link>

Маркеры — буквальные инструкции. AI воспроизводит примеры с ✅, избегает примеры с ❌.

### 5. Связанные компоненты с пояснением когда использовать

AI создаёт новый компонент потому что не знает что нужный уже есть.

## Вместо Button используй
- `Link` — для навигации между страницами (не действия)
- `IconButton` — кнопка только с иконкой (aria-label обязателен)
- `ButtonGroup` — группа переключаемых взаимоисключающих вариантов
- `FAB` — главное действие поверх контента на мобайле

## Полный шаблон документации компонента

# Button

Кнопка для триггеринга действий. НЕ для навигации между страницами.

## Варианты

| Вариант     | Когда использовать                          | Ограничение                       |
|-------------|---------------------------------------------|-----------------------------------|
| `primary`   | Главное действие на экране                  | Максимум одна в видимой области   |
| `secondary` | Вторичные действия                          | —                                 |
| `ghost`     | Третичные действия в плотном интерфейсе     | Не для деструктивных действий     |
| `danger`    | Необратимые деструктивные действия          | Всегда с confirm-диалогом         |

## Запрещено
- Два `variant="primary"` в одной видимой области
- `Button` для перехода на страницу → использовать `Link`
- Кнопка только с иконкой без `aria-label`
- Кнопка с текстом длиннее 5 слов (исключение: формы)
- Захардкоженные цвета через `style` вместо variant

## Пропсы
[таблица из примера выше]

## Примеры
[код с ✅ и ❌]

## Вместо Button используй
- `Link` — навигация
- `IconButton` — только иконка
- `ButtonGroup` — группа связанных действий

## Три места хранения: разные аудитории, разная глубина

AGENTS.md — для AI, кратко (≤200 строк)

Читается каждую сессию. Длиннее — важные правила теряются.

## Button — правила для AI
primary: единственная CTA (сохранить/отправить/создать)
secondary: рядом с primary или самостоятельно
ghost: третичные действия
danger: необратимые + confirm обязателен

❌ два primary рядом
❌ Button для навигации → Link
❌ только иконка без aria-label
❌ захардкоженные цвета

Storybook MDX — для разработчиков, подробно, с живыми примерами и Controls. AI читает через Storybook MCP.

Notion/Confluence — для команды, с историей решений и контекстом почему именно так.

## Как поддерживать актуальность

Документация устаревает быстрее чем кажется. Три правила:

В том же PR что и компонент. Не «позже». Изменился API без обновления AGENTS.md — AI генерирует нерабочий код.

Changelog:

## Changelog
v1.3.0 (июнь 2026): добавлен проп loading:boolean
v1.2.0 (март 2026): deprecated isDisabled → disabled
v1.1.0 (янв 2026): добавлены варианты size: sm/md/lg

Тест через AI раз в месяц. Дай только AGENTS.md, попроси создать форму. Если AI ошибается — документация неполная. Реальная метрика: правок после генерации с хорошей документацией — 1–2. Без неё — 5–10.

## Промпт для создания LLM-readable документации

Создай LLM-readable документацию для компонента [Название].

Обязательная структура:
1. Одна строка: что это и для чего НЕ использовать
2. Таблица вариантов: вариант | когда | ограничение
3. Секция "Запрещено" с альтернативами для каждого пункта
4. Таблица пропсов: проп | TypeScript-тип | default | описание
5. Примеры с маркерами ✅ (правильно) и ❌ (неправильно)
6. "Вместо [компонента] используй" — список с пояснениями

Требования:
- Никаких подразумеваний — всё написано явно
- Правила: конкретные действия или запреты (не "рекомендуется")
- Имена пропсов из реального кода — копипаст должен работать
- После создания: тест — дай только эту документацию Claude и попроси
  создать экран с этим компонентом. Результат покажет пробелы.

## Практика: как тестировать качество документации

Тест который показывает реальное качество лучше любого ревью: открой новый чат, дай только AGENTS.md без каких-либо других инструкций, и попроси «Создай типичную форму входа для нашего продукта».

Смотришь на результат: какие компоненты AI использовал? Правильные имена из системы или придуманные? Цвета через CSS-переменные или hex? Правильный шрифт?

Каждое нарушение — это пробел в документации, не в AI. Добавляешь явный запрет или пример — тестируешь снова. Через 3–4 итерации AGENTS.md начинает давать правильный результат с первого раза.

Реальная метрика которую стоит отслеживать: количество правок после первой генерации экрана. С хорошей документацией — 1–2 правки. С плохой — 5–10 итераций объяснений. Разница — в правках или в документации.

## Когда документация делает обратное

Бывает что обильная документация мешает. AI перегружается правилами и начинает применять их неправильно — одновременно несколько конфликтующих.

Признаки перегруза: AI начинает добавлять aria-label к каждому элементу включая те которым он не нужен. Или добавляет loading-состояние к статичному тексту. Или пытается применить Typography-токены к иконкам.

Решение: документация должна быть точной, а не исчерпывающей. Лучше 10 чётких правил чем 50 вялых рекомендаций. AGENTS.md до 200 строк — это не ограничение объёма, это ограничение шума.

## Разница между документацией для людей и для AI

Дизайнеры и разработчики годами учились писать документацию для людей. Получалась документация с контекстом, с подразумеванием, иногда с юмором. «Используй основную кнопку для важных действий» — любой дизайнер понимает о чём это.

AI не понимает «важных». Для AI «важное» — то что явно маркировано как важное. Если не написано — AI заполняет пробел своим предположением из обучающих данных.

Переключить мышление от «пишу для коллеги» к «пишу для системы которая не знает контекст» — вот что делает документацию LLM-readable. Это не «писать хуже» или «примитивнее». Это писать точнее: убирать подразумевание и заменять явными правилами.

Хорошая новость: документация написанная для AI работает лучше и для людей. Она чётче, конкретнее, с примерами. Новый дизайнер или разработчик читает её — и сразу понимает что и как. Без «ну это подразумевается из контекста».

## Документация как живой продукт

Ошибка которую делают многие: написали документацию один раз и думают что она «готова». Документация компонента — живой продукт который требует поддержки как сам компонент.

При каждом PR который изменяет компонент задавай вопрос: «Нужно ли обновить документацию?». Обычно ответ «да» занимает 5 минут. Дешевле чем потом искать почему AI генерирует по старому API.

Раз в квартал: пройтись по всем компонентам и проверить что документация соответствует реальности. Компоненты которые давно не трогали — начать с них, там больше всего устаревшего.

Три метрики качества документации:

Количество правок после первой AI-генерации. Хорошая документация → 1–2 правки. Плохая → 5–10 итераций.

Количество вопросов «как использовать этот компонент» в неделю. Хорошая документация → вопросов нет, ответ находится в документации. Плохая → постоянные вопросы в чате.

Процент AI-генераций которые используют правильные компоненты из системы. Можно проверять раз в месяц через тест из предыдущего раздела.

## Почему запреты работают лучше разрешений

В документации для людей мы пишем что можно и иногда что нельзя. Для AI соотношение должно быть обратным: больше явных запретов, меньше открытых разрешений.

Причина в том как AI интерпретирует неопределённость. «Используй кнопку для действий» — AI считает это разрешением использовать кнопку для любого интерактивного элемента, включая навигацию. «Не использовать Button для навигации между страницами» — однозначный запрет который AI соблюдает.

Практическое следствие: при написании документации пройди по каждому правилу и спроси «как AI может интерпретировать это расширительно?» Ответ показывает что нужно сформулировать как явный запрет.

Пример: «Button/Primary — для главного действия» → AI может поставить три Primary Button потому что три действия «главные». Правильно: «Button/Primary — для единственного CTA в видимой области. Запрещено: более одного Button/Primary на экране».

Это звучит избыточно для человека. Для AI — необходимо.

## Тест: проверь свою документацию прямо сейчас

Возьми AGENTS.md. Открой новый чат с Claude Code или Cursor. Вставь только содержимое AGENTS.md как системный промпт. Попроси: «Создай страницу профиля пользователя».

Смотри на результат: какие компоненты AI выбрал? Правильные имена? Правильные варианты? Правильные CSS-переменные для цветов?

Каждое отклонение от ожидаемого — это недостающее правило в документации. Добавь его явно. Повтори тест. Через 3–4 итерации документация начнёт давать консистентный результат.

Это самый быстрый способ улучшить документацию — не думать что в ней не хватает, а смотреть где AI ошибается.

## Когда документация мешает: признаки перегруза

Бывает что слишком подробная документация работает хуже короткой. AI начинает применять правила некорректно: добавляет aria-label к каждому элементу включая те которым он не нужен, или применяет typography-токены к иконкам.

Признаки перегруза в AGENTS.md:

• AI добавляет loading проп к статичному тексту
• AI ставит disabled на кнопки которые не должны быть неактивными
• AI применяет одно правило везде игнорируя контекст

Решение: AGENTS.md до 200 строк — это не ограничение объёма, это ограничение шума. Десять чётких правил работают лучше пятидесяти расплывчатых рекомендаций.

Принцип отбора: включай только правила которые AI нарушает без них. Если AI никогда не использует Inter — не нужно запрещать Inter. Если AI иногда ставит два Primary Button — запрети явно. Документация от реальных проблем, не от предполагаемых.

## Changelog: три строки которые меняют качество поддержки

Самое простое улучшение которое делают единицы: добавить секцию Changelog в каждый компонент.

# Button

## Changelog
v1.3.0 (июнь 2026): добавлен проп loading:boolean, иконку справа
v1.2.0 (март 2026): deprecated isDisabled → используй disabled
v1.1.0 (янв 2026): добавлены size: sm | md | lg

AI видит changelog и понимает актуальный API без дополнительных объяснений. Разработчик который не был на последнем митинге понимает что изменилось. Новый человек в команде видит историю решений.

Три строки на обновление. Экономит часы на «почему мой код не работает» вопросы.

☐ Одна строка: что и для чего НЕ использовать
☐ Таблица вариантов с явными ограничениями
☐ Секция "Запрещено" с альтернативами
☐ Таблица пропсов с TypeScript-типами и дефолтами
☐ Примеры с ✅ и ❌
☐ "Вместо X используй" — список с пояснениями
☐ AGENTS.md ≤200 строк (только самое критичное)
☐ Storybook MDX — полная версия для разработчиков
☐ Обновляется в том же PR что и компонент
☐ Changelog при изменении API