GitHub Spec Kit hands-on

Spec Kit — открытый тулкит GitHub, который оформляет SDD в конвейер слэш-команд для вашего агента: поддерживаются Claude Code, GitHub Copilot, Gemini CLI, Cursor и другие. Инициализация через uv:

uvx --from git+https://github.com/github/spec-kit.git specify init my-app

Команда разворачивает структуру каталогов, шаблоны и слэш-команды в формате выбранного агента. Дальше вся работа идёт из чата агента.

Первый шаг — /constitution: неизменяемые принципы проекта, которым обязаны подчиняться все последующие спеки и планы. Constitution отвечает не за фичу, а за проект в целом:

- Стек: TypeScript strict, Fastify, MongoDB. Новые языки — только через ADR.
- Каждый эндпоинт покрыт интеграционным тестом до мёржа.
- Никаких секретов в коде и логах; конфигурация — через env.
- Ошибки наружу — только типизированные, с кодом и человекочитаемым текстом.

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

Команда /specify принимает описание фичи и разворачивает его в структурированную спеку — в каталоге вида specs/001-csv-export/ появляется spec.md с user stories, функциональными требованиями и критериями приёмки. Ключевая дисциплина этого шага: описывайте «что» и «зачем», а не стек и архитектуру. Пример хорошего входа:

/specify Бухгалтеры выгружают месячный отчёт в CSV.
Сейчас копируют руками — 40 минут и ошибки.
Доступ только ролям accountant и admin.
Файл открывается в Excel. Отчёты до 100 000 строк.

Сгенерированную спеку обязательно читать: это черновик, а не результат. Агент честно помечает места, где ему не хватило информации, маркерами [NEEDS CLARIFICATION] — например, «что делать при пустом отчёте?» или «нужна ли история экспортов?».

Команда /clarify проходит по этим маркерам и задаёт вам вопросы по одному. Это самый недооценённый шаг конвейера: соблазн пропустить его велик, но каждый неотвеченный вопрос превратится в молчаливую догадку агента на этапе реализации — и всплывёт на приёмке, где исправление стоит в разы дороже. Правило: implement не запускается, пока в спеке остаётся хоть один открытый маркер. Отвечайте коротко и решением, а не рассуждением: «пустой отчёт — файл с одними заголовками, не ошибка».

Шаг /plan — первое место, где появляется «как». Агент читает спеку и constitution и генерирует план: стек, затрагиваемые модули, модель данных, контракты API, стратегию тестирования. Здесь уместно всё то, что мы выгоняли из спеки: выбор библиотеки, схема таблицы, структура каталогов. План — тоже артефакт для ревью: проверьте, что он не нарушает constitution и не изобретает лишнего. Типичная правка на этом шаге: «не надо новой очереди сообщений, у нас уже есть воркер».

Шаг /tasks нарезает план на маленькие проверяемые задачи с зависимостями:

- [ ] T01. Миграция: поле export_permissions в roles (после: —)
- [ ] T02. Эндпоинт POST /api/reports/:id/export, 403 для
      ролей без права (после: T01)
- [ ] T03. Генерация CSV стримом, UTF-8 with BOM (после: T02)
- [ ] T04. Интеграционные тесты AC-1..AC-4 (после: T03)
- [ ] T05. Кнопка экспорта в UI, скрыта без права (после: T02)

Хорошая задача — размером в один осмысленный коммит и с проверяемым итогом. Обратите внимание на T04: критерии приёмки из спеки явно превращаются в тесты, это та самая трассировка, которую мы разберём в следующем уроке. Если какая-то задача не сводится к критериям спеки — либо она лишняя, либо в спеке дыра. Оба открытия дешевле сделать сейчас, чем после генерации кода.

Команда /implement выполняет задачи по порядку с учётом зависимостей: агент пишет код, гоняет тесты, отмечает выполненное. Ваша роль смещается с «писать» на «принимать». И здесь главная дисциплина курса: принимайте по критериям спеки, а не по ощущению «вроде работает». Откройте spec.md и пройдите критерии один за другим: AC-1 — выполнен, воспроизвёл локально; AC-2 — выполнен, тест есть; AC-5 — не выполнен, при обрыве соединения файл остаётся наполовину записанным.

Когда находится расхождение, есть два пути, и выбор между ними — суть SDD. Если код не соответствует спеке — это дефект реализации: возвращаете агенту задачу с указанием критерия. Если же вы понимаете, что спека была неполной («мы не подумали про повторный экспорт того же отчёта»), — сначала правится спека, затем план и задачи, затем код. Молча починить код, оставив спеку старой, — значит своими руками создать drift, с которым будет бороться пятый урок.

Практические привычки: коммит на задачу, а не один мега-коммит на фичу — так ревью и откат остаются управляемыми; артефакты конвейера (spec.md, plan.md, tasks.md) коммитятся вместе с кодом в ту же ветку; в описание PR идёт ссылка на спеку и чек-лист критериев. После двух-трёх фич конвейер занимает меньше времени, чем привычные циклы ре-промптинга, — потому что переделок становится радикально меньше.