docs: добавлен CONTRIBUTING.md, удалён AGENTS.md
- создан CONTRIBUTING.md с мета-правилами работы над документацией - описаны три типа документации (workflow, базовые, прикладные) и границы между ними - добавлен шаблон структуры прикладного раздела - зафиксированы конвенции оформления (frontmatter, заголовки, примеры, таблицы) - удалён устаревший AGENTS.md
This commit is contained in:
32
AGENTS.md
32
AGENTS.md
@@ -1,32 +0,0 @@
|
|||||||
# NextJS Style Guide — правила для агентов
|
|
||||||
|
|
||||||
Это проект документации (VitePress). Агент является основным писателем контента в этом проекте — записывает, оформляет и редактирует материал по указаниям пользователя.
|
|
||||||
|
|
||||||
## Документация
|
|
||||||
|
|
||||||
### Tip-блоки со ссылками
|
|
||||||
При создании или редактировании документации добавлять tip-блоки (`::: tip`)
|
|
||||||
с ссылками на связанные разделы, где можно найти развёрнутое описание
|
|
||||||
процесса, действия или настройки.
|
|
||||||
|
|
||||||
Формат:
|
|
||||||
```
|
|
||||||
::: tip Заголовок блока
|
|
||||||
Описание — [Название раздела](/путь).
|
|
||||||
:::
|
|
||||||
```
|
|
||||||
|
|
||||||
Заголовок обязателен — он должен кратко описывать о чём блок.
|
|
||||||
Описание должно объяснять что найдёт читатель по ссылке.
|
|
||||||
|
|
||||||
### Структура разделов
|
|
||||||
- **Workflow** — порядок действий ("что делать и в каком порядке")
|
|
||||||
- **Базовые правила** — стандарты и конвенции ("каким должен быть код")
|
|
||||||
- **Прикладные разделы** — конфигурация и устройство конкретной области ("как это настроить и использовать")
|
|
||||||
|
|
||||||
Не дублировать информацию между разделами — использовать ссылки.
|
|
||||||
|
|
||||||
### Единообразие
|
|
||||||
- Заголовок страницы (h1) совпадает с названием в sidebar.
|
|
||||||
- Описание раздела (текст после h1) раскрывает смысл через "Как...".
|
|
||||||
- Не описывать инструменты генерации в каждом разделе — ссылаться на прикладной раздел "Шаблоны и генерация кода".
|
|
||||||
220
CONTRIBUTING.md
Normal file
220
CONTRIBUTING.md
Normal file
@@ -0,0 +1,220 @@
|
|||||||
|
# Правила работы над документацией
|
||||||
|
|
||||||
|
Мета-документ: как устроен проект, как писать и редактировать разделы.
|
||||||
|
|
||||||
|
## О проекте
|
||||||
|
|
||||||
|
Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
|
||||||
|
|
||||||
|
- Движок: VitePress
|
||||||
|
- Языки: русский (основной), английский
|
||||||
|
- Русская версия: `docs/ru/`
|
||||||
|
- Английская версия: `docs/en/`
|
||||||
|
|
||||||
|
## Команды
|
||||||
|
|
||||||
|
| Команда | Что делает |
|
||||||
|
|---------|-----------|
|
||||||
|
| `npm run dev` | Локальный сервер разработки |
|
||||||
|
| `npm run build` | Сборка статического сайта |
|
||||||
|
| `npm run docs` | Генерация `generated/{lang}/RULES.md` — единый файл для AI-ассистентов |
|
||||||
|
|
||||||
|
## Структура файлов
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── ru/ # Русская версия (основная)
|
||||||
|
│ ├── index.md # Главная страница
|
||||||
|
│ ├── workflow.md # Workflow (единый файл)
|
||||||
|
│ ├── basics/ # Базовые правила
|
||||||
|
│ │ ├── tech-stack.md
|
||||||
|
│ │ ├── architecture.md
|
||||||
|
│ │ ├── code-style.md
|
||||||
|
│ │ ├── naming.md
|
||||||
|
│ │ ├── documentation.md
|
||||||
|
│ │ └── typing.md
|
||||||
|
│ └── applied/ # Прикладные разделы
|
||||||
|
│ ├── vscode.md
|
||||||
|
│ ├── project-structure.md
|
||||||
|
│ ├── components.md
|
||||||
|
│ ├── page-level.md
|
||||||
|
│ ├── templates-generation.md
|
||||||
|
│ ├── styles.md
|
||||||
|
│ ├── images-sprites.md
|
||||||
|
│ ├── svg-sprites.md
|
||||||
|
│ ├── video.md
|
||||||
|
│ ├── api.md
|
||||||
|
│ ├── stores.md
|
||||||
|
│ ├── hooks.md
|
||||||
|
│ ├── fonts.md
|
||||||
|
│ └── localization.md
|
||||||
|
├── en/ # Английская версия (зеркало ru/)
|
||||||
|
.vitepress/
|
||||||
|
├── config.ts # Конфигурация VitePress, сайдбары, локали
|
||||||
|
generated/
|
||||||
|
├── ru/RULES.md # Сгенерированный единый файл (ru)
|
||||||
|
└── en/RULES.md # Сгенерированный единый файл (en)
|
||||||
|
concat-md.js # Скрипт генерации RULES.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Добавление нового раздела
|
||||||
|
|
||||||
|
1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`).
|
||||||
|
2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
|
||||||
|
3. Добавить файл в массив `fileOrder` — `concat-md.js` (для генерации RULES.md).
|
||||||
|
|
||||||
|
## Три типа документации
|
||||||
|
|
||||||
|
### Workflow
|
||||||
|
|
||||||
|
**Отвечает на вопрос:** «Что делать и в каком порядке?»
|
||||||
|
|
||||||
|
Пошаговые инструкции. Описывает процесс, а не правила.
|
||||||
|
Не содержит развёрнутых примеров кода — только минимальные команды и шаги.
|
||||||
|
|
||||||
|
Живёт в одном файле `workflow.md`.
|
||||||
|
|
||||||
|
### Базовые правила
|
||||||
|
|
||||||
|
**Отвечает на вопрос:** «Каким должен быть любой код?»
|
||||||
|
|
||||||
|
Универсальные стандарты, **не привязанные к конкретной области**.
|
||||||
|
Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
|
||||||
|
|
||||||
|
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
|
||||||
|
|
||||||
|
**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
|
||||||
|
|
||||||
|
### Прикладные разделы
|
||||||
|
|
||||||
|
**Отвечает на вопрос:** «Как работать с X?»
|
||||||
|
|
||||||
|
Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
|
||||||
|
|
||||||
|
**Граница:** прикладной раздел не дублирует базовые правила.
|
||||||
|
Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
|
||||||
|
|
||||||
|
## Структура прикладного раздела
|
||||||
|
|
||||||
|
Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# {Название}
|
||||||
|
|
||||||
|
Одно-два предложения: что это за область, зачем она нужна.
|
||||||
|
|
||||||
|
## Что нужно знать
|
||||||
|
|
||||||
|
Контекст перед правилами: технологии, термины, принципы работы.
|
||||||
|
Не правила — фундамент, без которого правила будут непонятны.
|
||||||
|
|
||||||
|
## Структура
|
||||||
|
|
||||||
|
Файловая организация: какие файлы создавать и куда класть.
|
||||||
|
Обязательно — дерево файлов через code-block.
|
||||||
|
|
||||||
|
## Правила
|
||||||
|
|
||||||
|
Конкретные требования к реализации в этой области.
|
||||||
|
Формат — маркированный или нумерованный список.
|
||||||
|
Для неочевидных случаев — блоки «Хорошо / Плохо».
|
||||||
|
|
||||||
|
## Именование
|
||||||
|
|
||||||
|
Соглашения по именам, специфичные для этой области.
|
||||||
|
Только то, что НЕ покрыто в базовом разделе «Именование».
|
||||||
|
|
||||||
|
## Типизация
|
||||||
|
|
||||||
|
Правила типизации, специфичные для этой области.
|
||||||
|
Только то, что НЕ покрыто в базовом разделе «Типизация».
|
||||||
|
|
||||||
|
## Документирование
|
||||||
|
|
||||||
|
Что и как документировать в этой области.
|
||||||
|
Только то, что НЕ покрыто в базовом разделе «Документирование».
|
||||||
|
|
||||||
|
## Примеры
|
||||||
|
|
||||||
|
Полноценные примеры кода.
|
||||||
|
Каждый пример с путём к файлу и пояснениями.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Порядок секций
|
||||||
|
|
||||||
|
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
|
||||||
|
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
|
||||||
|
|
||||||
|
### Секции-расширения базовых правил
|
||||||
|
|
||||||
|
«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
|
||||||
|
|
||||||
|
- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
|
||||||
|
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
|
||||||
|
|
||||||
|
Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
|
||||||
|
|
||||||
|
## Конвенции оформления
|
||||||
|
|
||||||
|
### Frontmatter
|
||||||
|
|
||||||
|
Каждый `.md`-файл начинается с YAML frontmatter:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
title: Название раздела
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
Значение `title` совпадает с текстом `h1`-заголовка в файле.
|
||||||
|
|
||||||
|
### Заголовки
|
||||||
|
|
||||||
|
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
||||||
|
- Сразу после `h1` — вводный абзац (одно-два предложения).
|
||||||
|
- Основные секции — `h2`.
|
||||||
|
- Подсекции внутри `h2` — `h3`.
|
||||||
|
- `h4` не используется.
|
||||||
|
|
||||||
|
### Примеры кода
|
||||||
|
|
||||||
|
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||||||
|
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
|
||||||
|
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.
|
||||||
|
|
||||||
|
### Блоки «Хорошо / Плохо»
|
||||||
|
|
||||||
|
Используются для контрастного сравнения правильного и неправильного подхода.
|
||||||
|
|
||||||
|
Формат:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
**Хорошо:**
|
||||||
|
|
||||||
|
\`\`\`tsx
|
||||||
|
// правильный код
|
||||||
|
\`\`\`
|
||||||
|
|
||||||
|
**Плохо:**
|
||||||
|
|
||||||
|
\`\`\`tsx
|
||||||
|
// неправильный код
|
||||||
|
\`\`\`
|
||||||
|
```
|
||||||
|
|
||||||
|
### Таблицы
|
||||||
|
|
||||||
|
Используются для структурированных перечислений: настройки, команды, соответствия.
|
||||||
|
Формат — стандартный Markdown: `| Ключ | Описание |`.
|
||||||
|
|
||||||
|
### Ссылки между разделами
|
||||||
|
|
||||||
|
Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
||||||
|
|
||||||
|
## Принципы
|
||||||
|
|
||||||
|
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
||||||
|
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
|
||||||
|
3. **Workflow vs правила.** Workflow описывает процесс (шаги). Правила описывают результат (каким должен быть код).
|
||||||
|
4. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
|
||||||
|
5. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
|
||||||
Reference in New Issue
Block a user