update-component-ai-md

name	update-component-ai-md
description	Создаёт или обновляет src/components/{Name}/{Name}-ai.md по docs/ai/template-ai.md на основе текущих исходников компонента, его stories и тестов. Используй когда добавляется AI-документация в Phase 1 ROADMAP, либо когда меняется публичный API компонента и нужно обновить существующий AI.md.

update-component-ai-md

Заполняет или обновляет src/components/{Name}/{Name}-ai.md по шаблону docs/ai/template-ai.md. Документ должен точно отражать текущий код, stories и инварианты.

Когда нужен AI.md

Сначала проверь docs/ai/CONTEXT.md → раздел «Когда создавать {ComponentName}-ai.md».

Создавай AI.md только если выполняются оба условия:

1. Компонент экспортируется из публичного barrel src/components/{Family}/index.ts.
2. У компонента нетривиальный API: собственные props сверх className + ref + ...rest, либо state, контекст, клавиатура, callback'и, accessibility-контракт, render-prop, discriminated union.

Тривиальные wrapper'ы описывай разделом «Связанные компоненты» в AI.md родителя.

Источники для заполнения

Секция	Откуда брать
frontmatter.component, category	Имя компонента и группа в barrel-структуре src/components/
frontmatter.related	Сиблинги в той же папке + используемые публично через index.ts (Loader, IconWrapper и т.д.)
frontmatter.tokens	grep по var(--triplex-next-{Name}- в styles/*.module.less
frontmatter.stories	Найти *{Name}.stories.tsx в stories/
frontmatter.version	Текущая мажорная — "1.0" (минор обновляется при breaking change в API)
Назначение	Из исходников + JSDoc на компоненте + название и роль в семействе
Варианты и props	Из TypeScript-интерфейсов в *.tsx/types.ts. Не дублируй типы целиком — описывай намерения и ограничения.
Дизайн-токены	Полный список CSS-переменных из стилей
Инварианты	forwardRef, имена публичных props/enum, корневой DOM-элемент, любые контракты, упомянутые в docs/ai/CONTEXT.md → «Инварианты»
Accessibility	Из реализации: ARIA-атрибуты, фокус-менеджмент, keyboard-обработчики, aria-роль
Связанные компоненты	Sibling-компоненты в той же папке, особенно тривиальные обёртки без своего AI.md
Stories	Файлы из stories/{Group}/examples/{Name}/ — таблица с колонкой Example file
История изменений	Дописывается при каждом обновлении документа

Workflow

Создание нового AI.md

1. Прочитай docs/ai/template-ai.md целиком.
2. Прочитай docs/ai/CONTEXT.md → разделы «Соглашения по именованию», «Дизайн-токены», «Инварианты».
3. Изучи весь код в src/components/{Name}/: tsx, ts, types.ts, styles, тесты.
4. Изучи stories и examples компонента.
5. Найди соседние AI.md в той же категории как референс паттерна (src/components/Button/Button-ai.md, src/components/List/List-ai.md).
6. Заполни шаблон. Удали HTML-комментарии-инструкции (<!-- ... -->) после заполнения.
7. В таблице Stories обязательно проставь колонку Example file — её читает scripts/generateMcpData.ts.
8. В «История изменений» добавь запись | YYYY-MM-DD | Создан документ | с сегодняшней датой.

Обновление существующего AI.md

1. Прочитай текущий {Name}-ai.md целиком.
2. Сверь каждую секцию с актуальным кодом:
   • Frontmatter tokens — пересчитай grep'ом
   • «Варианты и props» — сверь с интерфейсами
   • «Дизайн-токены» — пересчитай
   • «Инварианты» — добавь новые, если появились
   • «Stories» — сверь таблицу с файлами в examples/
3. Сохрани разделы, написанные человеком (Назначение, Не используй когда, Accessibility-описания) — обновляй точечно, не переписывай ради переписывания.
4. Допиши строку в «Историю изменений» с описанием что менялось:

   | 2026-05-04 | Добавлен prop `loading`, обновлены токены, описание клавиатурной навигации |
   

Жёсткие правила

• Не дублируй TypeScript-типы целиком — IDE/AI агент прочтёт их из исходника. AI.md описывает намерения и ограничения, которые из кода не видны.
• Колонка Example file в таблице Stories обязательна — её парсит scripts/generateMcpData.ts для сборки MCP bundle. Если у story нет отдельного example-файла — поставь —.
• Playground и VisualTests оставляй в таблице для человека, но Example file для них формальный — в MCP bundle они не попадают (фильтруются по имени).
• Accessibility секция обязательна для интерактивных компонентов (кнопки, поля, dialogs, dropdowns). Для тривиальных контейнеров — можно пропустить.
• Frontmatter — машиночитаемый. Не ломай формат YAML, не добавляй кастомные поля без согласования (mcp-server полагается на консистентность шаблона).
• Пиши по-русски — все существующие AI.md на русском, библиотека внутрироссийская.

Чек-лист перед завершением

• Frontmatter заполнен полностью (component, category, related, tokens, stories, version)
• Все HTML-комментарии-инструкции удалены
• Таблица Stories — все стори с колонкой Example file
• Accessibility описана (для интерактивных компонентов)
• Инварианты включают forwardRef и любые специфичные для компонента
• «История изменений» дополнена сегодняшней записью
• Файл сохранён в src/components/{Name}/{Name}-ai.md

Где не заполнять полностью

Если по результатам аудита какой-то раздел остаётся пустым (например, у компонента нет accessibility-нюансов сверх стандартного <button>), напиши коротко «Стандартное поведение <button>, отдельных требований нет» — не оставляй пустые заголовки, иначе документ выглядит недописанным.

После заполнения

Сообщи пользователю:

1. Какие секции заполнил автоматически из кода.
2. Какие секции нужно проверить вручную (Назначение, Когда использовать / не использовать — это семантика, агент может ошибиться).
3. Список найденных дизайн-токенов и инвариантов — попроси подтвердить.