156 lines
6.4 KiB
Markdown
156 lines
6.4 KiB
Markdown
# Правила написания документации
|
||
|
||
Как писать и редактировать разделы стайлгайда.
|
||
|
||
## Типы разделов
|
||
|
||
### Базовые правила (`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. **Примеры обязательны.** Прикладной раздел без примеров — незавершён.
|