# Правила написания документации

Как писать и редактировать разделы стайлгайда.

## Типы разделов

### Базовые правила (`basics/`)

**Отвечает на вопрос:** «Каким должен быть любой код?»

Универсальные стандарты, не привязанные к конкретной области.
Правило базовое, если оно применимо ко всему коду одинаково.

**Граница:** если правило касается только одной области — оно прикладное.

### Прикладные разделы (`applied/`)

**Отвечает на вопрос:** «Как работать с X?»

Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.

**Граница:** не дублирует базовые правила. Если правило уже описано в базовых — ссылается, но не повторяет.

### Триггеры (`triggers/`)

**Отвечает на вопрос:** «Как выполнить задачу X?»

Конкретная инструкция: какие разделы прочитать, какие шаги выполнить. Триггер ссылается на basics/ и applied/, но не дублирует их. Группируются по роли: `triggers/develop/`, `triggers/review/`, `triggers/architect/`.

Структура триггера:

- **Заголовок** — глагол + объект ("Создать компонент", "Добавить иконку")
- **Описание** — одно предложение: что делает триггер
- **Прочитай перед началом** — ссылки на basics/ и applied/
- **Шаги** — нумерованный список действий со ссылками
- **Смежные триггеры** — ссылки на связанные задачи
- **Проверь себя** — чеклист из 2-5 пунктов для самопроверки

### Фреймворк-специфичные (`{framework}/`)

Разделы и триггеры, которые применимы только к конкретному фреймворку. Те же категории — `applied/` и `triggers/`.

**Граница:** если правило одинаково для всех фреймворков — оно в `base/`.

## Frontmatter

Каждый `.md`-файл начинается с YAML frontmatter:

```yaml
---
title: Название раздела
scope: basics | applied | triggers
keywords: [ключевое слово 1, ключевое слово 2]
when: "Когда агенту читать этот раздел"
---
```

| Поле | Описание |
|------|----------|
| `title` | Название раздела. Совпадает с `h1` в файле |
| `scope` | Тип: `basics`, `applied` или `triggers` |
| `keywords` | Ключевые слова для поиска агентом |
| `when` | Описание ситуации, когда раздел релевантен |

## Структура прикладного раздела

Раздел включает только релевантные секции — пустые не создаются.

```markdown
# {Название}

Краткое описание: о чём раздел.

## Что нужно знать

Неочевидная вводная информация (если есть).

## Структура

Файловая организация. Обязательно — дерево файлов.

## Правила

### Реализация

Как писать код: синтаксис, паттерны, API.

### Организация

Где что лежит: файловые границы, зоны ответственности, экспорт.

## Именование

Специфичные для области соглашения (не покрытые в basics/naming).

## Типизация

Специфичные для области правила (не покрытые в basics/typing).

## Документирование

Специфичные для области правила (не покрытые в basics/documentation).

## Примеры

Полноценные примеры кода с путями к файлам.
```

Порядок фиксированный: контекст -> структура -> правила -> специализации базовых -> примеры.

## Конвенции оформления

### Заголовки

- Один `h1` на файл — совпадает с `title` из frontmatter.
- Сразу после `h1` — вводный абзац.
- Основные секции — `h2`. Подсекции — `h3`. `h4` не используется.

### Примеры кода

- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
- Путь к файлу — перед блоком кода или комментарием внутри.
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.

### Блоки «Хорошо / Плохо»

```markdown
**Хорошо:**

\`\`\`tsx
// правильный код
\`\`\`

**Плохо:**

\`\`\`tsx
// неправильный код
\`\`\`
```

### Таблицы

Формат — стандартный Markdown: `| Ключ | Описание |`.

### Ссылки между разделами

Ссылаться можно, дублировать содержимое — нет.

## Принципы

1. **Не дублировать.** Одна мысль — одно место. Остальные ссылаются.
2. **Базовое vs прикладное.** Применимо ко всему коду — базовое. К одной области — прикладное.
3. **Общее vs специфичное.** Одинаково для всех фреймворков — в `base/`. Для одного — в `{framework}/`.
4. **Пустые секции не создавать.**
5. **Примеры обязательны.** Прикладной раздел без примеров — незавершён.