From 43f2d922019f924dd43f252bdb459992600a952e Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Mon, 30 Mar 2026 09:10:21 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=20CONTRIBUTING.md,=20=D1=83=D0=B4=D0=B0=D0=BB?= =?UTF-8?q?=D1=91=D0=BD=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - создан CONTRIBUTING.md с мета-правилами работы над документацией - описаны три типа документации (workflow, базовые, прикладные) и границы между ними - добавлен шаблон структуры прикладного раздела - зафиксированы конвенции оформления (frontmatter, заголовки, примеры, таблицы) - удалён устаревший AGENTS.md --- AGENTS.md | 32 ------- CONTRIBUTING.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 220 insertions(+), 32 deletions(-) delete mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 3f19123..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,32 +0,0 @@ -# NextJS Style Guide — правила для агентов - -Это проект документации (VitePress). Агент является основным писателем контента в этом проекте — записывает, оформляет и редактирует материал по указаниям пользователя. - -## Документация - -### Tip-блоки со ссылками -При создании или редактировании документации добавлять tip-блоки (`::: tip`) -с ссылками на связанные разделы, где можно найти развёрнутое описание -процесса, действия или настройки. - -Формат: -``` -::: tip Заголовок блока -Описание — [Название раздела](/путь). -::: -``` - -Заголовок обязателен — он должен кратко описывать о чём блок. -Описание должно объяснять что найдёт читатель по ссылке. - -### Структура разделов -- **Workflow** — порядок действий ("что делать и в каком порядке") -- **Базовые правила** — стандарты и конвенции ("каким должен быть код") -- **Прикладные разделы** — конфигурация и устройство конкретной области ("как это настроить и использовать") - -Не дублировать информацию между разделами — использовать ссылки. - -### Единообразие -- Заголовок страницы (h1) совпадает с названием в sidebar. -- Описание раздела (текст после h1) раскрывает смысл через "Как...". -- Не описывать инструменты генерации в каждом разделе — ссылаться на прикладной раздел "Шаблоны и генерация кода". diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ed12f3f --- /dev/null +++ b/CONTRIBUTING.md @@ -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. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.