Spec Kit: приёмы работы, когда спека — источник истины, а код — следствие

Проблема

Наивный вайб-кодинг: один большой промпт → агент сразу пишет код → через час структура непонятна, границы размыты, откат дорогой. На ретро звучит «ИИ не тянет архитектуру» — хотя не было зафиксированного «что строим» и явных открытых вопросов в постановке.

GitHub Spec Kit переводит это в репозиторий: нумерованные specs/00N-*, clarify в spec.md, plan и tasks — реализация после согласования. Ниже — как не превратить SDD в ритуал с пустыми файлами.

Методика

1. Конституция репозитория: .specify/

Перед первой фичей — шаблоны и память проекта, а не «с нуля в чате».

• templates/ — spec-template.md, plan-template.md, tasks-template.md, checklist-template.md: агент не выдумывает структуру каждый раз.
• memory/ — устойчивые решения (стек, запреты, соглашения). Меньше противоречий между фичами 001-*, 004-*, 005-*.
• scripts/ — обвязка Spec Kit CLI (specify, plan, tasks и т.д.).

Приём: один раз настроить templates под свой домен (микросервисы, события, API keys) — дальше каждая фича наследует форму, а не стиль случайного промпта.

2. Одна фича — одна папка в specs/

Нумерация NNN-короткое-имя (например 001-model-service, 004-order-manager): параллельные ветки работ, понятный scope в PR и в голове.

Внутри фичи — цепочка файлов, не один SPEC.md на всё:

Приём: не начинать implement, пока нет plan + tasks; иначе агент строит то, что проще написать, а не то, что согласовано.

3. Clarify — отдельная фаза, не «уточни в чате»

В spec.md секция Clarifications (сессии с датой): вопрос → ответ → зафиксированное решение. Маркеры [NEEDS CLARIFICATION] в тексте спеки запрещают молчаливые допущения.

Пример логики (без привязки к домену): «какой формат сообщений в очереди?» → явный ответ в Clarifications → дальше plan и contracts ссылаются на него.

Приём: пока в spec остаются незакрытые [NEEDS CLARIFICATION], не переходить к plan — иначе план кодирует догадки.

4. Plan с обоснованием, не со списком технологий

В plan каждое нетривиальное решение: альтернатива → почему отвергли → что приняли. Агент при implement тянет не «среднюю температуру по интернету», а ваш контекст из spec + plan.

Приём: спорный пункт (очередь, хранение моделей, auth между сервисами) — только через запись в plan; иначе на code review нечего обсуждать, кроме диффа.

5. Tasks как граф, не плоский TODO

tasks.md: зависимости между задачами, явно выделенное «можно параллелить». Implement по одной задаче с коммитом/тестом — проще откат и проще понять, где агент сошёл с рельс.

Приём: после каждой задачи — прогон checklist фичи; не «всё сразу в конце».

6. Analyze — петля согласованности, не одноразовый gate

Spec Kit предполагает проверку: spec ↔ plan ↔ tasks — противоречия, дубли, пропущенные AC. Это итерация, не галочка перед релизом.

Приём: при смене spec после начала кода — сначала analyze и правка plan/tasks, потом код; иначе drift между «истиной» и репозиторием.

7. Мультисервис: contracts раньше кода

Когда в одном репо несколько сервисов (ws-gateway, order-manager, …), contracts/ в каждой фиче фиксируют сообщения и API до реализации. Иначе второй сервис «догоняет» формат первого в проде.

Приём: общие типы событий и версионирование — в clarify/plan; в #6 это не разбирается (один продуктовый сервис ML).

8. Анти-паттерн, который Spec Kit снимает

Артефакт

Иллюстрация: github.com/dobryakov/ytrader-bybit — публичный мультисервисный репозиторий с полным циклом Spec Kit: конституция .specify/, нумерованные specs/00N-*, цепочка spec.md → plan.md → tasks.md и contracts/ между сервисами. Разбор опирается на форму артефактов и их согласованность, а не на предметную область.

Для читателя достаточно клонировать репо и пройти один feature-folder по цепочке файлов сверху вниз — без запуска всей системы.

Для кого и почему

Architect и CTO, которые вводят агентов в разработку: не «какой фреймворк выбрать», а дисциплина артефактов, при которой агент усиливает, а не подменяет проектирование. Если вход ещё в Jira — сначала clarify gate на intake (#11); в репозитории — этот разбор. Дополняет cursor rules в IDE (#7) и eval в релизе (#10): Spec Kit — до кода; eval — после.

Отличие от #6: там — сквозной пример ML-сервиса и ответ на скепсис к ML в проде; здесь — учебник приёмов Spec Kit без углубления в feature store и модели.

Ссылки:

• github.com/github/spec-kit — upstream
• github.com/dobryakov/ytrader-bybit — иллюстрация (мультисервис, contracts)
• разбор #6 — ML-сервис в той же серии