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

Обязательный документ для агентов и разработчиков. Описывает, что, когда и как документировать после того, как функциональность реализована.

Планы, обоснования и проектные решения сюда не входят — они живут в docs/plans/ (design-документ + план) и architecture/, пишутся до кода и по другим правилам. Этот документ — про описание того, что уже работает.

Правила написания кода — в coding-rules.md.

1. Принцип

Документация — часть определения готовности, а не отдельная задача «потом». Функциональность считается сделанной, когда её поведение описано там, где его будут искать.

Три следствия:

Документируется реализованное поведение, в настоящем времени. «Эндпоинт возвращает 204», а не «будет возвращать». Если чего-то ещё нет — этому место в docs/plans/, а не на странице сервиса.
Документация правится в том же PR, что и код. Допустимо отдельным коммитом docs(<scope>): ... — так уже принято (015bfea после f037f41), — но не отдельным PR и не «позже».
Одно место истины. Факт описывается один раз, в остальных местах — ссылка. Копия таблицы эндпоинтов в трёх файлах гарантированно разъедется.

2. Где что живёт

Уровень	Где	Что описывает	Объём
Библиотека	`libs/.../<lib>/README.md`	что это за библиотека, зачем нужна, ссылки на детали	5–15 строк
Контракт фичи	`libs/.../<lib>/docs/<тема>.md`	детальный контракт: эндпоинты, тела, коды ответов, домен	по необходимости
Сервис	`docs/03-services/<домен>/<service>.md`	сервис целиком: состав, HTTP API, операции, зависимости	150–250 строк
Сквозные темы	`docs/04-shared-and-utils/`, `docs/05-data/`, `docs/06-operations/`	общие библиотеки, конфиги, данные, эксплуатация	—
Обзор	`docs/01-overview/`, `docs/02-apps/`	архитектура, стек, соглашения, bootstrap приложений	—
Машинный контракт	Swagger на `api/v1/docs`	генерируется из декораторов, руками не пишется	—

Swagger — не замена документации: он показывает форму запроса, но не отвечает на вопросы «зачем это», «какие переходы статусов разрешены» и «что сломается, если поменять». Страница сервиса отвечает.

3. Что обновлять — по типу изменения

Главная таблица этого документа. Сверяйся с ней перед тем, как считать задачу законченной.

Что сделал	Что обновить
Новый или изменённый эндпоинт	таблица HTTP API на странице сервиса; `docs/` библиотеки, если он там описан; Swagger-декораторы в коде (`@ApiOperation`, `@ApiResponse`)
Изменил DTO: поля, валидацию, дефолты	описание фильтров/тела рядом с таблицей эндпоинтов на странице сервиса
Новая фича-библиотека	`README.md` библиотеки; раздел Состав (фичи) и Ключевые файлы страницы сервиса
Новая библиотека в `shared`	`docs/04-shared-and-utils/shared-lib.md` (в раздел по типу: Guards / Decorators / Helpers / …)
Новый клиент в `utils`	`docs/04-shared-and-utils/utils-clients.md` + сводная таблица там же
Новый конфиг-модуль или env-переменная	`docs/04-shared-and-utils/configs.md` (полная таблица переменных) и `docs/06-operations/environment.md` (группы и наборы по сервисам)
Миграция Prisma	`docs/05-data/database-schema.md` (модели, ER, enum’ы) и строка в хронологии `docs/05-data/migrations.md`
Новый или изменённый сид	`docs/05-data/seeds.md`
Новая очередь, обменник, WebSocket-событие	`docs/06-operations/messaging.md`
Изменение bootstrap (`main.ts`), глобальных пайпов, фильтров	`docs/02-apps/README.md`
Новый сервис или изменение графа зависимостей	`docs/01-overview/architecture.md` (диаграмма) + сводная таблица в `docs/README.md`
Изменение деплоя, compose, Dockerfile	`docs/06-operations/deployment.md`
Новая команда разработки или сборки	`docs/06-operations/local-dev.md`
Новый повторяющийся паттерн в коде	`docs/01-overview/conventions.md` и, если это правило для агентов, `coding-rules.md`
Новая страница документации	строка в карте `docs/README.md` — иначе страницу никто не найдёт

Отдельно: таблицы эндпоинтов и env-переменных устаревают быстрее всего. Если правка задевает их — это не «мелочь, обновлю потом».

4. Скелет страницы сервиса

Все страницы в docs/03-services/ следуют одной структуре. Порядок разделов не меняется, лишние опускаются, доменные добавляются в середину.

# <Service> — <краткая роль>

## Назначение            обязательно — 3–5 предложений: что делает и кому нужен
## Состав (фичи)         обязательно — таблица: библиотека | контроллер / базовый путь | назначение
## HTTP API              обязательно, если есть HTTP — по разделу на фичу, таблицы
## <доменные разделы>    по необходимости — машина состояний, модель, ключевые операции
## Зависимости           обязательно — список: NestJS, Prisma, shared, configs, внешние сервисы
## Ключевые файлы        обязательно — список путей с однострочным пояснением
## Точки расширения      обязательно — как добавить сущность/статус/поле; отправная точка для новых фич
## Резюме                опционально — выжимка для тех, кто читает по диагонали

Раздел «Точки расширения» обязателен и не формален: именно с него начинают, когда приходят добавлять фичу. В нём — конкретные шаги («добавить фичу admin-api/features/<name>, навесить guard, подключить модуль в app.module.ts»), а не общие слова.

Таблица HTTP API — фиксированные колонки:

| Метод | Путь | Guard | Описание | DTO |

Пути даются без глобального префикса, с оговоркой в начале раздела, что полный URL — /api/v1/<path>. Фильтры и тела DTO описываются списком сразу под таблицей: имя поля, тип, ограничения, дефолт.

5. README библиотеки

Минимум, который должен быть у каждой библиотеки:

# <nx-имя библиотеки>

Одно-два предложения: что делает и зачем существует.

Детальный контракт: [`docs/<тема>.md`](./docs/<тема>.md).   ← если есть
Сервис деплоится на `<домен>`.                              ← если публичный

This library was generated with [Nx](https://nx.dev).

## Running unit tests

Run `nx test <nx-имя>` to execute the unit tests via [Jest](https://jestjs.io).

Заголовок README = Nx-имя библиотеки (раздел 1.2 coding-rules.md), команда в блоке про тесты — с тем же именем. Сгенерированный Nx текст оставляем, но заглушку без описания — нет: README из одного «This library was generated with Nx» считается недокументированной библиотекой.

Папка docs/ внутри библиотеки заводится, когда контракт не помещается в README: публичные эндпоинты, формат сообщений очереди, схема домена. Образец — libs/apis/providers/admin-api/features/admin-contact/.

6. Оформление

Язык — русский. Идентификаторы, пути, имена полей, коды ответов — как в коде, латиницей и в `обратных кавычках`.
Первая строка файла — # Заголовок. Docs-site (apps/docs-site/scripts/sync-docs.mjs) берёт из него title при синхронизации.
Frontmatter руками не пишется. Синхронизация подставляет его сама; файл, начинающийся с ---, она считает авторским и не трогает.
Ссылки — относительные: на соседние документы (../05-data/seeds.md), на файлы кода — относительно расположения документа (../../apps/core-api/prisma/migrations). Абсолютных URL на GitHub быть не должно.
Перечисления — таблицами, а не абзацами: эндпоинты, переменные окружения, поля, сущности.
Диаграммы — Mermaid (flowchart, erDiagram, sequenceDiagram), в блоке ```mermaid. Docs-site их рендерит. Картинок и скриншотов не держим — они устаревают молча.
Выноска > — для предупреждений и отсылок к источнику истины («точные типы см. в *.validation.ts»).
Имена файлов — kebab-case: docs/03-services/<домен>/<service>.md.

7. Стиль текста

Настоящее время, изъявительное наклонение: «Сервис отдаёт 204», «Guard проверяет, что пользователь не заблокирован».
Не пересказывать код построчно. Документация объясняет назначение, контракт и границы; детали реализации читаются в коде, на который стоит ссылка.
Не копировать в документ длинные листинги. Короткий фрагмент — когда он показывает форму вызова или структуру ответа; всё остальное — ссылкой на файл.
Фиксировать неочевидное: почему эндпоинт публичный, почему статус нельзя сменить напрямую, почему роль проверяется на логине, а не guard’ом. Именно это невозможно восстановить из кода.
Не писать «планируется», «в будущем», «TODO». Незаконченное — в docs/plans/.
Не оставлять в документации следов процесса: «я добавил», «в этом PR», «как обсуждали».

8. Чего не документируем

Приватные хелперы и внутренние детали, не входящие в публичный API библиотеки.
Очевидное из сигнатуры: «метод findAll возвращает список».
То, что уже описано в другом документе, — вместо копии ставится ссылка.
Секреты, реальные значения env, внутренние адреса и учётные данные.

9. Проверка перед сдачей

npm run build:docs        # синхронизация + сборка docs-site: ловит битые ссылки и сломанный Markdown

Плюс глазами:

новая страница добавлена в карту docs/README.md;
таблицы эндпоинтов и env совпадают с кодом (@Controller, @Get/@Post/..., *.validation.ts);
ссылки на файлы кода ведут в существующие пути;
в разделе «Ключевые файлы» нет путей, которых больше нет.

Утверждать, что документация обновлена, можно после реального запуска сборки, а не по факту правки файлов.

10. Чек-лист «функциональность готова»

Код написан по coding-rules.md.
README.md библиотеки описывает, что она делает.
Контракт фичи описан: docs/ библиотеки либо раздел HTTP API на странице сервиса.
Страница сервиса обновлена: Состав (фичи), HTTP API, Ключевые файлы, Точки расширения.
Пройдена таблица из раздела 3 — обновлено всё, чего коснулось изменение (env, миграции, очереди, деплой, команды).
Новая страница внесена в docs/README.md.
npm run build:docs проходит.