Aleksandr-Litvinenko Разработка от спецификации
Обзор
Пиши структурированную спецификацию до того, как напишешь хоть строчку кода. Спека — это общий источник истины между тобой и инженером-человеком: она определяет, что мы строим, зачем и как поймём, что готово. Код без спеки — это гадание.
Когда применять
- Начинается новый проект или фича
- Требования двусмысленны или неполны
- Изменение затрагивает несколько файлов или модулей
- Ты собираешься принять архитектурное решение
- Задача займёт больше 30 минут
Когда НЕ применять: однострочные правки, исправления опечаток или изменения, где требования однозначны и самодостаточны.
Рабочий процесс с воротами
В разработке от спецификации четыре фазы. Не переходи к следующей, пока текущая не подтверждена.
СПЕЦИФИКАЦИЯ ──→ ПЛАН ──→ ЗАДАЧИ ──→ РЕАЛИЗАЦИЯ
│ │ │ │
▼ ▼ ▼ ▼
человек человек человек человек
смотрит смотрит смотрит смотрит
Фаза 1: Спецификация
Начни с общего видения. Задавай человеку уточняющие вопросы, пока требования не станут конкретными.
Сразу проговори допущения. Прежде чем писать содержимое спеки, перечисли, из чего ты исходишь:
ДОПУЩЕНИЯ, КОТОРЫЕ Я ДЕЛАЮ:
1. Это веб-приложение (не нативное мобильное)
2. Аутентификация на сессионных куках (не JWT)
3. База — PostgreSQL (сужу по существующей схеме Prisma)
4. Целимся только в современные браузеры (без IE11)
→ Поправьте сейчас, иначе я исхожу из этого.
Не закрывай неоднозначные требования молча. Весь смысл спеки — вытащить недопонимание наружу до того, как написан код, а допущения — самая опасная форма недопонимания.
Напиши документ спеки, покрыв шесть базовых областей:
Цель — что мы строим и зачем? Кто пользователь? Как выглядит успех?
Команды — полные исполняемые команды с флагами, а не просто названия инструментов.
Сборка: npm run build Тесты: npm test -- --coverage Линтер: npm run lint --fix Разработка: npm run devСтруктура проекта — где лежит исходный код, куда идут тесты, где документация.
src/ → Исходный код приложения src/components → React-компоненты src/lib → Общие утилиты tests/ → Юнит- и интеграционные тесты e2e/ → Сквозные тесты docs/ → ДокументацияСтиль кода — один настоящий фрагмент кода, показывающий стиль, лучше трёх абзацев его описания. Включи соглашения об именовании, правила форматирования и примеры хорошего результата.
Стратегия тестирования — какой фреймворк, где лежат тесты, ожидания по покрытию, какие уровни тестов под какие задачи.
Границы — трёхуровневая система:
- Всегда делать: гонять тесты перед коммитом, следовать соглашениям об именовании, валидировать ввод
- Сначала спросить: изменения схемы БД, добавление зависимостей, правка конфига CI
- Никогда не делать: коммитить секреты, править каталоги вендоров, удалять падающие тесты без согласования
Шаблон спеки:
# Спека: [Название проекта/фичи]
## Цель
[Что строим и зачем. Пользовательские истории или критерии приёмки.]
## Технологии
[Фреймворк, язык, ключевые зависимости с версиями]
## Команды
[Сборка, тесты, линтер, дев-режим — полные команды]
## Структура проекта
[Раскладка каталогов с описаниями]
## Стиль кода
[Пример фрагмента + ключевые соглашения]
## Стратегия тестирования
[Фреймворк, расположение тестов, требования к покрытию, уровни тестов]
## Границы
- Всегда: [...]
- Сначала спросить: [...]
- Никогда: [...]
## Критерии успеха
[Как поймём, что готово — конкретные проверяемые условия]
## Открытые вопросы
[Всё нерешённое, что требует участия человека]
Переформулируй указания в критерии успеха. Получив размытое требование, переведи его в конкретные условия:
ТРЕБОВАНИЕ: «Сделай дашборд быстрее»
ПЕРЕФОРМУЛИРОВАННЫЕ КРИТЕРИИ УСПЕХА:
- LCP дашборда < 2,5 с на 4G-соединении
- Начальная загрузка данных укладывается в < 500 мс
- Никаких сдвигов вёрстки при загрузке (CLS < 0,1)
→ Это верные цели?
Так ты сможешь итерироваться, повторять попытки и решать задачу к понятной цели, а не гадать, что значит «быстрее».
Фаза 2: План
Имея подтверждённую спеку, составь технический план реализации:
- Определи основные компоненты и их зависимости
- Определи порядок реализации (что должно быть построено первым)
- Отметь риски и способы их снижения
- Определи, что можно делать параллельно, а что строго последовательно
- Задай точки проверки между фазами
Механику построения графа зависимостей и вертикальной нарезки бери из
planning-and-task-breakdown— это канонический источник. Пункты выше — краткая выжимка; при расхождении приоритет уplanning-and-task-breakdown.Соглашение о выводе: сохраняй план в
tasks/plan.md, а список задач — вtasks/todo.md, согласно соглашению команды/plan. Создайtasks/, если каталога нет. Последующие команды (/buildи другие) ожидают именно эти пути.
План должен быть пригоден для ревью: человек должен прочитать его и сказать «да, подход верный» либо «нет, поменяй X».
Фаза 3: Задачи
Разбей план на дискретные реализуемые задачи:
- Каждая задача должна закрываться за одну сфокусированную сессию
- У каждой задачи явные критерии приёмки
- Каждая задача включает шаг проверки (тест, сборка, ручная проверка)
- Задачи упорядочены по зависимостям, а не по субъективной важности
- Ни одна задача не должна требовать изменения более чем ~5 файлов
Полную механику определения размера задач и упорядочивания по зависимостям бери из
planning-and-task-breakdown— это канонический источник. Шаблон ниже — облегчённая встроенная форма; при расхождении приоритет уplanning-and-task-breakdown.
Шаблон задачи:
- [ ] Задача: [Описание]
- Приёмка: [Что должно быть истинно по завершении]
- Проверка: [Как подтвердить — команда теста, сборка, ручная проверка]
- Файлы: [Какие файлы будут затронуты]
Фаза 4: Реализация
Выполняй задачи по одной, следуя skills/incremental-implementation/SKILL.md (incremental-implementation) и skills/test-driven-development/SKILL.md (test-driven-development). Используй skills/context-engineering/SKILL.md (context-engineering), чтобы на каждом шаге подгружать нужные разделы спеки и исходники, а не заваливать агента всей спекой целиком.
Как поддерживать спеку живой
Спека — живой документ, а не разовый артефакт:
- Обновляй, когда меняются решения — если выяснилось, что модель данных надо менять, сначала обнови спеку, потом реализуй.
- Обновляй, когда меняются границы — добавленные или вырезанные фичи должны отражаться в спеке.
- Коммить спеку — её место в системе контроля версий рядом с кодом.
- Ссылайся на спеку в пулл-реквестах — давай ссылку на тот раздел спеки, который реализует конкретный PR.
Типовые самооправдания
| Самооправдание | Как на самом деле |
|---|---|
| «Тут всё просто, спека не нужна» | Простым задачам не нужны длинные спеки, но критерии приёмки нужны всё равно. Спека в две строки — нормально. |
| «Напишу спеку после кода» | Это документация, а не спецификация. Ценность спеки в том, что она заставляет добиться ясности до кода. |
| «Спека нас затормозит» | 15 минут на спеку экономят часы переделок. Водопад за 15 минут лучше отладки за 15 часов. |
| «Требования всё равно поменяются» | Именно поэтому спека — живой документ. Устаревшая спека всё равно лучше, чем никакой. |
| «Пользователь знает, чего хочет» | Даже в ясной просьбе есть неявные допущения. Спека их вытаскивает. |
Тревожные признаки
- Начинаешь писать код, не имея никаких письменных требований
- Спрашиваешь «просто начинать делать?» до того, как прояснено, что значит «готово»
- Реализуешь фичи, не упомянутые ни в спеке, ни в списке задач
- Принимаешь архитектурные решения, не фиксируя их
- Пропускаешь спеку, потому что «и так очевидно, что строить»
Проверка
Прежде чем переходить к реализации, убедись:
- Спека покрывает все шесть базовых областей
- Человек посмотрел и утвердил спеку
- Критерии успеха конкретны и проверяемы
- Границы (Всегда / Сначала спросить / Никогда) определены
- Спека сохранена в файл в репозитории