← назад к разделу

Представьте: сервис уже несколько лет в производстве, обрабатывает заказы или платежи, его поддерживают три команды — и у него нет никакого описания. Есть только код. Как разобраться в том, что он делает, и не сломать его при изменениях?

Для этого в Use Case Pattern есть Уровень 0.

Когда нет документации, а сервис уже есть

В реальных проектах часто так: сервис написали быстро, документацию отложили на потом — и «потом» не пришло. Новый разработчик тратит недели, чтобы понять, какие таблицы к чему относятся, какие статусы у заказа и откуда берётся ограничение на сумму.

Уровень 0 решает именно эту проблему: восстановить структурированное описание сервиса прямо из кода — без встреч с аналитиками, без бизнес-брифа. Читаем мигра́ции базы данных, контроллеры, тесты, конфигурацию — и собираем из этого понятную картину.

Это не про «правильную» архитектуру. Это про то, чтобы зафиксировать как есть — честно и без прикрас.

Что входит в такое описание

Описание уровня 0 охватывает то, что реально видно в коде:

  • Таблицы и поля — из миграций базы данных. Какие сущности хранятся, какие у них поля и статусы.
  • Точки входа — HTTP-эндпоинты, команды, очереди сообщений. Что сервис принимает снаружи.
  • Логика обработки — что происходит с данными: проверки, вычисления, переходы статусов.
  • Интеграции — какие внешние сервисы вызываются, какие события публикуются в брокер.

Всё, чего в коде не выражено — например, кто является инициатором операции или какое максимальное время ответа допустимо — помечается явно: not-declared. Это честный сигнал: «мы это не нашли, надо уточнить».

Такая пометка полезнее, чем пустое место: она показывает, где у описания пробелы.

Зачем это нужно

Снимок «как есть» даёт три практических преимущества.

Быстрое введение в сервис. Новый участник команды читает описание и за час понимает структуру — вместо двух недель чтения кода.

Точка отсчёта для изменений. Перед тем как что-то менять в старом сервисе, полезно зафиксировать текущее состояние. Тогда видно, от чего отталкиваемся и что именно меняем.

Основа для аудита. Когда описание есть, видно и то, чего нет: неочевидные зависимости, дублирующаяся логика, забытые эндпоинты.

Как получается спецификация

Скилл ucp-spec-tier-0 читает исходники сервиса и собирает описание в стандартном формате: корневой файл контекста плюс по одному файлу на каждый домен-юнит (агрегат).

Важные правила, которым следует скилл:

  • Только факты из кода. Скилл не предполагает и не выдумывает. Если агрегат не выражен явно — в описании будет таблица, а не «возможный агрегат».
  • Без оценки «правильно/неправильно». Цель — зафиксировать, а не критиковать. Критика будет позже, когда есть от чего отталкиваться.
  • level: 0 во frontmatter — чтобы отличать снимок от проектного описания.

Куда двигаться дальше

Уровень 0 — это стартовая точка, а не финальное состояние. Дальше команда:

  1. Читает описание и договаривается о том, что сервис реально должен делать.
  2. Заменяет not-declared на реальные бизнес-факты.
  3. Переводит описание на целевой уровень: 1 Слоёный, 2 Use Case Pattern или 3 DDD + Hexagonal.
  4. Постепенно подтягивает код к новому описанию.

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

Коротко

  • Уровень 0 — это описание сервиса, восстановленное из кода, когда документации нет.
  • В него входят таблицы, эндпоинты, логика, интеграции — всё, что видно в исходниках.
  • Чего нет в коде — помечается not-declared, а не просто пропускается.
  • Скилл ucp-spec-tier-0 собирает это описание автоматически.
  • Уровень 0 — отправная точка, от которой движутся к целевой архитектуре, а не конечная цель.

Что почитать дальше

  • Use Case Pattern — обзор методологии — уровни зрелости в общей картине.
  • Формат Use Case спецификации — единый формат для всех уровней.
  • Скиллы UCP — каталог и установка — где живёт ucp-spec-tier-0.