architect/standards/arh/guidance-project-management.md

type: standard
aspect: guidance
title: "СТАНДАРТ: Project Management"
version: 1.0.0
date: 2026-02-19
status: active

СТАНДАРТ: Project Management

Версия: 1.3.0
Дата: 2026-02-01
Статус: Active

Концепция

Система управления проектами основана на 4-мерной декомпозиции для решения проблемы переполнения контекста Claude.

Проблема: При росте проекта Claude теряет контекст, путается в зависимостях.

Решение: Разбиение на независимые units of work (контекстблоки), которые всегда влезают в контекст.

Четыре измерения проекта

┌─────────────────────────────────────────────────────────────┐
│ 1. СТАДИИ (Stages)        → lifecycle проекта               │
│ 2. БЛОКИ (Blocks)         → units of work                   │
│ 3. ПОКОЛЕНИЯ (Generations) → версии блока                   │
│ 4. ВОЛНЫ (Waves)          → релизы продукта                 │
└─────────────────────────────────────────────────────────────┘

1. Стадии (Lifecycle)

Стадия — этап жизненного цикла проекта.

Базовые стадии для IT проекта:

planning → infra → install → backup → setup → dev → testing → deploy → monitor → docs → maint
                                                      ↑
                                              основная стадия
                                          (содержит блоки)
Стадия Назначение Примеры
planning Планирование развития roadmap, требования
infra Инфраструктура сервер, домены, БД
install Установка платформы CS-Cart, Drupal, Django
backup Резервное копирование скрипты бэкапа, recovery
setup Настройка окружения конфиги, переменные
dev Разработка блоки функциональности
testing Тестирование unit, e2e, интеграционные
deploy Развёртывание CI/CD, staging, production
monitor Мониторинг логи, алерты, метрики
docs Документация guides, API docs
maint Обслуживание очистка, оптимизация

Принцип: Стадии — это структура проекта, не контекстблоки.

2. Блоки (Units of Work)

Блок = контекстблок = квант работы, влезающий в контекст Claude.

Критерии контекстблока

Критерий Значение
Размер 150-300 строк кода / 200-400 строк docs
Автономность Работает независимо от других блоков
Тестируемость Можно протестировать изолированно
Деплоимость Можно задеплоить отдельно
Полнота Решает одну законченную задачу

Типы блоков

Тип Описание Примеры
CODE Код приложения API endpoints, UI components
DOCS Документация концепция, руководство, стратегия
OPS Операции скрипты деплоя, бэкапа, миграции
DESIGN Дизайн системы архитектура, диаграммы, schemas
CONTENT Контент тексты, изображения, данные
TEST Тесты unit, e2e, интеграционные

Обязательная структура блока

ПРАВИЛО: Каждый блок (физическая папка) содержит минимум 2 файла:

блок/
├── CLAUDE.md          ← ОПИСАНИЕ (что это, метаданные, интерфейс)
├── CACHE.yaml         ← ВХОД (зависимости, параметры, кеш)
│
└── [результаты]       ← ВЫХОД (код, документация, артефакты)
    ├── lib/           ← код
    ├── README.md      ← документация
    ├── tests/         ← тесты
    └── dist/          ← артефакты

Роли файлов:

Файл Роль Содержит
CLAUDE.md Описание/интерфейс Метаданные блока, поколения, что делает
CACHE.yaml Входные данные Зависимости, параметры, кешированные данные
Остальное Результаты Код, документация, тесты, артефакты

Концептуальное разделение:

INPUT (CACHE.yaml)  → PROCESSING (логика блока) → OUTPUT (результаты)

Логическое vs Физическое разделение

ПРАВИЛО: Сначала логически описать в документации. Физическую папку создавать только если >300 строк.

# Малый блок (< 300 строк) — логически в CLAUDE.md стадии:
dev/
├── CLAUDE.md           ← описывает блоки filters, search
└── catalog.py          ← код всех блоков в одном файле

# Большой блок (> 300 строк) — физическая папка:
dev/
├── CLAUDE.md           ← описывает блоки стадии
├── import/             ← физическая папка для блока
│   ├── CLAUDE.md       ← описание блока
│   ├── CACHE.yaml      ← входные данные
│   └── lib/            ← результаты (код)

3. Поколения (Версии блока)

Поколение = версия одного блока (v1, v2, v3, ...).

Когда использовать

Если блок сложный (>300 строк) → разбить на поколения сразу при планировании.

Принципы поколений

Принцип Описание
Инкрементальность Каждое поколение добавляет функциональность
Автономность Каждое поколение работает независимо
Размер Каждое поколение влезает в контекст (~300-500 строк)
Деплой Каждое поколение можно задеплоить отдельно

Схема поколений в YAML

---
block:
  name: catalog
  type: CODE
  status: in_progress
  current_version: v2

generations:
  v1:
    date: 2025-12-15
    description: "MVP: базовый каталог + фильтры по марке"
    size: 400 строк
    duration: 45 минут
    deliverables:
      - Вывод списка товаров
      - Фильтр по марке/модели
      - Базовая пагинация
    status: deployed

  v2:
    date: 2026-01-10
    description: "Вариации по OEM + умный поиск"
    size: 500 строк
    duration: 1 час
    deliverables:
      - product_variations модуль
      - Поиск по артикулу/OEM
      - Группировка вариантов
    status: in_progress
    depends_on: [v1]

  v3:
    date: planned
    description: "Продвинутые фильтры + кеширование"
    size: 400 строк
    duration: 45 минут
    deliverables:
      - AJAX фильтры
      - Кеширование запросов
      - Умная пагинация
    status: planned
    depends_on: [v2]
---

Физическая организация поколений

Вариант A: Архив старых версий

catalog/
├── CLAUDE.md           ← описание всех поколений
├── current/            ← v2 (текущее)
│   ├── filters.php
│   └── variations.php
└── archive/
    └── v1/             ← архив v1
        └── filters.php

Вариант B: Метаданные в YAML (для малых блоков)

# Код в одном файле, версии в метаданных
generations:
  v1: { status: archived, lines: "1-150" }
  v2: { status: current, lines: "151-350" }

4. Волны (Релизы продукта)

Волна = snapshot всего продукта (набор блоков + поколений в определённый момент).

Волна ≠ Поколение:
- Поколение — версия одного блока (import v1, v2, v3)
- Волна — версия всего продукта (Product 1.0, 2.0, 3.0)

Схема волн в YAML

---
# ROADMAP.md

product:
  name: lideravto
  current_version: 2.0

waves:
  v1.0:
    name: "MVP"
    release_date: 2025-12-01
    status: deployed
    blocks:
      import: v1
      data: v1
      infra: v1
    deliverables:
      - Базовый импорт BAZON
      - Инфраструктура настроена

  v2.0:
    name: "Каталог"
    release_date: 2026-01-15
    status: deployed
    blocks:
      import: v3        ← прыгнул на 2 версии
      catalog: v1       ← новый блок
      seo: v1           ← новый блок
      data: v1          ← не менялся
    deliverables:
      - Модульный импорт (lib/)
      - Каталог с фильтрами
      - SEO концепция

  v3.0:
    name: "Оптимизация"
    release_date: 2026-02-15
    status: planned
    blocks:
      import: v3        ← не менялся
      catalog: v2       ← обновился
      seo: v2           ← обновился
    deliverables:
      - Вариации по OEM
      - Canonical URLs
      - Продвинутые фильтры
---

Независимость версий

Блок может обновляться между волнами:

import:  v1 ────→ v2 ────→ v3
          ↓       skip     ↓
        Wave 1           Wave 2

Волна может включать разные поколения блоков:

Wave 2.0 (Product):
├── import v3      ← зрелый блок (3 поколения)
├── catalog v1     ← новый блок (1 поколение)
└── seo v1         ← новый блок (1 поколение)

Иерархия CLAUDE.md

Каждая папка содержит CLAUDE.md с метаданными в YAML frontmatter.

Схема наследования

workspace/CLAUDE.md                    ← L1: Workspace
    ↓ extends
projects/org/CLAUDE.md                 ← L2: Organization
    ↓ extends
projects/org/{PROJECT_NAME}/CLAUDE.md       ← L3: Project
    ↓ extends
projects/org/{PROJECT_NAME}/dev/CLAUDE.md   ← L4: Stage
    ↓ extends
.../dev/import/CLAUDE.md               ← L5: Block

YAML Frontmatter

---
# Наследование
extends: ../CLAUDE.md

# Секции из родителя
include:
  - credentials
  - config

# Кеш зависимостей
cache:
  bazon_url: {$ref: ../../data/MASTER.md#bazon_live_url}
  db_config: {$ref: ../infra/DATABASE.md#dev}

# Метаданные стадии
stage:
  name: dev
  type: development
  status: in_progress

# Метаданные блока
block:
  name: import
  type: CODE
  status: completed
  current_version: v3

# Поколения блока
generations:
  v1: { date: 2025-11, status: archived }
  v2: { date: 2025-12, status: archived }
  v3: { date: 2026-01, status: current }

# Автогенерируемая секция (claude-loader.py)
resolved:
  # заполняется автоматически при компиляции
---

# Markdown контент...

Компиляция контекста

claude-loader.py компилирует CLAUDE.md с зависимостями в один документ:

# Компиляция CLAUDE.md
claude-loader compile projects/org/{PROJECT_NAME}/dev/import/CLAUDE.md

# Валидация YAML
claude-loader validate projects/org/{PROJECT_NAME}/dev/import/CLAUDE.md

# Обновление resolved секции
claude-loader update projects/org/{PROJECT_NAME}/dev/import/CLAUDE.md

Что делает:
1. Резолвит extends: рекурсивно (до корня)
2. Извлекает секции из include:
3. Резолвит $ref из cache:
4. Генерирует resolved: секцию
5. Возвращает полный контекст для Claude

Workflow

1. Планирование проекта

# PROJECT.md или CLAUDE.md (корень)

project:
  name: projectname
  type: ecommerce
  status: planning

stages:                        ← определить стадии
  - planning
  - infra
  - dev
  - testing
  - deploy
  - monitor

2. Декомпозиция стадии на блоки

# dev/CLAUDE.md

stage:
  name: dev

blocks:                        ← определить блоки
  import:
    type: CODE
    size: ~1500 строк         ← большой → нужны поколения
    status: planned

  catalog:
    type: CODE
    size: ~800 строк          ← средний → возможны поколения
    status: planned

  seo:
    type: DOCS
    size: ~200 строк          ← малый → без поколений
    status: planned

3. Планирование поколений (если блок >300 строк)

# dev/import/CLAUDE.md

block:
  name: import

generations:
  v1:
    description: "Базовый CSV парсинг"
    size: 300 строк
    duration: 30 минут
    deliverables: [...]

  v2:
    description: "4-уровневая категоризация"
    size: 400 строк
    duration: 45 минут
    deliverables: [...]
    depends_on: [v1]

  v3:
    description: "Модульная lib/ архитектура"
    size: 500 строк
    duration: 1 час
    deliverables: [...]
    depends_on: [v2]

4. Планирование волн (релизов)

# ROADMAP.md

waves:
  v1.0:
    name: "MVP"
    blocks:
      import: v1
      data: v1

  v2.0:
    name: "Каталог"
    blocks:
      import: v3       ← финальная версия import
      catalog: v1
      seo: v1

5. Реализация

Для каждой волны:
  Для каждого блока в волне:
    Для каждого поколения блока:
      1. Загрузить контекст (claude-loader compile)
      2. Реализовать поколение
      3. Тесты
      4. Деплой
      5. Обновить статус в CLAUDE.md

6. Документирование прогресса

# Обновление статусов в CLAUDE.md

block:
  name: import
  current_version: v2          ← обновить версию

generations:
  v1: { status: deployed }
  v2: { status: in_progress }  ← обновить статус
  v3: { status: planned }

Структура проекта

Типичная структура

projectname/
├── CLAUDE.md                  ← L3: корень проекта
├── CONTEXT_BLOCKS.md          ← карта всех блоков
├── ROADMAP.md                 ← волны (релизы)
├── PROJECT.md                 ← описание бизнеса
├── MIGRATION.md               ← история миграций
│
├── planning/                  ← СТАДИЯ
│   └── CLAUDE.md
│
├── infra/                     ← СТАДИЯ
│   └── CLAUDE.md
│
├── dev/                       ← СТАДИЯ (основная)
│   ├── CLAUDE.md              ← описание блоков стадии
│   │
│   ├── import/                ← БЛОК (физическая папка, >300 строк)
│   │   ├── CLAUDE.md          ← описание блока, поколения
│   │   ├── CACHE.yaml         ← входные данные, зависимости
│   │   ├── lib/               ← результаты: код v3 (current)
│   │   ├── README.md          ← результаты: документация
│   │   ├── tests/             ← результаты: тесты
│   │   └── archive/
│   │       ├── v1/            ← ПОКОЛЕНИЕ 1
│   │       └── v2/            ← ПОКОЛЕНИЕ 2
│   │
│   ├── catalog/               ← БЛОК
│   │   ├── CLAUDE.md
│   │   ├── CACHE.yaml
│   │   └── views/             ← результаты: код
│   │
│   └── seo/                   ← БЛОК (малый, только docs)
│       ├── CLAUDE.md
│       ├── CACHE.yaml
│       └── docs/              ← результаты: документация
│
├── testing/                   ← СТАДИЯ
│   └── CLAUDE.md
│
├── deploy/                    ← СТАДИЯ
│   └── CLAUDE.md
│
└── data/                      ← СТАДИЯ (источники данных)
    ├── CLAUDE.md
    └── MASTER.md

Шаблоны YAML

Корень проекта (L3)

---
extends: ../CLAUDE.md

project:
  name: projectname
  type: ecommerce|saas|platform
  status: development|production
  current_version: 2.0        ← текущая волна

credentials:
  database:
    host: localhost
    name: db_name
  domain:
    production: example.com
    development: dev.example.com
---

Стадия (L4)

---
extends: ../CLAUDE.md

stage:
  name: dev
  type: development
  status: in_progress

include:
  - credentials

blocks:
  import: { status: completed, version: v3 }
  catalog: { status: in_progress, version: v1 }
  seo: { status: planned }
---

Блок (L5)

CLAUDE.md (описание блока):

---
extends: ../CLAUDE.md

block:
  name: import
  type: CODE
  status: completed
  current_version: v3
  size: ~1500 строк

  description: "Импорт товаров из BAZON с 4-уровневой категоризацией"

  inputs:              ← что требует (ссылка на CACHE.yaml)
    - BAZON CSV URL
    - Database config

  outputs:             ← что производит
    - Товары в БД (4626 шт)
    - Категории 4-уровневые (153 шт)
    - Лог импорта

generations:
  v1:
    date: 2025-11-15
    description: "Базовый CSV парсинг"
    size: 300 строк
    duration: 30 минут
    status: archived
    deliverables:
      - Парсинг CSV файла BAZON
      - Создание товаров в БД

  v2:
    date: 2025-12-20
    description: "4-уровневая категоризация"
    size: 400 строк
    duration: 45 минут
    status: archived
    depends_on: [v1]
    deliverables:
      - Марка → Модель → Группа → Подгруппа
      - Автоматическое создание категорий

  v3:
    date: 2026-01-10
    description: "Модульная lib/ архитектура"
    size: 500 строк
    duration: 1 час
    status: current
    depends_on: [v2]
    deliverables:
      - lib/parsers/ — парсинг
      - lib/categories/ — категоризация
      - lib/products/ — создание товаров
---

CACHE.yaml (входные данные):

# Зависимости
dependencies:
  - ../../data/MASTER.md
  - ../infra/DATABASE.md

# Параметры (что нужно на вход)
inputs:
  bazon_url:
    type: string
    required: true
    source: {$ref: ../../data/MASTER.md#bazon_live_url}

  db_config:
    type: object
    required: true
    source: {$ref: ../infra/DATABASE.md#dev}

# Кеш (resolved данные)
resolved:
  bazon_url: "https://baz-on.ru/export/c3762/18829/lideravtoplus-bitrix.csv"
  db_config:
    host: localhost
    name: lideravto_db
    user: lideravto_user

# Метаданные кеша
cache_metadata:
  updated: 2026-02-01T10:30:00
  version: 3.0.0

ROADMAP.md (волны)

---
product:
  name: projectname
  current_version: 2.0

waves:
  v1.0:
    name: "MVP"
    release_date: 2025-12-01
    status: deployed
    blocks:
      import: v1
      data: v1
      infra: v1
    deliverables:
      - Базовый импорт работает
      - Инфраструктура готова
    metrics:
      lines_of_code: 500
      duration: 2 часа

  v2.0:
    name: "Каталог"
    release_date: 2026-01-15
    status: deployed
    blocks:
      import: v3
      catalog: v1
      seo: v1
    deliverables:
      - Модульный импорт
      - Каталог с фильтрами
      - SEO концепция
    metrics:
      lines_of_code: 2000
      duration: 6 часов

  v3.0:
    name: "Оптимизация"
    release_date: 2026-02-15
    status: planned
    blocks:
      import: v3
      catalog: v2
      seo: v2
      testing: v1
    deliverables:
      - Вариации по OEM
      - Canonical URLs
      - Автотесты
    metrics:
      lines_of_code: 3000
      duration: 8 часов
---

CONTEXT_BLOCKS.md (карта блоков)

# КОНТЕКСТБЛОКИ: projectname

## Стадии проекта

| Стадия | Статус | Описание |
|--------|--------|----------|
| planning | completed | Планирование |
| infra | completed | Инфраструктура |
| **dev** | in_progress | **Разработка (содержит блоки)** |
| testing | planned | Тестирование |
| deploy | in_progress | Развёртывание |

## Контекстблоки в dev/

| Блок | Статус | Тип | Размер | Версия | Описание |
|------|--------|-----|--------|--------|----------|
| import | completed | CODE | ~1500 | v3 | Импорт данных |
| catalog | in_progress | CODE | ~800 | v1 | Каталог товаров |
| seo | planned | DOCS | ~200 | v1 | SEO оптимизация |

## Зависимости блоков

data → import → catalog → seo
↓
testing → deploy

## Волны развития

- **v1.0 (MVP)**: import v1, data v1
- **v2.0 (Каталог)**: import v3, catalog v1, seo v1
- **v3.0 (Оптимизация)**: catalog v2, seo v2, testing v1

Инструменты

claude-loader.py

Назначение: Компиляция CLAUDE.md с зависимостями в один контекст.

# Установка
pip install pyyaml python-frontmatter

# Компиляция
claude-loader compile path/to/CLAUDE.md

# Валидация
claude-loader validate path/to/CLAUDE.md

# Обновление resolved секции
claude-loader update path/to/CLAUDE.md

# Обновление всех CLAUDE.md в проекте
claude-loader update-all projects/org/projectname/

Что делает:
1. Читает CLAUDE.md
2. Резолвит extends: (рекурсивно вверх по иерархии)
3. Извлекает секции из include:
4. Резолвит $ref из cache:
5. Генерирует resolved: секцию
6. Возвращает полный скомпилированный документ

Путь: $WORKSPACE/tools/claude-loader.py

Метрики и KPI

Метрики блока

block:
  metrics:
    size: 500 строк
    complexity: medium
    test_coverage: 85%
    duration_estimate: 1 час
    duration_actual: 55 минут

Метрики волны

wave:
  metrics:
    blocks_total: 5
    blocks_completed: 3
    lines_of_code: 2500
    duration_estimate: 6 часов
    duration_actual: 5.5 часов
    test_coverage: 80%

Метрики проекта

project:
  metrics:
    stages_total: 11
    stages_completed: 5
    blocks_total: 12
    blocks_completed: 6
    waves_total: 3
    waves_completed: 2
    lines_of_code: 5000

Чеклисты

Создание нового проекта

Добавление нового блока

ОБЯЗАТЕЛЬНАЯ фрактальная структура:

Стандарт: FRACTAL_ARCHITECTURE.md

Реализация поколения блока

Релиз волны

Примеры

Пример 1: Малый проект (1 волна, без поколений)

simple-bot/
├── CLAUDE.md           ← project info
├── PROJECT.md
├── dev/
│   ├── CLAUDE.md       ← описывает блоки логически
│   └── bot.py          ← все блоки в одном файле
└── deploy/
    └── CLAUDE.md

# dev/CLAUDE.md
blocks:
  telegram: { type: CODE, size: 150, status: completed }
  commands: { type: CODE, size: 100, status: completed }
  database: { type: CODE, size: 80, status: completed }

Без физических папок — всё описано логически.

Пример 2: Средний проект (2-3 волны, частичные поколения)

ecommerce/
├── CLAUDE.md
├── ROADMAP.md          ← 2 волны
├── CONTEXT_BLOCKS.md
├── dev/
│   ├── CLAUDE.md
│   ├── catalog/        ← большой блок, физическая папка
│   │   ├── CLAUDE.md   ← описание, 2 поколения
│   │   ├── CACHE.yaml  ← входные данные
│   │   ├── v1/         ← результаты: код v1
│   │   └── v2/         ← результаты: код v2
│   └── payment.py      ← малый блок, один файл
└── deploy/

Частичное разделение — большие блоки в папках с CACHE.yaml, малые inline.

Пример 3: Большой проект (5+ волн, поколения, архив)

platform/
├── CLAUDE.md
├── ROADMAP.md          ← 5 волн
├── CONTEXT_BLOCKS.md
├── dev/
│   ├── CLAUDE.md
│   ├── api/            ← блок с поколениями
│   │   ├── CLAUDE.md   ← описание, 4 поколения
│   │   ├── CACHE.yaml  ← входные данные
│   │   ├── current/    ← результаты: v4
│   │   ├── README.md   ← результаты: документация
│   │   ├── tests/      ← результаты: тесты
│   │   └── archive/
│   │       ├── v1/
│   │       ├── v2/
│   │       └── v3/
│   ├── ui/             ← блок с поколениями
│   │   ├── CLAUDE.md
│   │   ├── CACHE.yaml
│   │   └── ...
│   └── workers/        ← блок с поколениями
│       ├── CLAUDE.md
│       ├── CACHE.yaml
│       └── ...
├── testing/
└── deploy/

Полное разделение — все блоки в папках с CLAUDE.md + CACHE.yaml, все поколения архивируются.

Фрактальная архитектура

См. полный стандарт: FRACTAL_ARCHITECTURE.md

Концепция: Каждый уровень (проект, модуль, блок, поколение) — это микро-проект с одинаковой структурой.

Минимальная структура любого уровня:

микро-проект/
├── CLAUDE.md          ← описание
├── CACHE.yaml         ← входные данные
├── planning/          ← требования, декомпозиция, критерии
├── dev/               ← разработка (код или под-блоки)
├── testing/           ← тесты
└── deploy/            ← результат

Рекурсивный цикл разработки:
1. Декомпозиция (top-down) — разбить до атомарного уровня
2. Уточнение — заполнить CLAUDE.md, CACHE.yaml, planning/ на всех уровнях
3. Реализация (bottom-up) — реализовать от атомов к корню
4. Валидация — тестировать на каждом уровне

Результат: Безупречный продукт (все уровни протестированы и интегрированы).

Связанные стандарты

Стандарт Назначение
FRACTAL_ARCHITECTURE.md Фрактальная архитектура (рекурсивная структура)
CONTEXT_BLOCKS.md Концепция контекстблоков
CLAUDE_HIERARCHY.md Иерархия CLAUDE.md файлов
PROJECT_DOCUMENTATION.md Документация проекта
ROADMAP.md Шаблон roadmap

Инструменты

Инструмент Путь
claude-loader.py $WORKSPACE/tools/claude-loader.py
Шаблоны CLAUDE.md $WORKSPACE/architect/templates/

Changelog

Версия Дата Изменения
1.2.0 2026-02-01 Добавлено: фрактальная архитектура (рекурсивная структура)
1.1.0 2026-02-01 Добавлено: обязательная структура блока (CLAUDE.md + CACHE.yaml + результаты)
1.0.0 2026-02-01 Первая версия стандарта

Версия: 1.2.0
Статус: Active