# Spec Driven Development

> Пишет спецификацию до кода. Используй, когда начинаешь новый проект, фичу или существенное изменение и спецификации ещё нет. Используй, когда требования неясны, двусмысленны или существуют только в виде размытой идеи.

- Skill: `aleksandr-litvinenko/spec-driven-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aleksandr-litvinenko/spec-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aleksandr-litvinenko/spec-driven-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Aleksandr-Litvinenko (https://skillmd.com/u/aleksandr-litvinenko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aleksandr-litvinenko/spec-driven-development

---


# Разработка от спецификации

## Обзор

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

## Когда применять

- Начинается новый проект или фича
- Требования двусмысленны или неполны
- Изменение затрагивает несколько файлов или модулей
- Ты собираешься принять архитектурное решение
- Задача займёт больше 30 минут

**Когда НЕ применять:** однострочные правки, исправления опечаток или изменения, где требования однозначны и самодостаточны.

## Рабочий процесс с воротами

В разработке от спецификации четыре фазы. Не переходи к следующей, пока текущая не подтверждена.

```
СПЕЦИФИКАЦИЯ ──→ ПЛАН ──→ ЗАДАЧИ ──→ РЕАЛИЗАЦИЯ
      │            │         │           │
      ▼            ▼         ▼           ▼
   человек      человек   человек     человек
   смотрит      смотрит   смотрит     смотрит
```

### Фаза 1: Спецификация

Начни с общего видения. Задавай человеку уточняющие вопросы, пока требования не станут конкретными.

**Сразу проговори допущения.** Прежде чем писать содержимое спеки, перечисли, из чего ты исходишь:

```
ДОПУЩЕНИЯ, КОТОРЫЕ Я ДЕЛАЮ:
1. Это веб-приложение (не нативное мобильное)
2. Аутентификация на сессионных куках (не JWT)
3. База — PostgreSQL (сужу по существующей схеме Prisma)
4. Целимся только в современные браузеры (без IE11)
→ Поправьте сейчас, иначе я исхожу из этого.
```

Не закрывай неоднозначные требования молча. Весь смысл спеки — вытащить недопонимание наружу *до* того, как написан код, а допущения — самая опасная форма недопонимания.

**Напиши документ спеки, покрыв шесть базовых областей:**

1. **Цель** — что мы строим и зачем? Кто пользователь? Как выглядит успех?

2. **Команды** — полные исполняемые команды с флагами, а не просто названия инструментов.
   ```
   Сборка: npm run build
   Тесты:  npm test -- --coverage
   Линтер: npm run lint --fix
   Разработка: npm run dev
   ```

3. **Структура проекта** — где лежит исходный код, куда идут тесты, где документация.
   ```
   src/           → Исходный код приложения
   src/components → React-компоненты
   src/lib        → Общие утилиты
   tests/         → Юнит- и интеграционные тесты
   e2e/           → Сквозные тесты
   docs/          → Документация
   ```

4. **Стиль кода** — один настоящий фрагмент кода, показывающий стиль, лучше трёх абзацев его описания. Включи соглашения об именовании, правила форматирования и примеры хорошего результата.

5. **Стратегия тестирования** — какой фреймворк, где лежат тесты, ожидания по покрытию, какие уровни тестов под какие задачи.

6. **Границы** — трёхуровневая система:
   - **Всегда делать:** гонять тесты перед коммитом, следовать соглашениям об именовании, валидировать ввод
   - **Сначала спросить:** изменения схемы БД, добавление зависимостей, правка конфига CI
   - **Никогда не делать:** коммитить секреты, править каталоги вендоров, удалять падающие тесты без согласования

**Шаблон спеки:**

```markdown
# Спека: [Название проекта/фичи]

## Цель
[Что строим и зачем. Пользовательские истории или критерии приёмки.]

## Технологии
[Фреймворк, язык, ключевые зависимости с версиями]

## Команды
[Сборка, тесты, линтер, дев-режим — полные команды]

## Структура проекта
[Раскладка каталогов с описаниями]

## Стиль кода
[Пример фрагмента + ключевые соглашения]

## Стратегия тестирования
[Фреймворк, расположение тестов, требования к покрытию, уровни тестов]

## Границы
- Всегда: [...]
- Сначала спросить: [...]
- Никогда: [...]

## Критерии успеха
[Как поймём, что готово — конкретные проверяемые условия]

## Открытые вопросы
[Всё нерешённое, что требует участия человека]
```

**Переформулируй указания в критерии успеха.** Получив размытое требование, переведи его в конкретные условия:

```
ТРЕБОВАНИЕ: «Сделай дашборд быстрее»

ПЕРЕФОРМУЛИРОВАННЫЕ КРИТЕРИИ УСПЕХА:
- LCP дашборда < 2,5 с на 4G-соединении
- Начальная загрузка данных укладывается в < 500 мс
- Никаких сдвигов вёрстки при загрузке (CLS < 0,1)
→ Это верные цели?
```

Так ты сможешь итерироваться, повторять попытки и решать задачу к понятной цели, а не гадать, что значит «быстрее».

### Фаза 2: План

Имея подтверждённую спеку, составь технический план реализации:

1. Определи основные компоненты и их зависимости
2. Определи порядок реализации (что должно быть построено первым)
3. Отметь риски и способы их снижения
4. Определи, что можно делать параллельно, а что строго последовательно
5. Задай точки проверки между фазами

> Механику построения графа зависимостей и вертикальной нарезки бери из `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`.

**Шаблон задачи:**
```markdown
- [ ] Задача: [Описание]
  - Приёмка: [Что должно быть истинно по завершении]
  - Проверка: [Как подтвердить — команда теста, сборка, ручная проверка]
  - Файлы: [Какие файлы будут затронуты]
```

### Фаза 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 часов. |
| «Требования всё равно поменяются» | Именно поэтому спека — живой документ. Устаревшая спека всё равно лучше, чем никакой. |
| «Пользователь знает, чего хочет» | Даже в ясной просьбе есть неявные допущения. Спека их вытаскивает. |

## Тревожные признаки

- Начинаешь писать код, не имея никаких письменных требований
- Спрашиваешь «просто начинать делать?» до того, как прояснено, что значит «готово»
- Реализуешь фичи, не упомянутые ни в спеке, ни в списке задач
- Принимаешь архитектурные решения, не фиксируя их
- Пропускаешь спеку, потому что «и так очевидно, что строить»

## Проверка

Прежде чем переходить к реализации, убедись:

- [ ] Спека покрывает все шесть базовых областей
- [ ] Человек посмотрел и утвердил спеку
- [ ] Критерии успеха конкретны и проверяемы
- [ ] Границы (Всегда / Сначала спросить / Никогда) определены
- [ ] Спека сохранена в файл в репозитории