Стандарт документации

Формальные требования к документации проекта. Цель стандарта — сделать документы быстро читаемыми, не смешивать текущее состояние репозитория с целевой архитектурой и не создавать ложного ощущения, что несуществующие сервисы уже можно запускать.

Что должно быть понятно с первых строк

Любой новый документ должен сразу ответить на три вопроса:

1. Что это за документ: обзор, target design, описание текущей реализации, процесс, runbook.
2. Для кого он написан: новый участник, разработчик, архитектор, оператор.
3. Куда идти дальше после прочтения.

Если читатель не может понять это по первым абзацам, документ написан плохо.

Не смешивайте current state и target design

Это обязательное правило для всего корпуса документации.

• Если документ описывает целевую систему, скажите об этом в первых строках.
• Для target-документов явно указывайте статус реализации: есть ли уже выделенный код, какой код существует сейчас, где проходит граница между текущим scaffold и будущей реализацией.
• Если документ описывает то, что уже есть в репозитории, не используйте будущие сервисы, процессы или директории как будто они уже существуют.
• Если в одной теме нужно описать и текущее состояние, и целевое, разделите это на явные секции Текущее состояние и Целевое состояние или на два отдельных документа.
• Если документ ссылается на ещё не реализованные модули, он обязан вести на roadmap, architecture или service docs, а не создавать впечатление “это уже лежит в коде”.

Три слоя

1. Business (10-business/) — что и почему. Доменная модель, правила, сценарии. Без технических деталей.
2. Технический контекст (20-architecture/) — как. ADR, схемы, паттерны.
3. Сервисы (30-services/) — README на сервисах и коннекторах.

Операции (40-operations/) и процессы (50-processes/) — кросс-срезы.

Правило слоёв:

• Слой выше не зависит от слоя ниже по содержимому, только по ссылкам.
• Слой ниже может ссылаться на слой выше за определениями.

Как выбрать место для нового документа

Если документ отвечает на вопрос	Куда его класть
Зачем проект нужен, куда идёт, что ещё не решено	00-overview/
Какие сущности, правила и термины есть в домене	10-business/
Как должна быть устроена система и почему принято решение	20-architecture/
За что отвечает конкретный сервис или модуль	30-services/
Как запускать, наблюдать и чинить окружение	40-operations/
Как менять проект, релизы, документацию и процессы	50-processes/

Если документ не укладывается ни в один из пунктов, сначала уточните его назначение, а потом создавайте файл.

AGENTS.md — обязателен на каждом уровне

В каждой директории docs/ и в каждой папке сервиса — AGENTS.md.

Секции в строгом порядке:

1. Назначение уровня (1-2 предложения).
2. Содержание (дерево или список файлов с 1-строчным описанием).
3. Ключевые концепции уровня — новые термины.
4. Когда смотреть сюда.
5. Когда НЕ смотреть сюда (с указаниями куда).
6. Связано (ссылки на соседние / связанные AGENTS.md).
7. Соглашения (опционально, локальные соглашения).

Максимум 300 строк. Императивный тон. Без маркетинга и воды.

README.md на сервисах

На каждом сервисе / модуле — README.md по шаблону ../30-services/TEMPLATE-service-README.md.

Обязательные секции:

1. Назначение.
2. Статус документа.
3. Scope (что входит, что НЕ входит).
4. Публичный контракт (incoming / outgoing).
5. Внутренняя архитектура.
6. Зависимости.
7. Хранилище.
8. Конфигурация.
9. Локальный запуск.
10. Тестирование.
11. Наблюдаемость.
12. Открытые вопросы / TODO.
13. Связанные документы.

Сервисный README должен в первом экране объяснять:

• это описание текущего сервиса или target service boundary;
• реализован ли сервис как отдельный runtime/module в репозитории;
• если нет, какой код существует сейчас вместо него;
• какие документы читать после него: схемы, ADR, runbooks, смежные сервисы.

Минимальный формат секции Статус документа

В сервисных README это обязательный мини-чеклист:

• Тип знания: current service или target service boundary.
• Статус реализации: есть выделенный код / отдельного кода пока нет / есть только scaffold.
• Текущее место кода: точные пути в репозитории или явная пометка, что путь пока не создан.
• Что читать дальше: 2-4 ссылки на схемы, ADR, соседние сервисы или процессы.

Wiki-архитектура и web-публикация

Документация организована по wiki-принципу:

• у каждого уровня есть индекс (AGENTS.md, родительский README, дочерние документы);
• навигация идёт от общего к частному;
• новый документ обязан быть доступен из родительского уровня ссылкой и попадать в web-навигацию.

Нельзя публиковать в навигацию AI-ориентированный индекс, если для этого же уровня нет человеческой входной страницы. В пользовательской web-навигации показываем страницы для человека, а не служебные AGENTS-документы.

Публикация обязательна:

• canonical source — файлы в docs/docs/;
• web-сайт собирается через Quartz (deploy/docker/resources/docs-quartz/);
• публикация идёт через GitLab Pages из main;
• сайт показывает текущую документацию, а не отдельные versioned snapshots.

Ubiquitous Language

Все термины — в ../GLOSSARY.md и ../10-business/ubiquitous-language.md.

• Термин определяется один раз.
• Используется в документации и коде в единой форме.
• Запрещённые термины помечаются явно.

Каноничность документов

• На одну тему существует один актуальный документ.
• Файлы вида *-v2.md, *-final.md, *-delta.md, copy.md запрещены.
• История решений фиксируется через ADR и историю изменений репозитория, а не через параллельные версии документов.
• В канонических документах не должно быть секций вида “что изменилось относительно прошлой версии” или ссылок на “предыдущую редакцию”.
• Если подход изменился, обновляется текущий документ, а при необходимости добавляется ADR с контекстом решения.

Требования к понятности

Это обязательные требования, а не пожелания:

• В начале документа должен быть короткий абзац “что это и когда читать”.
• В начале сервисного README должен быть явный статус: current vs target, плюс текущий путь к коду.
• В длинном документе должна быть секция с обзором структуры или маршрутом чтения.
• Ссылки должны помогать следующему шагу, а не просто перечислять всё подряд.
• Термины из глоссария используются последовательно; синонимы без явного объяснения запрещены.
• Путь в репозитории, API endpoint или имя сервиса указываются только если они реально существуют или документ явно помечен как target design.

Чеклист перед merge

Перед merge автор документа обязан проверить:

1. По первым абзацам понятно, current это или target.
2. Указано, где код находится сейчас, либо явно сказано, что нужного пути ещё нет.
3. Родительский индекс (README.md, index.md или AGENTS.md) ссылается на новый документ.
4. Внутренние ссылки ведут к следующему шагу, а не просто перечисляют соседние файлы.
5. README сервисов и AGENTS.md соответствуют обязательному порядку секций.
6. Документ не создаёт впечатление, что несуществующий сервис уже можно запустить локально.

ADR

См. adr-process.md.

Схемы

Все схемы (PG, CH, ES, Kafka events, HTTP APIs) — в ../20-architecture/schemas/.

• Любое изменение схемы — через PR.
• Breaking change — через ADR и план миграции.
• Код не “знает” полей до их появления в схеме.

Процесс

• Любое изменение продукта / контракта / схемы / deploy / CI/CD / процесса: обновить документацию в том же MR.
• Новая фича: обновить документ уровня 1 или 2 или README сервиса в том же PR, что и код.
• Новый сервис: новая папка в 30-services/, AGENTS.md + README.md, обновлён родительский AGENTS.md.
• Новый поставщик: следовать adding-new-supplier.md.
• Новая таблица / индекс / топик: обновление в 20-architecture/schemas/.
• Нетривиальное решение: ADR в 20-architecture/adr/.
• Изменение пользовательского поведения / релизного контракта: обновить CHANGELOG.md, а при релизе — VERSION.

CI-проверки

1. Markdown lint.
2. Quartz static build проходит без ошибок и рендерит docs site.
3. Внутренние ссылки валидны.
4. В каждой папке docs/ есть AGENTS.md.
5. В каждом сервисе есть README.md + AGENTS.md.
6. ADR соответствует шаблону.
7. Изменения вне docs/ не мёржатся без docs-delta, кроме явно помеченных инфраструктурных исключений.

Ревью

• PR, меняющий документацию, требует минимум 1 approve.
• Значительные изменения (архитектура, модель) — 2 approve’а, включая техлида.
• AI-помощь в написании документации допустима; ответственность за содержание — на авторе PR.