Модуль 10

От идеи до готового приложения

Идея «программа лояльности» превращается в файл требований через интервью с агентом, режется на задачи с критериями и проходит цикл «сессия, план, правка, проверка, статус, коммит» до приёмки по сценариям. В конце: как этот подход называется и где готовые фреймворки.

30 мин

Содержание модуля

Шаг 1. Идея превращается в требования
Шаг 2. Требования превращаются в задачи
Шаг 3. Цикл одной задачи
Шаг 4. Приёмка по требованиям

Чему научишься

собирать требования в docs/loyalty.md через интервью с агентом
декомпозировать требования на задачи с проверяемыми критериями
проводить задачу по циклу: сессия, план, правка, проверка критерия, статус, коммит
принимать фичу прогоном сценариев из файла требований

До сих пор требование приходило готовым: TODO в pricing.ts, сломанная валидация, устаревший README. Реальный поток начинается словами «хочу программу лояльности», и качество приложения решается до первой правки кода. Модуль проходит весь цикл на фиче лояльности в orders-api, те же шаги работают и для нового проекта с нуля.

В цикле четыре шага: интервью и файл требований, декомпозиция на задачи, выполнение по одной, приёмка по сценариям. Поток держат два файла: docs/loyalty.md хранит требования, TASKS.md хранит задачи и статусы. Файлы переживают сессии, чат умирает вместе с задачей.

Шаг 1. Идея превращается в требования

Дай агенту роль интервьюера: пусть прежде чем предлагать решение задаёт вопросы. Вопросы находят дыры в идее до кода: начисление до или после скидки от 1000 ₽, сгорают ли баллы, что делать со старыми заказами. Отвечай фактами и числами, каждое решение фиксируй в файле требований.

Интервью в plan-агенте

Хочу программу лояльности в orders-api. Прежде чем что-то предлагать, задай уточняющие вопросы, ответы зафиксируй в docs/loyalty.md

Вопросы: 1. Сколько баллов начислять и от чего: процент от суммы или фикс за заказ? 2. Начисление до скидки от 1000 ₽ или после неё? 3. Округление при начислении? 4. Сгорают ли баллы и через сколько? 5. Можно ли списать часть баллов и какой максимум списания? 6. Что с заказами, сделанными до запуска программы?

1 балл за каждые полные 10 ₽ оплаченной суммы, после скидки. Списание частями, максимум 50% суммы заказа, передаётся полем loyalty.spend. Сгорают через 30 дней. Старые заказы не трогаем.

Создан docs/loyalty.md: правила, сценарии приёмки, границы

docs/loyalty.md

# Программа лояльности

Правила:
- 1 балл за каждые полные 10 ₽ оплаченной суммы (после скидки от 1000 ₽)
- 1 балл = 1 ₽ при списании, списание до 50% суммы заказа
- Списание передаётся в заказе полем loyalty.spend
- Баллы сгорают через 30 дней после начисления
- Профиль баллов заводится по полю customer, старые заказы баллов не начисляют

Сценарии приёмки:
1. Заказ cap×3 + chz×2 (1740 ₽) со скидкой: к оплате 1566 ₽, начислено 156 баллов
2. Следующий заказ chz×2 (840 ₽) с loyalty.spend 100: к оплате 740 ₽
3. Запрос списать 500 баллов за заказ 840 ₽ отклоняется: максимум 50%
4. Заказ с новым customer заводит профиль баллов с нуля

Числа согласованы с меню: cap 300 ₽, chz 420 ₽, скидка из модуля 6.

Шаг 2. Требования превращаются в задачи

План-агент режет файл требований на задачи. Правило размера: одна задача закрывается одним коммитом и имеет проверяемый критерий, тест или curl-сценарий. Критерий пишется рядом с задачей сразу, приёмка потом пойдёт по этим критериям.

Декомпозиция по docs/loyalty.md

@docs/loyalty.md Разбей требования на задачи: одна задача — один коммит, у каждой проверяемый критерий (тест или curl). Сохрани в TASKS.md со статусами

Пять задач: профиль баллов, начисление, списание, сгорание, README. Критерии взял из сценариев приёмки, порядок выстроен по зависимостям: списание опирается на профиль и начисление. Файл TASKS.md создан.

TASKS.md

# TASKS: программа лояльности

- [ ] 1. Профиль баллов в data/db.json: чтение и запись
      Критерий: заказ из сценария 1 заводит профиль с 156 баллами
- [ ] 2. Начисление: 1 балл за полные 10 ₽ оплаченной суммы
      Критерий: тест сценария 1 зелёный
- [ ] 3. Списание до 50% суммы в POST /api/orders (поле loyalty.spend)
      Критерий: тесты сценариев 2 и 3 зелёные
- [ ] 4. Сгорание через 30 дней после начисления
      Критерий: тест с фиксированной датой зелёный
- [ ] 5. README: раздел «Лояльность» с правилами и сценариями
      Критерий: правила и все 4 сценария описаны

Шаг 3. Цикл одной задачи

Задача живёт в своей сессии: /new перед началом, план в plan-агенте, правки в build (Shift+Tab из модуля 2). Критерий гоняешь на месте, статус в TASKS.md обновляет агент по твоей команде, коммит несёт номер задачи. Ревью субагентом из модуля 4 закрывает петлю.

Задача 2: сессия, план, правка, статус

/new

Сессия «Задача 2: начисление баллов»

Задача 2 из TASKS.md: начисление после оплаты. Составь план

План: сервис src/services/loyalty.ts с функцией начисления, вызов из POST /api/orders после подсчёта суммы, тест tests/loyalty-accrual.test.ts по сценарию 1 (156 баллов).

Делай по плану

Созданы src/services/loyalty.ts, tests/loyalty-accrual.test.ts; изменён src/routes/orders.ts

Прогони критерий задачи 2

npm test: все тесты зелёные, включая новый, начисление даёт 156 баллов. TASKS.md готов закрыть после твоей проверки.

Проверил. Закрой задачу и сделай коммит

TASKS.md: задача 2 [x]. Коммит feat(loyalty): задача 2 — начисление баллов.

Шаг 4. Приёмка по требованиям

Приёмка идёт по сценариям из docs/loyalty.md. Прогони каждый curl'ом, затем npm test целиком и обнови README задачей 5. Упавший сценарий означает дыру в требованиях: вопрос возвращается в docs/loyalty.md, задача в TASKS.md.

Приёмка: сценарии 1 и 2

# сценарий 1: заказ 1740 ₽ -> 1566 к оплате, 156 баллов
curl -s localhost:3000/api/orders -H "Content-Type: application/json" \
  -d '{"customer":"Аня","items":[{"menuId":"cap","quantity":3},{"menuId":"chz","quantity":2}]}'

# сценарий 2: заказ 840 ₽ со списанием 100 баллов -> 740 к оплате
curl -s localhost:3000/api/orders -H "Content-Type: application/json" \
  -d '{"customer":"Аня","items":[{"menuId":"chz","quantity":2}],"loyalty":{"spend":100}}'

npm test

Запуск сервера: npm run dev в соседнем терминале (модуль 1).

Практика модуля

Открой plan-агент в orders-api и попроси интервью по идее лояльности

Хочу программу лояльности. Прежде чем что-то предлагать, задай уточняющие вопросы, ответы зафиксируй в docs/loyalty.md

Добейся минимум пяти вопросов до первого предложения кода
Ответь фактами и числами, проверь созданный docs/loyalty.md

Попроси декомпозицию с критериями и сохрани TASKS.md

@docs/loyalty.md Разбей на задачи: одна задача — один коммит, у каждой проверяемый критерий. Сохрани в TASKS.md со статусами

Задачу 1 начни в новой сессии: план, правки, прогон критерия
Дока: TUI
```
/new
```
После проверки критерия закрой статус и сделай коммит с номером задачи
Погоняй готовые задачи через ревьюера из модуля 4
```
@reviewer сделай ревью src/services/loyalty.ts перед закрытием задачи
```

Приёмка: прогони сценарии 1 и 2 из ФТ curl'ом

curl -s localhost:3000/api/orders -H "Content-Type: application/json" \
  -d '{"customer":"Аня","items":[{"menuId":"cap","quantity":3},{"menuId":"chz","quantity":2}]}'

Прогони npm test целиком и обнови README задачей 5

Отмечено 0 из 9

Проверь себя

Вопрос 1 из 5

Прогресс квиза

Зачем требования держать в docs/loyalty.md, если все решения уже обсуждались в чате?

Файл — единственный источник требований, он переживает сессии и передаётся командеАгенту нужен файл, чтобы получить доступ к коду проектаФайл ускоряет ответы моделиЧат и файл равнозначны, файл просто аккуратнее выглядит

Шпаргалка модуля

Интервью

Роль интервьюера: «Прежде чем предлагать, задай вопросы»
Ответы фактами: числа и границы, решение сразу в файл требований

Декомпозиция

Задача: один коммит, один проверяемый критерий
TASKS.md: статусы [ ] / [x] рядом с критериями

Цикл задачи

/new: задача получает свою сессию
План до правок: plan-агент, потом build
Статус после проверки: человек проверил критерий, агент отметил
Коммит: номер задачи в сообщении

Название подхода

SDD: spec-driven development: спецификации в репозитории
OpenSpec, Spec Kit, BMAD, Kiro: готовые фреймворки цикла