# Аудит документации Qadam

## Паспорт документа

- Статус документа: historical snapshot
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при следующем цикле аудита, security review или ревизии противоречий в документации и спеках
- Область применения: audit-слой проекта: снимки состояния, реестры расхождений и результаты ревизий
- Связанные документы:
  - [Индекс документации](../README.md)
  - [Текущее состояние](../project/current-state.md)
  - [Roadmap](../project/roadmap.md)

## Цель документа

Этот аудит фиксирует, что уже хорошо организовано в документационном слое Qadam и что ещё стоит улучшить, если смотреть на проект как на передаваемую инженерную систему, а не как на набор отдельных markdown-файлов.

Документ не заменяет [README.md](../README.md), [current-state.md](../project/current-state.md), [roadmap.md](../project/roadmap.md) или [engineering-principles.md](../governance/engineering-principles.md). Его задача — дать профессиональное заключение по качеству документации и сформировать следующий backlog именно по docs-layer.

## Статус исполнения рекомендаций на 29 марта 2026 года

На сегодня базовые рекомендации из этого аудита уже закрыты в каноническом слое:

- введён [стандарт документации](../governance/documentation-standard.md);
- добавлены [backup/restore runbook](../operations/backup-restore-runbook.md), [incident response](../operations/incident-response.md), [environment matrix](../operations/environment-matrix.md) и [post-deploy checklist](../operations/post-deploy-checklist.md);
- зафиксированы [ownership model](../governance/ownership-model.md) и [change package standard](../governance/change-package-standard.md);
- добавлены [execution checkpoints](../project/execution-checkpoints.md) и [project change log](../project/project-change-log.md);
- введён исполнимый `docs quality gate` через `pnpm check:docs`.

Сам аудит остаётся историческим снимком проблем и рекомендаций на момент 28 марта 2026 года.

## 1. Общий вывод

Документация проекта уже находится в хорошем рабочем состоянии:

- есть канонический русскоязычный слой `docs/`;
- документы разложены по разделам `project`, `architecture`, `frontend`, `operations`, `governance`, `audits`, `product`;
- roadmap-портал читает живые markdown-файлы и поддерживает внутреннюю перелинковку;
- зафиксированы runbook, current state, roadmap, frontend handoff и инженерные правила;
- исторические планы уже отделены в архивный слой.

Главный следующий шаг уже не в “навести порядок в дереве файлов”, а в повышении зрелости документационного процесса:

1. унифицировать lifecycle документов;
2. закрыть пробелы по эксплуатации и handover;
3. сократить избыточную когнитивную нагрузку в `docs/Agents`;
4. убрать остаточные нарушения правила “канонический слой на русском языке”;
5. ввести автоматический quality gate для документации.

## 2. Что уже сделано хорошо

### 2.1. Появился понятный источник истины

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

- [README.md](../README.md) — индекс;
- [current-state.md](../project/current-state.md) — фактическое состояние;
- [requirements.md](../project/requirements.md) — требования;
- [roadmap.md](../project/roadmap.md) — план;
- [deployment-runbook.md](../operations/deployment-runbook.md) — эксплуатация;
- [api-routes.md](../architecture/api-routes.md) + OpenAPI — API-контракт;
- [frontend-handoff.md](../frontend/frontend-handoff.md) и [frontend-change-log.md](../frontend/frontend-change-log.md) — отдельный handoff для внешней frontend-команды.

### 2.2. Документация уже привязана к реальному runtime

Это важнее любой “красоты текста”. В документах явно отражены:

- split-репозитории `qadam-core` и `qadam-web`;
- отдельный сервис `qadam-roadmap`;
- host-based production через `systemd` и `nginx`;
- OpenAPI runtime и contract workflow;
- отдельная операционная модель для frontend-команды.

То есть проект уже вышел из стадии “много красивых текстов, мало фактов”.

### 2.3. Архив и канонический слой отделены

Папка `plans/` выведена в архивный контур, а processed plans больше не притворяются каноническими решениями. Это хорошая база для дальнейшей передачи проекта другой команде.

## 3. Главные проблемы, которые ещё стоит закрыть

## P0 — high priority

### P0-1. Нет единого стандарта metadata/lifecycle у документов

Сейчас часть документов имеет явную отметку актуальности, а часть нет. Например:

- есть дата в [current-state.md](../project/current-state.md), [frontend-handoff.md](../frontend/frontend-handoff.md), [frontend-change-log.md](../frontend/frontend-change-log.md), [implementation.md](../../specs/qadam-platform/implementation.md);
- нет явной даты ревизии в [README.md](../README.md), [requirements.md](../project/requirements.md), [deployment-runbook.md](../operations/deployment-runbook.md), [api-routes.md](../architecture/api-routes.md), [engineering-principles.md](../governance/engineering-principles.md), [security-review.md](./security-review.md).

Проблема не в косметике, а в том, что другой команде сложно понять:

- когда документ последний раз проверялся;
- кто его должен поддерживать;
- является ли он живым operational source of truth или историческим снимком.

Что улучшить:

- ввести единый короткий header для всех канонических документов:
  - `Статус документа`
  - `Актуально на`
  - `Владелец`
  - `Когда пересматривать`
  - `Связанные документы`
- закрепить этот шаблон в отдельном `documentation-standard.md`.

### P0-2. Есть документационные пробелы по эксплуатации и handover

В [deployment-runbook.md](../operations/deployment-runbook.md) уже прямо зафиксировано, что ещё нужны:

- резервное копирование PostgreSQL;
- отдельный runbook по восстановлению;
- monitoring;
- автоматизированный post-deploy smoke.

Но самих канонических документов пока нет.

Это означает, что документация уже описывает текущий runtime, но ещё не закрывает полный transferability-контур production.

Что улучшить:

- добавить [operations/backup-restore-runbook.md];
- добавить [operations/incident-response.md];
- добавить [operations/environment-matrix.md] или аналогичный документ по env/secrets/access boundaries;
- добавить [operations/post-deploy-checklist.md].

### P0-3. `docs/Agents` остаётся слишком тяжёлым и не до конца нормализованным

Сейчас `docs/Agents` полезен как внутренняя инженерная база, но с точки зрения передачи другой команде он перегружен:

- [knowledge-base.md](../Agents/knowledge-base.md) очень большой и смешивает продуктовую модель, старые доменные описания и нормализацию конфликтов;
- [product-roadmap.md](../Agents/product-roadmap.md) очень большой и фактически является второй плоскостью roadmap/backlog;
- часть `specs` в `docs/Agents/specs` имеет объём 500-1300 строк и остаётся тяжёлой для навигации и сопровождения.

Проблема здесь не в объёме как таковом, а в том, что чтение этих файлов становится “экспедицией”, а не рабочей инженерной навигацией.

Что улучшить:

- разделить `docs/Agents` на более ясные классы:
  - `guides/`
  - `rules/`
  - `active-specs/`
  - `reference/`
  - `archive/`, если часть больших spec уже не активна;
- для каждой большой spec добавить сверху короткий `TL;DR`:
  - цель;
  - статус;
  - что уже реализовано;
  - что остаётся;
  - какой документ сейчас source of truth по API.

### P0-4. Канонический слой всё ещё не полностью выдержан на русском языке

Верхний слой `docs/` уже в основном русифицирован, но внутри `docs/Agents` и части rule/reference-файлов остаются смешанные слои:

- английские заголовки и frontmatter;
- английские описания правил;
- большие англоязычные блоки в [knowledge-base.md](../Agents/knowledge-base.md) и [product-roadmap.md](../Agents/product-roadmap.md);
- англоязычные title/impact-блоки в некоторых rule-документах, например [reference-file-locations.md](../Agents/rules/reference-file-locations.md).

Это прямо конфликтует с принципом из [engineering-principles.md](../governance/engineering-principles.md), где канонический слой должен быть на русском языке.

Что улучшить:

- довести `docs/Agents` до той же языковой дисциплины, что и верхний `docs/`;
- оставить английский только там, где это действительно имя технологии, API или код.

## P1 — medium priority

### P1-1. Не хватает отдельного глоссария терминов и canonical vocabulary

Проблема терминологии уже видна в [qadam-contradictions-registry.md](./qadam-contradictions-registry.md): buyer/parent/student, active/published, pending/new/created, approved/active и т.д.

Сейчас терминологическая нормализация размазана по нескольким документам:

- [knowledge-base.md](../Agents/knowledge-base.md)
- [qadam-contradictions-registry.md](./qadam-contradictions-registry.md)
- [api-routes.md](../architecture/api-routes.md)
- [requirements-api-registration.md](../product/requirements-api-registration.md)

Лучше вынести это в отдельный документ:

- `project/glossary.md`

Что в нём должно быть:

- доменные сущности;
- канонические названия ролей;
- канонические статусы;
- deprecated термины и чем их заменять.

### P1-2. Нет отдельного документа по error catalog и API-поведенческим соглашениям

[api-routes.md](../architecture/api-routes.md) хорошо описывает маршруты, но не является полноценным guide по API behavior. Сейчас знания об ошибках и контрактах частично размазаны:

- в OpenAPI;
- в change-log для frontend;
- в handoff;
- в отдельных feature-docs.

Для внешней frontend-команды и будущих интеграторов полезно иметь отдельный документ:

- `architecture/api-conventions.md`
- или `architecture/error-catalog.md`

Туда стоит вынести:

- коды ошибок;
- общий envelope/response shape;
- поведение cookies и auth;
- правила backward compatibility и deprecated endpoint aliases;
- правила pagination/filtering/search params;
- rate limits, если они становятся продуктово значимыми.

### P1-3. Нет отдельного документа по ownership и зонам ответственности

[frontend-handoff.md](../frontend/frontend-handoff.md) хорошо фиксирует границу `qadam-core` и `qadam-web`, но на уровне всей платформы нет короткой RACI/ownership-карты:

- кто владеет production runtime;
- кто владеет roadmap-порталом;
- кто владеет OpenAPI artifact;
- кто обновляет канонические docs;
- кто принимает решение по breaking changes.

Это не обязательно делать как “корпоративный bureaucracy-doc”, но короткий документ уровня `governance/ownership-model.md` сильно облегчит handover.

### P1-4. Нет канонического документа по release/change-package process

Части процесса уже описаны в:

- [engineering-principles.md](../governance/engineering-principles.md)
- [deployment-runbook.md](../operations/deployment-runbook.md)
- [frontend-change-log.md](../frontend/frontend-change-log.md)
- [docs/Agents/commands.md](../Agents/commands.md)

Но это всё ещё не один компактный документ “как выглядит change package от идеи до production”.

Что улучшить:

- добавить `governance/change-package-standard.md`;
- описать в нём:
  - состав change package;
  - обязательные docs updates;
  - release note;
  - frontend changelog update;
  - smoke checks;
  - rollback note.

## P2 — lower priority, but valuable

### P2-1. Нужен docs quality gate в CI

Сейчас link integrity уже можно проверять автоматически, и это особенно важно после того, как roadmap-портал стал зависеть от корректной перелинковки markdown.

Рекомендуемый минимум:

- проверка битых относительных markdown-ссылок;
- проверка, что все документы в `docs/` имеют header metadata;
- проверка, что в каноническом слое не осталось ссылок на legacy пути вроде `docs/*.md` старой структуры, если они не являются частью исторических снимков;
- проверка, что новые документы попали в [README.md](../README.md), если они канонические.

### P2-2. Нужен более явный status-banner для historical snapshot документов

Часть audit/legacy документов всё ещё визуально похожа на “живые документы”, хотя по смыслу это снимки или ревью конкретного момента времени. Например:

- [security-review.md](./security-review.md)
- [plans-audit-2026-03-28.md](./plans-audit-2026-03-28.md)
- [qadam-contradictions-registry.md](./qadam-contradictions-registry.md)

Что улучшить:

- ввести явные баннеры статуса:
  - `historical snapshot`
  - `living document`
  - `reference only`
  - `superseded`

### P2-3. Нужно сильнее разделить “что читать новой команде сначала” и “глубокий reference”

Сейчас это частично решено через [README.md](../README.md), но можно сделать ещё лучше:

- отдельный `project/start-here.md` для новой команды;
- отдельный короткий `architecture/system-overview.md`;
- отдельный `operations/start-here-prod.md` для инженера, который впервые заходит на сервер.

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

## 4. Рекомендуемый backlog по документации

## Фаза 1 — закрыть базовый процесс

1. Ввести единый metadata/header standard для канонических документов.
2. Добавить docs quality gate на проверку относительных ссылок и обязательных header-полей.
3. Добавить `operations/backup-restore-runbook.md`.
4. Добавить `operations/incident-response.md`.
5. Добавить `operations/environment-matrix.md`.

## Фаза 2 — снизить когнитивную нагрузку

1. Нормализовать и частично разрезать `docs/Agents`.
2. Добавить `project/glossary.md`.
3. Добавить `governance/change-package-standard.md`.
4. Добавить `governance/ownership-model.md`.
5. Для больших spec из `docs/Agents/specs` добавить краткие executive-summary блоки.

## Фаза 3 — усилить интеграционный слой

1. Добавить `architecture/api-conventions.md` или `architecture/error-catalog.md`.
2. Зафиксировать правила deprecation/backward compatibility.
3. Добавить machine-checkable docs QA в CI.

## 5. Практический вывод

Документация Qadam уже находится на уровне выше среднего для инженерного проекта в активной разработке. Основной хаос уже снят:

- есть канонический слой;
- есть roadmap;
- есть current state;
- есть runbook;
- есть frontend handoff;
- есть live roadmap-портал;
- есть архив historical plans.

Следующий уровень зрелости теперь не в создании ещё большего количества markdown-файлов, а в трёх вещах:

1. lifecycle и ownership документов;
2. эксплуатационные runbook-пробелы;
3. сокращение перегруженности `docs/Agents` и добивание русскоязычного канонического слоя до конца.

Именно эти улучшения дадут проекту максимальный прирост передаваемости другой команде.