---
name: spec-maintenance
description: Используй при обновлении спецификаций модулей после реализации фич или изменений в дизайне — помогает прочитать текущую спецификацию, выявить изменения и обновить до актуального состояния
---

# Поддержка спецификаций

Используй этот скилл после реализации фичи или применения дизайн-изменения для обновления соответствующей спецификации модуля в `docs/specs/`.

## Рабочий процесс

1. **Определи спецификацию модуля** для обновления на основе изменённого домена (например, Skills -> `docs/specs/skills.md`)
2. **Прочитай текущую спецификацию**, чтобы понять, что задокументировано
3. **Прочитай дизайн-документ или изменения в коде**, которые вызвали обновление — пойми, что изменилось
4. **Обнови спецификацию** для отражения текущего состояния:
   - Добавь новые сущности, эндпоинты или поведения
   - Измени существующие записи, которые изменились
   - Удали всё, что было удалено или заменено
5. **Проверь лимит ~300 строк** — если превышен, сократи таблицы или объедини связанные поведения
6. **Проверь, что не просочились история или обоснования** — спецификации описывают только текущее состояние, никогда «было изменено с X на Y» или «это было добавлено потому что...»
7. **Проверь, что структура шаблона** сохранена (см. ниже)

## Правила

- **Только текущее состояние** — никакой истории, обоснований, ссылок на дизайн-документы или PR
- **Никаких деталей реализации** — не упоминай MediatR, FluentValidation, EF Core или внутренние паттерны
- **Максимум ~300 строк** на спецификацию модуля — используй таблицы для структурированных данных, маркеры для поведений
- **Таблицы для модели данных и эндпоинтов** — маркеры для ключевых поведений
- **Ссылайся на файлы кода** для сложной логики вместо повторного объяснения

## Шаблон спецификации модуля

```markdown
# Название модуля

Краткое назначение (2-3 предложения).

## Модель данных

| Сущность | Ключевые поля | Примечания |
|----------|--------------|------------|

## API-эндпоинты

| Метод | Путь | Авторизация | Описание |
|-------|------|-------------|----------|

## Ключевые поведения

- Маркированный список важных бизнес-правил и потоков

## Структура контента

(Только для модулей на основе MDX — описывает расположение файлов и frontmatter)

## Операции администратора

(Краткое описание admin-специфичных фич, если есть)
```

## Рекомендации по разделам

**Таблица модели данных:**
- Одна строка на сущность
- Ключевые поля: перечисли важные поля (Id, Slug, FK, поля статуса, timestamps)
- Примечания: ограничения, связи, значения enum

**Таблица API-эндпоинтов:**
- Группируй по уровню авторизации или области фич, если модуль большой (используй подзаголовки)
- Колонка авторизации: Anonymous, Authenticated, Admin, Owner/Admin, Instructor/Admin
- Описание: однострочное описание того, что делает эндпоинт

**Ключевые поведения:**
- Бизнес-правила и инварианты
- Переходы состояний
- Гарантии идемпотентности
- Автоматически вызываемые побочные эффекты (например, «завершение раздела автоматически завершает навык»)
- Нюансы контроля доступа, не отражённые в таблице эндпоинтов

**Структура контента** (если применимо):
- Расположение MDX-файлов и соглашения о путях
- Что хранится в БД, а что в MDX
- Используемые кастомные MDX-компоненты

**Операции администратора:**
- Краткое описание admin-специфичных рабочих процессов
- Ограничения (например, «нельзя удалить, если есть пользовательские данные»)