--- 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. Допиши строку в «Историю изменений» с описанием что менялось: ```text | 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-нюансов сверх стандартного `