diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c408fdc..02a4c78 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -185,6 +185,50 @@ title: Название раздела - Подсекции внутри `h2` — `h3`. - `h4` не используется. +### Вводный абзац + +Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?». +Он попадает в `llms.txt` и `README.md` архива как краткое описание, +поэтому должен быть плотным и без воды. + +**Правила:** + +- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе», + «Здесь рассмотрено», «В этом документе». +- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`). +- Двоеточие или тире для перечисления **категорий и областей**, а не + конкретных значений из содержимого. +- Не дублировать содержимое: если внутри раздела 12 правил — + не перечислять их во вводном абзаце. +- Не аргументировать («единые правила делают код предсказуемым»). +- 1–2 предложения. + +**Проверка:** если при добавлении нового правила/инструмента/раздела +вводный абзац придётся править — он слишком конкретный. + +**Хорошо:** + +```markdown +Слои SLM: назначение, классификация, направление зависимостей, правила. +``` + +```markdown +Базовый стек проекта по областям: UI, архитектура, данные, состояние, +локализация, тестирование, стили, генерация кода. +``` + +**Плохо:** + +```markdown +Раздел описывает слои SLM: что такое слой, какие бывают, как между +ними направлены зависимости и какие правила действуют на каждом. +``` + +```markdown +Этот раздел описывает базовый стек технологий и библиотек, принятый в +проекте. React, TypeScript, Next.js, SWR, Zustand, i18next. +``` + ### Примеры кода - Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `. diff --git a/README.md b/README.md index 0baefe1..39bd837 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # NextJS Style Guide -Rules and standards for NextJS and TypeScript development: architecture, typing, styles, components, API, and infrastructure. +Conventions for Next.js project development: application architecture and layers, code structure, module organization, styling, typing, and infrastructure. ## Documentation Structure @@ -26,7 +26,7 @@ Rules and standards for NextJS and TypeScript development: architecture, typing, | Section | Answers the question | |---------|---------------------| | Tech Stack | What stack do we use? | -| Architecture | How are FSD layers, dependencies, and public API structured? | +| Architecture | How are SLM layers, dependencies, and public API structured? | | Code Style | How to format code: indentation, quotes, imports, early return? | | Naming | How to name files, variables, components, hooks? | | Documentation | How to write JSDoc: what to document and what not? | @@ -51,8 +51,3 @@ Rules and standards for NextJS and TypeScript development: architecture, typing, | Hooks | _(not filled)_ | | Fonts | _(not filled)_ | | Localization | _(not filled)_ | - -## For Assistants - -Documentation map with links to all sections ([llmstxt.org](https://llmstxt.org) format): -https://gromlab.ru/docs/nextjs-style-guide/raw/branch/main/generated/en/llms.txt diff --git a/README_RU.md b/README_RU.md index 6278457..75e9289 100644 --- a/README_RU.md +++ b/README_RU.md @@ -1,11 +1,6 @@ # NextJS Style Guide -Правила и стандарты разработки на NextJS и TypeScript: архитектура, типизация, стили, компоненты, API и инфраструктурные разделы. - -## Для ассистентов - -Карта документации со ссылками на все разделы (формат [llmstxt.org](https://llmstxt.org)): -https://gromlab.ru/docs/nextjs-style-guide/raw/branch/main/generated/ru/llms.txt +Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура. ## Структура документации diff --git a/docs/ru/applied/project-structure.md b/docs/ru/applied/project-structure.md index 423d7b8..f85fdc9 100644 --- a/docs/ru/applied/project-structure.md +++ b/docs/ru/applied/project-structure.md @@ -4,7 +4,7 @@ title: Структура проекта # Структура проекта -Раздел описывает расположение файлов и папок в проекте Next.js (App Router). +Файловая организация Next.js-проекта по архитектуре SLM. ## Корень репозитория diff --git a/docs/ru/applied/styles.md b/docs/ru/applied/styles.md index 5ce5cdd..3633133 100644 --- a/docs/ru/applied/styles.md +++ b/docs/ru/applied/styles.md @@ -4,7 +4,7 @@ title: Стили # Стили -Раздел описывает правила написания CSS: PostCSS Modules, вложенность, медиа-запросы, переменные, форматирование. +Правила написания CSS: PostCSS Modules, форматирование, переменные. ## Общие правила diff --git a/docs/ru/basics/architecture/index.md b/docs/ru/basics/architecture/index.md index 742d600..eb15f39 100644 --- a/docs/ru/basics/architecture/index.md +++ b/docs/ru/basics/architecture/index.md @@ -1,6 +1,5 @@ --- title: Архитектура -description: "Раздел описывает архитектуру проекта: из каких слоёв состоит приложение, как организован код внутри слоёв и какие правила управляют зависимостями." --- # SLM Design diff --git a/docs/ru/basics/architecture/reference/layers.md b/docs/ru/basics/architecture/reference/layers.md index c313273..56457d2 100644 --- a/docs/ru/basics/architecture/reference/layers.md +++ b/docs/ru/basics/architecture/reference/layers.md @@ -4,7 +4,7 @@ title: Слои # Слои -Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом. +Слои SLM: назначение, классификация, направление зависимостей, правила. ## Определение diff --git a/docs/ru/basics/architecture/reference/modules.md b/docs/ru/basics/architecture/reference/modules.md index 4bb7b0d..1af3c60 100644 --- a/docs/ru/basics/architecture/reference/modules.md +++ b/docs/ru/basics/architecture/reference/modules.md @@ -4,7 +4,7 @@ title: Модули # Модули -Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом. +Модули SLM: состав, границы, взаимодействие с остальным кодом. ## Определение diff --git a/docs/ru/basics/architecture/reference/segments.md b/docs/ru/basics/architecture/reference/segments.md index f68240d..0d095f9 100644 --- a/docs/ru/basics/architecture/reference/segments.md +++ b/docs/ru/basics/architecture/reference/segments.md @@ -4,7 +4,7 @@ title: Сегменты # Сегменты -Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит. +Сегменты SLM: типы, назначение, что лежит внутри каждого. ## Определение diff --git a/docs/ru/basics/code-style.md b/docs/ru/basics/code-style.md index ed6b06b..232f0ee 100644 --- a/docs/ru/basics/code-style.md +++ b/docs/ru/basics/code-style.md @@ -4,7 +4,7 @@ title: Стиль кода # Стиль кода -Раздел описывает единые правила оформления кода: отступы, переносы, кавычки, порядок импортов и базовую читаемость. +Единые правила оформления кода: форматирование, импорты, читаемость. ## Отступы diff --git a/docs/ru/basics/documentation.md b/docs/ru/basics/documentation.md index a70c209..bfed283 100644 --- a/docs/ru/basics/documentation.md +++ b/docs/ru/basics/documentation.md @@ -4,8 +4,7 @@ title: Документирование # Документирование -Этот раздел описывает правила документирования кода: когда и как писать -комментарии к компонентам, функциям, типам и интерфейсам. +Правила документирования кода: что и когда документировать через JSDoc. ## Общие правила diff --git a/docs/ru/basics/naming.md b/docs/ru/basics/naming.md index a7c37fb..b4148a0 100644 --- a/docs/ru/basics/naming.md +++ b/docs/ru/basics/naming.md @@ -4,7 +4,7 @@ title: Именование # Именование -Этот раздел описывает соглашения об именовании в проекте. Единые правила делают код предсказуемым и упрощают навигацию по проекту. +Соглашения об именовании в коде: что и как называть. ## Базовые правила diff --git a/docs/ru/basics/tech-stack.md b/docs/ru/basics/tech-stack.md index 8cbc978..2a56fb7 100644 --- a/docs/ru/basics/tech-stack.md +++ b/docs/ru/basics/tech-stack.md @@ -4,7 +4,7 @@ title: Технологии и библиотеки # Технологии и библиотеки -Этот раздел описывает базовый стек технологий и библиотек, принятый в проекте. +Базовый стек проекта по областям: UI, архитектура, данные, состояние, локализация, тестирование, стили, генерация кода. ## Что используем diff --git a/docs/ru/basics/typing.md b/docs/ru/basics/typing.md index 3da8967..c125e51 100644 --- a/docs/ru/basics/typing.md +++ b/docs/ru/basics/typing.md @@ -4,7 +4,7 @@ title: Типизация # Типизация -Этот раздел описывает правила типизации: как типизировать компоненты, функции и работу с `any`/`unknown`. +Правила типизации в TypeScript: общие принципы и работа с динамическими типами. ## Общие правила