Версия: 1.0.0
Дата: 2026-03-07
При росте проекта AI теряет контекст — путается в зависимостях, держит в голове лишнее.
Решение: Разбивать работу на независимые единицы (контекстблоки), каждая из которых
помещается в контекст за один сеанс.
Читать вместе с:
- PROJECT_STANDARD_IT.md — структура, git, versioning
- PROJECT_PROCESSES.md — жизненный цикл IDEA→CLOSED
┌─────────────────────────────────────────────────────────────┐
│ 1. СТАДИИ (Stages) → этапы жизненного цикла │
│ 2. БЛОКИ (Blocks) → единицы работы (контекстблоки) │
│ 3. ПОКОЛЕНИЯ (Generations) → версии одного блока │
│ 4. ВОЛНЫ (Waves) → релизы продукта │
└─────────────────────────────────────────────────────────────┘
Стадия — этап жизненного цикла. Это структура проекта, не единица работы.
planning → infra → install → setup → dev → testing → deploy → monitor → maint
| Стадия | Назначение |
|---|---|
planning |
Roadmap, требования |
infra |
Сервер, домены, БД |
install |
Установка платформы (Drupal, Django...) |
setup |
Конфиги, переменные окружения |
dev |
Разработка (блоки) |
testing |
Unit, e2e, интеграционные тесты |
deploy |
CI/CD, staging → production |
monitor |
Логи, алерты, метрики |
maint |
Обслуживание, очистка |
Блок = квант работы, помещающийся в контекст AI за один сеанс.
| Критерий | Значение |
|---|---|
| Размер | 150–300 строк кода / 200–400 строк docs |
| Автономность | Работает независимо |
| Тестируемость | Тестируется изолированно |
| Полнота | Решает одну законченную задачу |
| Тип | Что | Примеры |
|---|---|---|
CODE |
Код приложения | API, UI компоненты, скрипты |
DOCS |
Документация | концепция, руководство |
OPS |
Операции | деплой, бэкап, миграции |
DESIGN |
Архитектура | схемы, модели данных |
TEST |
Тесты | unit, e2e, интеграция |
CONTENT |
Контент | тексты, данные |
Сначала описать логически. Физическую папку создавать только если блок >300 строк.
# Малый блок (< 300 строк) — логически в CLAUDE.md стадии:
dev/
├── CLAUDE.md ← описывает блоки filters, search
└── catalog.py ← код всех блоков в одном файле
# Большой блок (> 300 строк) — физическая папка:
dev/
├── CLAUDE.md
└── import/
├── CLAUDE.md ← описание блока
├── CACHE.yaml ← входные данные / зависимости
└── lib/ ← результаты (код)
блок/
├── CLAUDE.md ← ЧТО ЭТО (описание, метаданные, поколения)
├── CACHE.yaml ← ВХОД (зависимости, параметры, кешированные данные)
└── [результаты] ← ВЫХОД
├── lib/ ← код
├── tests/ ← тесты
└── README.md ← документация
Поколение = версия одного блока (v1, v2, v3...).
Применять если блок > 300 строк — разбить на инкрементальные части.
block:
name: import
type: CODE
status: in_progress
current_version: v2
generations:
v1:
description: "MVP: базовый парсинг CSV"
size: 300 строк
deliverables: [парсинг, базовая категоризация]
status: deployed
v2:
description: "Модульная lib/ архитектура"
size: 400 строк
deliverables: [lib/parser, lib/mapper, lib/loader]
status: in_progress
depends_on: [v1]
v3:
description: "Кеширование + инкрементальный импорт"
size: 300 строк
deliverables: [кеш, дельта-импорт]
status: planned
depends_on: [v2]
import/
├── CLAUDE.md ← описание всех поколений
├── lib/ ← текущее поколение (v2)
│ ├── parser.py
│ └── loader.py
└── arh/
└── v1/ ← архив v1
└── import.py
Волна = версия всего продукта в определённый момент (набор блоков × поколений).
Волна ≠ Поколение:
Поколение — версия одного блока (import v1, v2, v3)
Волна — версия всего проекта (Product 1.0, 2.0, 3.0)
waves:
v1.0:
name: "MVP"
status: deployed
blocks:
import: v1
infra: v1
v2.0:
name: "Каталог"
status: in_progress
blocks:
import: v3 # вырос за время между волнами
catalog: v1 # новый блок
seo: v1 # новый блок
v3.0:
name: "Оптимизация"
status: planned
blocks:
catalog: v2 # обновился
seo: v2 # обновился
import: v1 ──→ v2 ──→ v3
↓ ↓
(skip) Wave 2
Каждая папка содержит CLAUDE.md с контекстом для AI.
CLAUDE.md (workspace)
↓
projects/org/CLAUDE.md
↓
projects/org/{name}/CLAUDE.md ← L3: проект (стратегия)
↓
{name}/dev/CLAUDE.md ← L4: стадия (блоки стадии)
↓
{name}/dev/import/CLAUDE.md ← L5: блок (поколения, кеш)
Что содержит CLAUDE.md блока:
---
block:
name: import
type: CODE
status: in_progress
current_version: v2
# Кешированные данные из зависимостей
cache:
db_config: "host=localhost, db=lideravto"
api_url: "https://api.bazon.ru/v2"
generations:
v1: { status: deployed, date: 2026-01 }
v2: { status: in_progress, date: 2026-02 }
---
# Что делает этот блок
# Интерфейс (входы / выходы)
# Зависимости
1. Определить стадию: dev / testing / ...
2. Определить блок: import / catalog / ...
3. Определить поколение: v1 / v2 / ...
4. Загрузить контекст:
- Прочитать CLAUDE.md блока
- Прочитать CACHE.yaml (зависимости)
5. Реализовать поколение:
- Код / документация / тесты в рамках блока
- Не выходить за границы блока
6. Проверить:
- Размер не превысил 300 строк?
- Тесты проходят?
- Задача блока выполнена?
7. Обновить статус в CLAUDE.md
8. Зафиксировать (git commit)
# dev/CLAUDE.md
stage:
name: dev
blocks:
import:
type: CODE
size: ~1500 строк # большой → нужны поколения
status: planned
catalog:
type: CODE
size: ~800 строк # средний → 2-3 поколения
status: planned
seo:
type: DOCS
size: ~200 строк # малый → без поколений
status: planned
Правило: Если блок > 300 строк — планировать поколения сразу.
- [ ] Определить тип блока (CODE/DOCS/OPS/DESIGN/TEST)
- [ ] Оценить размер
- [ ] Если > 300 строк — спланировать поколения
- [ ] Создать CLAUDE.md с метаданными
- [ ] Создать CACHE.yaml с зависимостями
- [ ] Добавить блок в CLAUDE.md стадии
- [ ] Прочитать CLAUDE.md блока и родительской стадии
- [ ] Прочитать CACHE.yaml
- [ ] Реализовать только то, что в deliverables этого поколения
- [ ] Написать тесты
- [ ] Обновить статус в CLAUDE.md
- [ ] Коммит: feat({блок}): {поколение} - {описание}
- [ ] Все блоки волны в статусе deployed
- [ ] Тесты прошли
- [ ] ROADMAP.md обновлён
- [ ] Версия зафиксирована тегом (git tag v2.0.0)
Обновлено: 2026-03-07