Процесс фичи
Главный принцип: чем меньше решений агент принимает сам, тем стабильнее
результат. Каждая фаза заканчивается артефактом в
docs/features/<slug>/ и проверкой («воротами»). Там, где помечено,
переход дальше — только после подтверждения человека.
Как писать сам код — fsd-frontend; проверка на мусор — anti-slop-review;
вход и сессия — frontend-auth-session.
1. Фазы
| # | Фаза | Артефакт | Утверждает | Ворота |
|---|---|---|---|---|
| 0 | Подготовка | ветка | — | Рабочее дерево чистое; после установки зависимостей и миграций — /clear |
| 1 | PRD | prd.md | человек | Non-Goals заполнены; критерии проверяемые; нет технических решений |
| 2 | Спецификация | spec.md, до 150 строк | человек | Покрывает все критерии PRD и ничего сверх |
| 3 | Задачи | tasks.md | человек | Одна задача — один коммит; первая — tracer bullet |
| 4 | Исследование | журнал в tasks.md | — | Только чтение; найдено, что переиспользовать |
| 5 | Tracer bullet | коммит | — | Один сценарий проходит насквозь и виден в браузере |
| 6 | Сборка | коммит на задачу | — | Тест сначала для логики; pnpm check зелёный |
| 7 | Ревью | отчёт reviewer | человек по находкам | Подтверждённые находки исправлены |
| 8 | Браузер | e2e на критичный путь | — | Сценарии PRD проходят без ошибок в консоли |
Маленькая задача (один коммит, без нового поведения для пользователя) пропускает фазы 1–3, но Non-Goals всё равно записываются в описание задачи. Пропуск фазы называется вслух, а не происходит молча.
2. PRD
Шаблон — docs/features/_template/prd.md.
- Агент составляет черновик из запроса и спрашивает только то, без чего нельзя продолжить. Остальное — допущения в «Открытых вопросах», которые человек подтверждает при утверждении.
- Non-Goals обязательны. Перечисли то, что агенту захочется сделать «заодно»: адаптив под новые размеры, анимации, i18n, кэширование, админку, рефакторинг соседнего кода. Без этого списка фича разрастается.
- Критерии готовности проверяемые: «Дано / Когда / Тогда», а не «удобно» и «быстро».
- Никаких библиотек, файлов и схем: это вопрос «что и зачем», не «как».
3. Спецификация
Шаблон — docs/features/_template/spec.md.
- До 150 строк. Пишет агент, утверждает человек. Длинная сгенерированная спецификация хуже никакой: она забивает контекст и размывает решения.
- Перед написанием — короткий read-only обзор затронутых слоёв: что уже есть, что переиспользовать.
- Содержит: где живёт код (слои, слайсы), контракты данных (схемы zod,
маппинг DTO), API (вход, выход, ошибки →
kind), состояния UI, граничные случаи, приёмочные сценарии с уровнем теста. - Спецификация живёт вместе с кодом. Изменилось поведение — правится
spec.mdв том же коммите. Код, расходящийся со спецификацией, — дефект одного из двух.
4. Задачи
Шаблон — docs/features/_template/tasks.md.
- Одна задача — один коммит, после которого проект собирается и проверки проходят. Если агент зашёл в тупик, откат на предыдущий коммит дешевле спора с моделью.
- Задача помещается в одну сессию; у каждой — «готово, когда».
- Первая задача — tracer bullet, дальше — состояния, граничные случаи, полировка.
5. Исследование (только чтение)
Перед каждой задачей, без правок файлов:
AGENTS.mdзатронутых папок;- существующий код, который решает похожее (
rgпо именам и контрактам); - контракты и типы, на которые задача опирается.
Если найденное понадобится позже — 2–3 строки в журнал tasks.md.
6. Tracer bullet
Один сценарий насквозь: маршрут → страница → фича или сущность →
request() → route handler или бэкенд → результат на экране.
- Это production-код, а не прототип: правильные слои, настоящие контракты из спецификации.
- Сознательно без: подробной валидации, полировки состояний загрузки и ошибок, стилей, граничных случаев.
- Бэкенд не готов — обработчик MSW или route handler, отдающий данные по
контракту из спецификации; это отмечается в
tasks.md. - Проверка — в браузере: сценарий проходит и в консоли нет ошибок.
7. Сборка
- Логика — тест сначала: чистые функции, сторы, маппинг ответов, хуки с ветвлением. Тест должен упасть по ожидаемой причине, потом — код. Тест, написанный после кода, склонен проверять то, что код делает, а не то, что требуется.
- Вёрстка и стили — без теста заранее: их проверяет браузер (фаза 8), критичный путь закрывается e2e.
- После задачи:
pnpm check, коммит (lint-staged проверит изменённые файлы). - Остановка: три неудачные попытки исправить одно и то же — стоп. Опиши человеку, что пробовал и какая гипотеза. Не подгоняй тесты под код, не отключай правила линтера, не ослабляй типы.
- Всё, что вне задачи, — в журнал «потом», а не в этот коммит.
8. Ревью
- Субагент
reviewer(.claude/agents/reviewer.md) с чистым контекстом: передай путь кprd.mdиspec.mdи диапазон коммитов; diff он прочитает сам. Автор кода свои ошибки видит хуже: в его контексте — аргументы, почему решение верное. - Подтверждённые находки исправляются, спорные — решает человек.
- Безопасность смотрит и человек: вход, сессии, редиректы, cookie, пользовательский ввод в HTML. Зелёные проверки этого не гарантируют: на практике открытый редирект проходил тесты, а нечитаемая страница ошибки — линтер.
9. Браузер
- Next.js: скилл
next-dev-loopсagent-browser, если установлен; иначе Playwright или Chrome DevTools MCP. - Пройди сценарии PRD, включая негативные: пустые данные, ошибка сети, повторная отправка. Смотри консоль и статусы запросов.
- Для UI — светлая и тёмная тема, ширина телефона.
- Критичный путь — e2e-тест в
e2e/. - Готово, когда каждый критерий PRD проверен; в итоговом сообщении — список критериев и как проверен каждый.
10. Контекст
- Состояние работы живёт в
docs/features/<slug>/, а не в переписке: новую сессию начинай с чтенияprd.md,spec.md,tasks.md. - После шумных шагов (установка, миграции, длинные логи) —
/clear. - Параллельные эксперименты — в
git worktree, не в рабочей ветке.
11. Чего не делать
- Бесконечные уточняющие вопросы: спрашивай то, что блокирует, остальное — допущения в PRD.
- Оркестраторы из многих агентов: достаточно исполнителя и ревьюера.
- Спецификации и документация, которые никто не утверждал и не читает.
- Молчаливый пропуск фаз и «заодно поправил».