СТАНДАРТ: Fractal Architecture

ПРОЕКТ ≈ МОДУЛЬ ≈ БЛОК ≈ ПОКОЛЕНИЕ

Одна и та же структура на всех уровнях:
  CLAUDE.md + CACHE.yaml + planning/ + dev/ + testing/ + deploy/

ПРОЕКТ
  ├── dev/
      ├── МОДУЛЬ (микро-проект)
          ├── dev/
              ├── БЛОК (микро²-проект)
                  ├── dev/
                      └── ПОКОЛЕНИЕ (микро³-проект)

микро-проект/
├── CLAUDE.md          ← описание, метаданные, интерфейс
├── CACHE.yaml         ← входные данные, зависимости
│
├── planning/          ← планирование
│   ├── requirements.md   ← требования
│   ├── blocks.md         ← декомпозиция на под-блоки
│   └── criteria.md       ← критерии готовности
│
├── dev/               ← разработка
│   ├── [под-блоки]       ← рекурсия (микро-проекты)
│   └── [код]             ← или финальный код (атом)
│
├── testing/           ← тесты
│   ├── unit/
│   ├── integration/
│   └── criteria.md       ← результаты тестов
│
└── deploy/            ← результат (финальная сборка)
    ├── dist/             ← собранный продукт
    └── README.md         ← как использовать

блок/
├── CLAUDE.md
├── CACHE.yaml
├── planning/
│   ├── requirements.md
│   ├── blocks.md      ← список функций/классов
│   └── criteria.md    ← coverage >80%, 0 bugs
│
├── dev/
│   ├── функция_1/     ← под-блок (если сложная)
│   ├── функция_2/
│   └── utils.py       ← вспомогательный код
│
├── testing/
│   ├── unit/
│   │   ├── test_функция_1.py
│   │   └── test_функция_2.py
│   └── integration/
│
└── deploy/
    └── module.py      ← финальный модуль

блок/
├── CLAUDE.md
├── CACHE.yaml
├── planning/
│   ├── requirements.md    ← что документировать
│   ├── blocks.md          ← разделы документации
│   └── criteria.md        ← полнота, ясность
│
├── dev/
│   ├── раздел_1.md
│   ├── раздел_2.md
│   └── диаграммы/
│
├── testing/
│   └── review.md          ← ревью документации
│
└── deploy/
    └── final.md           ← финальная документация

блок/
├── CLAUDE.md
├── CACHE.yaml
├── planning/
│   ├── requirements.md    ← что автоматизировать
│   ├── blocks.md          ← шаги скрипта
│   └── criteria.md        ← надёжность, откат
│
├── dev/
│   ├── validation/
│   ├── backup/
│   └── cleanup/
│
├── testing/
│   ├── dry-run.sh         ← тест без изменений
│   └── rollback.sh        ← тест отката
│
└── deploy/
    └── script.sh          ← финальный скрипт

1. ПРОЕКТ
   ├── Определить стадии (planning, dev, testing, deploy)
   ├── Для dev/ → определить модули/компоненты
   │
2. МОДУЛЬ (микро-проект)
   ├── CLAUDE.md — описать модуль
   ├── CACHE.yaml — входные данные
   ├── planning/requirements.md — требования
   ├── planning/blocks.md — декомпозировать на БЛОКИ
   ├── planning/criteria.md — критерии готовности
   │
3. БЛОК (микро²-проект)
   ├── CLAUDE.md — описать блок
   ├── CACHE.yaml — входные данные
   ├── planning/requirements.md — требования
   ├── planning/blocks.md — декомпозировать на ПОКОЛЕНИЯ
   ├── planning/criteria.md — критерии готовности
   │
4. ПОКОЛЕНИЕ (микро³-проект, АТОМ)
   ├── CLAUDE.md — описать поколение
   ├── CACHE.yaml — входные данные
   ├── planning/requirements.md — требования
   ├── planning/criteria.md — критерии готовности
   └── dev/ — КОД (атомарный уровень, влезает в контекст)

# CLAUDE.md — интерфейс уровня
block:
  name: "..."
  type: CODE|DOCS|OPS
  inputs: [...]     ← что требует
  outputs: [...]    ← что производит

# CACHE.yaml — входные данные
dependencies: [...]
inputs: {...}
resolved: {...}

# planning/requirements.md — требования
- Функциональные требования
- Нефункциональные требования
- Ограничения

# planning/blocks.md — декомпозиция
Список под-блоков с кратким описанием

# planning/criteria.md — критерии
- Критерии готовности
- Метрики качества
- Условия приёмки

НАЧАТЬ С САМОГО ГЛУБОКОГО УРОВНЯ (атом):

Уровень N (атомарный):
  1. claude-loader compile CLAUDE.md → загрузить контекст
  2. dev/ → реализовать код
  3. testing/ → написать и запустить тесты
  4. Если тесты FAILED → вернуться к dev/
  5. Если тесты PASSED → deploy/ собрать результат
  6. ПРОДУКТ УРОВНЯ N ГОТОВ

Уровень N-1 (использует результаты N):
  1. CACHE.yaml → resolved += deploy/ уровня N
  2. claude-loader compile CLAUDE.md → загрузить контекст
  3. dev/ → интегрировать под-блоки
  4. testing/ → тесты интеграции
  5. Если тесты FAILED → проверить под-блоки или интеграцию
  6. Если тесты PASSED → deploy/ собрать результат
  7. ПРОДУКТ УРОВНЯ N-1 ГОТОВ

Продолжать до КОРНЯ (проект):
  - Каждый уровень использует deploy/ под-уровней
  - Каждый уровень тестируется независимо
  - Результат собирается в deploy/

ДЛЯ КАЖДОГО УРОВНЯ (снизу вверх):

1. СБОРКА deploy/
   - Собрать результаты под-уровней
   - Создать финальный продукт уровня
   - Документировать deploy/README.md

2. ТЕСТИРОВАНИЕ
   - Запустить testing/unit/
   - Запустить testing/integration/
   - Проверить criteria.md

3. ВАЛИДАЦИЯ
   - Все тесты PASSED?
   - Критерии выполнены?
   - Покрытие достаточное?

4. ФИКСАЦИЯ
   - Обновить CLAUDE.md (status: completed)
   - Записать метрики в testing/criteria.md
   - Зафиксировать версию в deploy/

5. ПОДЪЁМ НА УРОВЕНЬ ВЫШЕ
   - deploy/ текущего → CACHE.yaml родителя
   - Повторить процесс для родителя

# planning/blocks.md
Модули:
- library/connectors/api/ozon — API клиент Ozon
- dev/catalog — Каталог товаров
- dev/import — Импорт BAZON

# Декомпозируем в dev/

library/connectors/api/ozon/
├── CLAUDE.md
│   block:
│     name: ozon
│     inputs: [API_KEY, API_URL]
│     outputs: [OrdersClient, ProductsClient, StocksClient]
│
├── CACHE.yaml
│   resolved:
│     api_key: "..."
│     api_url: "https://api-seller.ozon.ru"
│
├── planning/
│   ├── requirements.md
│   │   - Поддержка FBO/FBS заказов
│   │   - Управление товарами
│   │   - Синхронизация остатков
│   │
│   ├── blocks.md
│   │   Блоки:
│   │   - orders — работа с заказами
│   │   - products — управление товарами
│   │   - stocks — синхронизация остатков
│   │
│   └── criteria.md
│       - API compatibility: 100%
│       - Test coverage: >85%
│       - Rate limits: respected
│
├── dev/
│   ├── orders/    ← БЛОК (декомпозируем дальше)
│   ├── products/
│   └── stocks/
│
├── testing/
│   ├── integration/
│   └── criteria.md (результаты)
│
└── deploy/
    └── __init__.py
        # from .orders.deploy.orders import OrdersClient
        # from .products.deploy.products import ProductsClient
        # from .stocks.deploy.stocks import StocksClient

dev/orders/
├── CLAUDE.md
│   block:
│     name: orders
│     inputs: [api_client]
│     outputs: [OrdersClient]
│     current_version: v2
│
├── CACHE.yaml
│   resolved:
│     api_client: {$ref: ../../CACHE.yaml#api_client}
│
├── planning/
│   ├── requirements.md
│   │   - Список заказов FBO/FBS
│   │   - Получение деталей заказа
│   │   - Отмена заказа
│   │
│   ├── blocks.md
│   │   Поколения:
│   │   - v1 — базовый функционал
│   │   - v2 — пагинация + rate limits
│   │
│   └── criteria.md
│       - Unit tests: 10+
│       - Integration tests: 3+
│       - Rate limit handling: YES
│
├── dev/
│   ├── v1/        ← ПОКОЛЕНИЕ (атом, декомпозируем)
│   └── v2/        ← ПОКОЛЕНИЕ (атом, реализуем)
│
├── testing/
│   ├── unit/
│   │   ├── test_list.py
│   │   ├── test_get.py
│   │   └── test_cancel.py
│   ├── integration/
│   │   └── test_real_api.py
│   └── criteria.md (✅ 12 unit, ✅ 3 integration)
│
└── deploy/
    └── orders.py
        # class OrdersClient:
        #     def list_orders(...)
        #     def get_order(...)
        #     def cancel_order(...)

dev/v2/
├── CLAUDE.md
│   generation:
│     version: v2
│     description: "Пагинация + rate limits"
│     size: 280 строк
│     inputs: [api_client]
│     outputs: [OrdersClient class]
│
├── CACHE.yaml
│   resolved:
│     api_client: {$ref: ../../../CACHE.yaml#api_client}
│
├── planning/
│   ├── requirements.md
│   │   - Добавить пагинацию (limit, offset)
│   │   - Обработка rate limits (429)
│   │   - Retry logic
│   │
│   └── criteria.md
│       - Функции: list_orders, get_order, cancel_order
│       - Unit tests: 5+
│       - Rate limit: обработан
│
├── dev/
│   └── orders.py          ← АТОМАРНЫЙ КОД (280 строк)
│       ```python
│       class OrdersClient:
│           def list_orders(self, limit=100, offset=0):
│               # реализация с пагинацией
│               ...
│           def get_order(self, order_id):
│               # реализация с retry
│               ...
│           def cancel_order(self, order_id):
│               # реализация
│               ...
│       ```
│
├── testing/
│   ├── unit/
│   │   ├── test_pagination.py      ← 2 теста
│   │   ├── test_rate_limits.py     ← 2 теста
│   │   └── test_retry.py           ← 1 тест
│   └── criteria.md
│       ✅ 5 unit tests PASSED
│       ✅ Rate limit handling: OK
│
└── deploy/
    └── orders.py          ← финальная версия v2

ПРОЕКТ lideravto
  ↓ декомпозиция
dev/library/connectors/api/ozon (МОДУЛЬ)
  ↓ декомпозиция
dev/orders (БЛОК)
  ↓ декомпозиция
dev/v2 (ПОКОЛЕНИЕ — АТОМ, 280 строк)

dev/v2/
  1. claude-loader compile CLAUDE.md
     → Загружен контекст: requirements, api_client

  2. dev/orders.py
     → Написан код (280 строк)

  3. testing/unit/
     → 5 тестов написаны и PASSED

  4. deploy/orders.py
     → Финальная версия v2 готова

dev/orders/
  1. CACHE.yaml
     resolved:
       v2_result: {$ref: dev/v2/deploy/orders.py}

  2. claude-loader compile CLAUDE.md
     → Контекст: v1, v2 готовы

  3. deploy/orders.py
     → Экспортируем v2 (current)

  4. testing/integration/
     → 3 теста интеграции PASSED

library/connectors/api/ozon/
  1. CACHE.yaml
     resolved:
       orders: {$ref: dev/orders/deploy/orders.py}
       products: {$ref: dev/products/deploy/products.py}
       stocks: {$ref: dev/stocks/deploy/stocks.py}

  2. deploy/__init__.py
     → Собрать экспорты всех блоков

  3. testing/integration/
     → Тесты модуля PASSED

lideravto/
  1. CACHE.yaml
     resolved:
       ozon: {$ref: library/connectors/api/ozon/deploy/__init__.py}

  2. deploy/
     → Релиз проекта v2.0

  3. testing/e2e/
     → End-to-end тесты PASSED

# Для каждого уровня должны быть TRUE:

✅ planning/requirements.md — все требования зафиксированы
✅ planning/blocks.md — декомпозиция понятна
✅ planning/criteria.md — критерии определены
✅ CACHE.yaml — все входные данные resolved
✅ dev/ — реализовано (код или интеграция блоков)
✅ testing/ — все тесты PASSED
✅ testing/criteria.md — критерии выполнены
✅ deploy/ — результат собран и задокументирован

1. ИДЕЯ
   ↓
2. ДЕКОМПОЗИЦИЯ (Фаза 1)
   - Разбить на стадии
   - Разбить на модули
   - Разбить на блоки
   - Разбить на поколения
   - До атомарного уровня
   ↓
3. УТОЧНЕНИЕ (Фаза 2)
   - CLAUDE.md на каждом уровне
   - CACHE.yaml на каждом уровне
   - planning/ на каждом уровне
   ↓
4. РЕАЛИЗАЦИЯ (Фаза 3, bottom-up)
   - Начать с атомов
   - dev/ → testing/ → deploy/
   - Подняться на уровень выше
   - Повторить до корня
   ↓
5. ВАЛИДАЦИЯ (Фаза 4)
   - Тесты на каждом уровне
   - Критерии на каждом уровне
   - Интеграция на каждом уровне
   ↓
6. БЕЗУПРЕЧНЫЙ ПРОДУКТ

metrics:
  planning:
    requirements_coverage: 100%
    blocks_defined: YES
    criteria_defined: YES

  development:
    code_size: < 500 строк (если атом)
    dependencies_resolved: 100%

  testing:
    unit_tests_passed: 100%
    integration_tests_passed: 100%
    criteria_met: 100%

  deployment:
    build_success: YES
    documentation: YES

project_metrics:
  levels_total: 4
  levels_completed: 4
  atoms_total: 12
  atoms_passed: 12
  overall_coverage: 87%
  bugs_found: 0
  quality_score: A+