Qadam Roadmap
← Назад к библиотеке
проектdocs/audits/documentation-audit-2026-03-28.md

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

Обновлён 1 апр. 2026 г., 12:41 · 0 комментариев

ИсходникСкачать

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

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

  • Статус документа: historical snapshot
  • Актуально на: 28 марта 2026 года
  • Владелец: backend/platform-команда
  • Пересмотр: при следующем цикле аудита, security review или ревизии противоречий в документации и спеках
  • Область применения: audit-слой проекта: снимки состояния, реестры расхождений и результаты ревизий
  • Связанные документы:

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

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

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

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

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

Сам аудит остаётся историческим снимком проблем и рекомендаций на момент 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. Появился понятный источник истины

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

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 у документов

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

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

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

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

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

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

В 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 очень большой и смешивает продуктовую модель, старые доменные описания и нормализацию конфликтов;
  • 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 и product-roadmap.md;
  • англоязычные title/impact-блоки в некоторых rule-документах, например reference-file-locations.md.

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

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

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

P1 — medium priority

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

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

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

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

  • project/glossary.md

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

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

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

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 хорошо фиксирует границу 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

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

Но это всё ещё не один компактный документ “как выглядит 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, если они канонические.

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

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

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

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

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

Сейчас это частично решено через 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 и добивание русскоязычного канонического слоя до конца.

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