nextjs-style-guide/CONTRIBUTING.md

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

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

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

Базовые правила (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:

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

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

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

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

# {Название}

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

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

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

## Структура

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

## Правила

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

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

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

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

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

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

## Типизация

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

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

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

## Примеры

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

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

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

Заголовки

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

Примеры кода

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

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

**Хорошо:**

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

**Плохо:**

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

Таблицы

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

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

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

Принципы

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