ERP Platform Docs

Workflow

время чтения ~4 мин.

Workflow разработки с Claude Code

Обзор

flowchart TD
    BIZ["Коллега (бизнес)"] -->|"описывает фичу"| BR["07-Tasks/Business Requirements/"]
    BR --> SPEC["08-Specs/{Продукт}/"]
    SPEC --> BACKEND["03-Services/ — бэкенд-контракты"]
    SPEC --> FRONTEND["09-Frontend Specs/ — экраны + user flow"]
    BACKEND --> DECOMP["07-Tasks/Decomposition/"]
    FRONTEND --> DECOMP
    DECOMP --> VERIFY["/verify — проверка консистентности"]
    VERIFY --> IMPL["Реализация в репозиториях"]

    style BIZ fill:#1a1a2e,stroke:#e94560,color:#fff
    style BR fill:#16213e,stroke:#e94560,color:#fff
    style SPEC fill:#0f3460,stroke:#e94560,color:#fff
    style BACKEND fill:#1a1a2e,stroke:#533483,color:#fff
    style FRONTEND fill:#1a1a2e,stroke:#533483,color:#fff
    style DECOMP fill:#16213e,stroke:#e94560,color:#fff
    style IMPL fill:#2d6a4f,stroke:#40916c,color:#fff
    style VERIFY fill:#b5179e,stroke:#f72585,color:#fff

Участники

КтоРольГде работает
КоллегаБизнес-требования07-Tasks/Business Requirements/
Алексей + ClaudeСистемный анализ + разработка08-Specs/, 03-Services/, 09-Frontend Specs/, 07-Tasks/Decomposition/, репозитории

Цикл разработки

Шаг 1: Входящее требование (коллега)

Коллега кладёт файл в 07-Tasks/Business Requirements/ с описанием фичи своими словами. Формат свободный.

Шаг 2: Бизнес-спека (Алексей + Claude)

Читаем требование → создаём бизнес-спеку в 08-Specs/{Продукт}/.

Продукты (верхний уровень 08-Specs):

  • Админка Франшизы/ — бэк-офис владельца бренда
  • Админка Франчайзи/ — бэк-офис партнёра
  • POS/ — POS-терминал

Что входит:

  • Сущности и их поля (таблицы с типами, обязательностью)
  • Бизнес-правила (валидации, ограничения, side-эффекты)
  • Ролевая матрица (кто что может делать)
  • Связи с другими модулями

Что НЕ входит:

  • REST-эндпоинты, JSON-структуры
  • ER-диаграммы, SQL-таблицы
  • Kafka-события и payload
  • Описания экранов и UI

Шаг 3: Технические контракты + фронтенд-спеки (параллельно)

Из бизнес-спеки создаются одновременно:

3a. Бэкенд-контракты в 03-Services/{ServiceName}/:

  • API.md — REST-эндпоинты с полной спецификацией
  • Data Model.md — ER-диаграмма (Mermaid), таблицы БД
  • Events.md — Kafka-события с payload
  • Overview.md — зависимости, конфигурация

3b. Фронтенд-спеки в 09-Frontend Specs/{Продукт}/:

  • По файлу на экран или flow
  • Что видит пользователь, какие данные, действия, переходы, состояния

Шаг 4: Декомпозиция задач (Алексей + Claude)

Создаём папку в 07-Tasks/Decomposition/{номер BR}/:

07-Tasks/Decomposition/1.1 Юридические лица/
  Overview.md              ← статус, прогресс, ссылки на BR и спеки
  User Service.md          ← что делать в бэкенде
  Store Service.md         ← что делать (если затронут)
  Admin Franchise.md       ← что делать во фронте

Каждый файл — конкретные задачи для реализации со ссылками на контракты.

Шаг 5: Проверка консистентности (перед реализацией)

Запускаем /verify — скилл проверяет всю цепочку до начала написания кода:

  1. BR существует и взят в работу
  2. Бизнес-спека покрывает все пункты BR
  3. Бэкенд-контракты существуют для затронутых сервисов
  4. Фронтенд-спеки существуют для затронутых продуктов
  5. Декомпозиция создана и задачи размечены
  6. Нет противоречий между слоями (поля, роли, эндпоинты)

Реализация не начинается пока /verify не пройдёт без замечаний.

Шаг 6: Реализация (в репозиториях)

Разработчик переходит в репозиторий сервиса/фронта:

cd ../erp-user-service && claude

Claude в репозитории:

  1. Читает свой файл из 07-Tasks/Decomposition/
  2. Читает контракты из 03-Services/ или 09-Frontend Specs/
  3. Реализует
  4. Коммитит

Блокеры (02-ADR)

Если на любом шаге цикла обнаруживается блокер (зависимость, которая не решена, открытый вопрос от бизнеса), создаётся папка в 02-ADR/:

02-ADR/ADR-NNN Название блокера/
  Проблема.md     ← контекст: что блокирует, почему, что ждём
  Решение.md      ← что решили (заполняется когда блокер снят)

Обычные архитектурные решения (не блокеры) остаются одним файлом: 02-ADR/ADR-NNN Название.md.

Блокер vs решение

  • Блокер = BR не может двигаться дальше (нет данных, нет ответа от бизнеса, циклическая зависимость) → папка
  • Решение = выбрали технологию/подход (Resend, локальный JWT) → файл

Баги (07-Tasks/Bugs)

Если найден баг:

  1. Создать папку 07-Tasks/Bugs/BUG-NNN Название/ (через /add-bug)
  2. Баг.md — описание, шаги воспроизведения, affected BR
  3. Декомпозиция.md — задачи по сервисам + правки спек если нужно
  4. Исправить код
  5. Если баг выявил ошибку в спеке — обновить спеку с пометкой *(Исправлено в BUG-NNN)*
  6. Отметить status: fixed

Разделение ответственности

07-Tasks/BR/         08-Specs/              03-Services/         09-Frontend Specs/
(бизнес, raw)        (бизнес, structured)   (бэкенд, техника)    (фронт, экраны)
────────────         ──────────────────     ─────────────────    ──────────────────
"нужно ЮЛ"     →    Поля, правила,    →    POST /api/v1/...     Список ЮЛ: колонки,
                     роли, flow             { JSON }             фильтры, действия
                                            erDiagram            Карточка ЮЛ: поля
                                            Kafka events         Импорт: шаги

Правила для Claude в репозитории сервиса

Инструкции для .claude/CLAUDE.md каждого сервиса

  1. Перед работой — читай свой файл из 07-Tasks/Decomposition/ и контракты из 03-Services/
  2. Изоляция — работай только в своём репозитории
  3. Два коммита — один в репозитории (код), один в obsidian_erp (контракты если менялись)
  4. Документация — если менялся API, модель, события — обнови 03-Services/

Формат коммитов

В репозитории сервиса

feat(user): add CRUD for legal entities

BR-1.1: legal entity management with soft delete and role-based access

Co-Authored-By: Claude <noreply@anthropic.com>

В obsidian_erp

docs: update contracts after BR-1.1 implementation

Co-Authored-By: Claude <noreply@anthropic.com>

Ссылки

Вид графа

Обратные ссылки