Aleksandr-Litvinenko Планирование и декомпозиция задач
Обзор
Разложи работу на мелкие проверяемые задачи с явными критериями приёмки. Хорошая декомпозиция — это разница между агентом, который надёжно доводит работу до конца, и агентом, который производит клубок. Каждая задача должна быть достаточно мелкой, чтобы её можно было реализовать, протестировать и проверить за одну сфокусированную сессию.
Когда применять
- Есть спека, и её надо разложить на реализуемые единицы
- Задача кажется слишком большой или размытой, чтобы начать
- Работу нужно распараллелить между несколькими агентами или сессиями
- Нужно донести объём работ до человека
- Порядок реализации неочевиден
Когда НЕ применять: изменения в одном файле с очевидным объёмом или когда спека уже содержит хорошо определённые задачи.
Процесс планирования
Шаг 1: Войди в режим планирования
Прежде чем писать код, работай в режиме «только чтение»:
- Прочитай спеку и относящиеся к делу части кодовой базы
- Определи существующие паттерны и соглашения
- Построй карту зависимостей между компонентами
- Отметь риски и неизвестные
НЕ пиши код во время планирования. Результат — документ плана в tasks/plan.md и список задач в tasks/todo.md, а не реализация.
Шаг 2: Построй граф зависимостей
Отобрази, что от чего зависит:
Схема базы данных
│
├── Модели/типы API
│ │
│ ├── Эндпоинты API
│ │ │
│ │ └── Клиент API на фронтенде
│ │ │
│ │ └── UI-компоненты
│ │
│ └── Логика валидации
│
└── Начальные данные / миграции
Порядок реализации идёт по графу зависимостей снизу вверх: сначала фундамент.
Шаг 3: Режь вертикально
Вместо того чтобы сделать всю базу, потом весь API, потом весь UI — делай по одному целому пути фичи за раз:
Плохо (горизонтальная нарезка):
Задача 1: Построить всю схему БД
Задача 2: Построить все эндпоинты API
Задача 3: Построить все UI-компоненты
Задача 4: Соединить всё вместе
Хорошо (вертикальная нарезка):
Задача 1: Пользователь может создать аккаунт (схема + API + UI регистрации)
Задача 2: Пользователь может войти (схема аутентификации + API + UI логина)
Задача 3: Пользователь может создать задачу (схема задачи + API + UI создания)
Задача 4: Пользователь может посмотреть список задач (запрос + API + UI списка)
Каждый вертикальный срез даёт работающую и проверяемую функциональность.
Шаг 4: Опиши задачи
Каждая задача строится так:
## Задача [N]: [Короткий описательный заголовок]
**Описание:** один абзац о том, что эта задача даёт.
**Критерии приёмки:**
- [ ] [Конкретное проверяемое условие]
- [ ] [Конкретное проверяемое условие]
**Проверка:**
- [ ] Тесты проходят: [команда точечного прогона тестов в этом репозитории]
- [ ] Сборка успешна: [команда сборки в этом репозитории]
- [ ] Ручная проверка: [описание того, что проверить]
**Зависимости:** [Номера задач, от которых зависит, или «Нет»]
**Файлы, которые скорее всего будут затронуты:**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`
**Оценка объёма:** [Малая: 1–2 файла | Средняя: 3–5 файлов | Большая: 5+ файлов]
Шаг 5: Упорядочь и расставь точки контроля
Расставь задачи так, чтобы:
- Зависимости были удовлетворены (сначала фундамент)
- Каждая задача оставляла систему в работающем состоянии
- Точки проверки стояли после каждых 2–3 задач
- Высокорисковые задачи шли раньше (падать быстро)
Добавь явные точки контроля:
## Контрольная точка: после задач 1–3
- [ ] Все тесты проходят
- [ ] Приложение собирается без ошибок
- [ ] Основной пользовательский сценарий работает от начала до конца
- [ ] Обсудить с человеком, прежде чем идти дальше
Ориентиры по размеру задач
| Размер | Файлов | Объём | Пример |
|---|---|---|---|
| XS | 1 | Одна функция или изменение конфига | Добавить правило валидации |
| S | 1–2 | Один компонент или эндпоинт | Добавить новый эндпоинт API |
| M | 3–5 | Один срез фичи | Поток регистрации пользователя |
| L | 5–8 | Фича из нескольких компонентов | Поиск с фильтрацией и пагинацией |
| XL | 8+ | Слишком крупно — дроби дальше | — |
Если задача размера L или больше, её надо разбить на более мелкие. Агент лучше всего работает на задачах S и M.
Когда дробить задачу дальше:
- Она займёт больше одной сфокусированной сессии (грубо — 2+ часа работы агента)
- Ты не можешь описать критерии приёмки тремя или меньше пунктами
- Она затрагивает две и более независимые подсистемы (например, аутентификацию и биллинг)
- Ты ловишь себя на слове «и» в заголовке задачи (признак того, что задачи две)
Выходные файлы
- Документ плана: сохраняй план реализации в
tasks/plan.md. - Список задач: сохраняй чеклист задач в
tasks/todo.md.
Создай каталог tasks/, если его нет. Эти пути — соглашение, которого ожидает команда /build и остальной инструментарий ниже по потоку.
Шаблон документа плана
# План реализации: [Название фичи/проекта]
## Обзор
[Один абзац о том, что мы строим]
## Архитектурные решения
- [Ключевое решение 1 и его обоснование]
- [Ключевое решение 2 и его обоснование]
## Список задач
### Фаза 1: Фундамент
- [ ] Задача 1: ...
- [ ] Задача 2: ...
### Контрольная точка: фундамент
- [ ] Тесты проходят, сборка чистая
### Фаза 2: Основные фичи
- [ ] Задача 3: ...
- [ ] Задача 4: ...
### Контрольная точка: основные фичи
- [ ] Сквозной сценарий работает
### Фаза 3: Доводка
- [ ] Задача 5: ...
- [ ] Задача 6: ...
### Контрольная точка: готово
- [ ] Все критерии приёмки выполнены
- [ ] Готово к ревью
## Риски и способы их снижения
| Риск | Влияние | Что делаем |
|------|--------|------------|
| [Риск] | [Высокое/Среднее/Низкое] | [Стратегия] |
## Открытые вопросы
- [Вопрос, требующий участия человека]
Возможности для распараллеливания
Когда доступно несколько агентов или сессий:
- Безопасно параллелить: независимые срезы фич, тесты для уже реализованных фич, документацию
- Строго последовательно: миграции БД, изменения общего состояния, цепочки зависимостей
- Требует координации: фичи, разделяющие контракт API (сначала определи контракт, потом параллель)
Типовые самооправдания
| Самооправдание | Как на самом деле |
|---|---|
| «Разберусь по ходу» | Именно так и получается клубок с последующими переделками. 10 минут планирования экономят часы. |
| «Задачи и так очевидны» | Всё равно выпиши их. Явные задачи вытаскивают скрытые зависимости и забытые краевые случаи. |
| «Планирование — это накладные расходы» | Планирование и есть задача. Реализация без плана — это просто набор текста. |
| «Я всё удержу в голове» | Окно контекста конечно. Записанные планы переживают границы сессий и сжатие контекста. |
Тревожные признаки
- Начинаешь реализацию без письменного списка задач
- Задачи вида «реализовать фичу» без критериев приёмки
- В плане нет шагов проверки
- Все задачи размера XL
- Между задачами нет контрольных точек
- Не учтён порядок зависимостей
Проверка
Прежде чем начинать реализацию, убедись:
- У каждой задачи есть критерии приёмки
- У каждой задачи есть шаг проверки
- Зависимости задач определены и упорядочены верно
- Ни одна задача не трогает больше ~5 файлов
- Между крупными фазами есть контрольные точки
- Человек посмотрел и утвердил план
См. также
Критерии приёмки относятся к отдельной задаче и отвечают на вопрос «то ли мы построили?». Они лежат поверх общего для проекта Definition of Done — постоянной планки, которую проходит каждая задача, прежде чем считаться выполненной. См. ../../references/definition-of-done.md.