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

1. Назначение стандарта

Этот документ определяет обязательный формат документации проекта Konstructorium. Документация является частью Definition of Done и проверяется наравне с кодом и тестами.

2. Master-first модель документации

Единый верхнеуровневый источник:

• project-master-handbook.md

Правило:

• В master-странице фиксируются интегральные рамки (процессы, роли, риски, CI/CD, политика AI, MVP path).
• В дочерних страницах фиксируются технические детали конкретного домена/сервиса.
• Дублирование допустимо только если нет противоречий и есть ссылка на первоисточник.

3. Обязательная структура страницы сервиса

Каждая страница docs/services/*/index.md обязана содержать:

1. Назначение и границы.
2. Полный API-каталог.
3. Контракты endpoint-ов (request, response, errors, side effects).
4. Модель данных и инварианты.
5. Безопасность и права доступа.
6. Операционные требования.
7. Риски, ограничения, технический долг.
8. Диаграммы ключевых сценариев.
9. Ссылку на master-документацию.

4. Обязательная структура доменных страниц

Для разделов architecture, infrastructure, operations, governance, reference страница должна включать:

1. Цель раздела и границы применимости.
2. Формальные требования в формате:
3. Требование
4. Причина
5. Проверка
6. Артефакт
7. Известные риски и ограничения.
8. Связи с соседними разделами (явные ссылки).
9. Порядок обновления и владелец актуальности.

5. Формальные требования к контрактам

• Все пути endpoint указываются в явном виде.
• Для каждого endpoint указывается auth-политика.
• Ошибки документируются с кодом и условием возникновения.
• Любые межсервисные зависимости фиксируются явно.
• Для фильтрации/сортировки указывается серверная поддержка и ограничения.

6. Обязательные проектные блоки (верхний уровень)

В master-документации должны быть явно представлены:

1. Интерфейсы и модульные границы.
2. CI/CD контроль и release gates.
3. Политика использования нейросетей в разработке.
4. Риск-реестр разработки.
5. MVP path с критериями переходов.
6. Персональная ответственность участников и RACI.

7. Требования к диаграммам

• Диаграммы отражают фактический процесс/архитектуру, а не намерение.
• Идентификаторы узлов в mermaid без пробелов.
• Для сложных label используются кавычки.
• Диаграммы обязательны для критичных потоков: delivery и ответственность.

8. Правила сопровождения

• Изменение API без обновления docs запрещено.
• Изменение модели без обновления ER/инвариантов запрещено.
• Изменение релизного процесса без обновления operations/governance docs запрещено.
• Изменение ролей и зон ответственности без обновления charter/master docs запрещено.

9. Контроль качества документации

Минимальный контроль перед завершением задачи:

1. MkDocs сборка проходит в strict mode.
2. Нет omitted/unrecognized предупреждений.
3. Термины согласованы между master и дочерними страницами.
4. На новую страницу есть ссылка из nav.
5. Для каждого существенного изменения зафиксированы риск и проверка.