Spec Kit: спецификации как исполняемые артефакты

6 апреля 2026

Главный вопрос про Spec Kit - не «как поставить» и не «какие есть команды», а «в какой момент натуральный язык как способ давать задачу AI-агенту перестаёт работать и какую новую дисциплину нужно ввести, чтобы агент стабильно делал то, что от него хотят». Без структуры агент, получив фразу «добавь авторизацию через WebAuthn», сразу пишет код: выбирает библиотеки, проектирует API, создаёт миграции - и инженер видит результат только когда PR готов. Если выбор оказался неудачным, переделывать приходится всё. Spec Kit - реализация подхода Spec-Driven Development (SDD), который инвертирует модель: спецификация становится первичным артефактом, код - производным, а контроль человека встроен в переходы между фазами. Статья разбирает, когда этот подход оправдан, чем он отличается от TDD и BDD, какие антипаттерны убивают его на практике, и как устроен сам фреймворк - от установки до интеграций с Jira, GitHub и community-extensions.

Подробнее о Spec-Driven Development как подходе к SDLC и сравнение с другими фреймворками (BMAD, OpenSpec, cc-sdd, SPECTRE, IDD) - в статье SDLC для AI-агентов.

Когда применять Spec Kit: рамка решения

Spec Kit - не универсальная замена «обычной» работе с AI-агентом. У него есть себестоимость: команда учит шаблоны, инженер пишет constitution, ревьюит spec.md и plan.md, обновляет artifacts при изменениях. На маленькой задаче это overhead. На большой - страховка от того, что агент сделает не то и переделать придётся в три раза дороже. Решение «применять или нет» сводится к нескольким параметрам, которые легко проверить заранее.

Первый параметр - ширина решений, которые агент должен принять самостоятельно. Если задача звучит как «добавь endpoint, который возвращает текущего пользователя по сессии», агент не принимает архитектурных решений - он пишет код в существующих рамках. Spec Kit здесь почти ничего не добавит, кроме шума. Если задача - «спроектируй и реализуй систему фич-флагов», агент будет принимать десятки решений: где хранить флаги, как обновлять без рестарта, как изолировать по окружениям, как тестировать. Каждое из этих решений человек захочет проконтролировать до того, как агент превратит его в код. SDD создаёт промежуточный артефакт (spec.md, plan.md), на котором это контроль возможен.

Второй параметр - стоимость переделки. В прототипе, который через неделю выкинется, неудачное решение агента обходится дёшево - переписать. В production-системе, где код запускают в 17 окружений и от него зависят несколько команд, неудачное решение стоит недели рефакторинга. Чем выше стоимость переделки, тем раньше нужен контроль, и тем оправданнее spec-фаза, на которой ошибка в выборе библиотеки ловится в одном абзаце текста, а не в 1500 строках кода.

Третий параметр - число людей в петле обратной связи. Если агент работает один на один с автором задачи, лишние артефакты избыточны - человек и так держит контекст в голове. Если в задаче участвуют PM, дизайнер, smartass-инженер из соседней команды и QA, спецификация становится протоколом договорённостей. Без неё каждый интерпретирует задачу по-своему, и агент усиливает расхождения, потому что код от агента выглядит авторитетно.

Четвёртый параметр - длительность работы над фичей. Если фича делается за один сеанс агента, контекст не теряется. Если работа растягивается на дни и переключается между сеансами или агентами, артефакты становятся способом перенести контекст. Spec.md, plan.md, tasks.md - это компактное представление того, до чего команда договорилась, в формате, который любой агент может прочитать и продолжить с нужного места.

Сопоставление параметров и режима работы:

Сценарий	Решения агента	Стоимость переделки	Людей в петле	Длительность	Spec Kit
Точечная правка в существующем коде	Узкие, в рамках конвенций	Низкая	1-2	Один сеанс	Не нужен; обычный prompt
Прототип для гипотезы	Широкие, но дешёвые	Низкая	1-2	Дни	Не нужен; spec замедлит исследование
Новая фича в production-системе	Архитектурные	Высокая	3-5	Дни-недели	Оправдан; основной use case
Новый сервис / модуль	Системные	Очень высокая	4+	Недели	Оправдан; constitution особенно важна
Compliance-задача (медицина, финансы)	Регламентированные	Регуляторная	5+ (включая аудитора)	Недели-месяцы	Обязателен; V-Model extension

SDD vs. TDD vs. BDD: исторический контекст и выбор

Spec-Driven Development - не первая попытка сделать спецификацию первичным артефактом. Эта линия мышления тянется как минимум с конца 1980-х, и каждое следующее поколение реагировало на ограничения предыдущего. Полезно держать в голове родословную, потому что многие антипаттерны SDD - те же самые, на которых ломались предшественники.

Design by Contract (Bertrand Meyer, 1988-1997)

Бертран Мейер сформулировал Design by Contract в работе над языком Eiffel в конце 1980-х: каждый метод имеет precondition (что должно быть истинно до вызова), postcondition (что гарантирует метод после вызова) и инвариант класса. Контракт встроен в синтаксис языка и проверяется во время выполнения. Идея описана в книге «Object-Oriented Software Construction» (Prentice Hall, 1-е издание 1988, второе расширенное издание - 1997). Это первая попытка сделать спецификацию исполняемой: контракт - не комментарий в коде, а часть программы, которая падает, если её нарушают.

На практике DbC прижился ограниченно: писать contracts отдельно от кода большинство команд считало излишним overhead-ом, а Eiffel так и остался нишевым языком. Но идея «спецификация - не документ, а исполняемый артефакт» прямо унаследована современным SDD.

Test-Driven Development (Kent Beck, 1999-2002)

Кент Бек переоткрыл практику «сначала тест, потом код» в Extreme Programming и оформил её в книге «Test-Driven Development: By Example» (Addison-Wesley, 2002). Цикл red-green-refactor стал почти каноном: написать падающий тест, написать минимум кода, чтобы тест прошёл, рефакторить. Тест здесь играет роль исполняемой спецификации поведения - но только на уровне юнита.

Сильная сторона TDD - быстрая обратная связь и регрессионный safety net. Слабая - тест описывает «как» (вызвать функцию X с аргументами Y и проверить Z), а не «что и зачем». Спецификация на уровне продуктовой фичи в TDD не формализована - её приходится держать в голове или в отдельной документации, которая быстро устаревает.

Behavior-Driven Development (Dan North, 2006)

Дэн Норт ввёл термин BDD в статье «Introducing BDD» (Better Software, March 2006), чтобы решить понятную проблему обучения TDD: новички не понимали, какой тест писать первым и в каких словах его формулировать. BDD заменил язык тестов на язык поведения: вместо «test_calculate_total» - «Given пустая корзина, When добавляется товар, Then total равен цене товара». Формат Given/When/Then стал стандартом, его подхватил Cucumber (Aslak Hellesoy) и потом множество других инструментов.

BDD расширил спецификацию с уровня юнита до уровня поведения системы и сделал её доступной для не-инженеров. Бизнес-аналитик может прочитать сценарий, инженер - его реализовать, тест - его проверить. Идея, что текстовое описание сценария становится исполняемым артефактом, прямо предшествует SDD. Spec Kit использует ту же модель в шаблоне spec.md (User Stories с acceptance scenarios в формате Given/When/Then).

Spec-as-API (OpenAPI, 2010-е)

Параллельно с BDD развивалась линия «спецификация интерфейса как первичный артефакт». Swagger (Tony Tam, 2011) и потом OpenAPI Initiative под Linux Foundation (с 2015) предложили описывать REST API в декларативном формате (YAML/JSON), из которого генерируется и документация, и клиентские библиотеки, и mock-сервер. В публикациях Brandur Leach (инженера Stripe, brandur.org) описывается, как на Stripe OpenAPI spec стал внутренним источником истины для API: код API генерируется из spec, тесты проверяют, что реализация соответствует spec, документация публикуется из spec автоматически.

Это уже спецификация на уровне системы, не отдельного теста. Слабое место - OpenAPI описывает только интерфейс, не поведение, не бизнес-правила, не архитектурные решения. SDD расширяет идею с интерфейса на всю фичу.

Spec-Driven Development (GitHub Spec Kit, 2024-2025)

SDD появляется в эпоху AI-агентов как ответ на новый класс проблем. Команда GitHub spec-kit (открытый репозиторий github/spec-kit) формулирует подход в README и в собственных skill-шаблонах: сначала specify описывает что и зачем, потом plan описывает как, потом tasks декомпозирует, и только после этого implement пишет код. Каждая фаза - артефакт, который человек ревьюит до того, как агент перейдёт к следующей.

Технически SDD наследует у предшественников: User Stories и Given/When/Then - из BDD; «спецификация как исполняемый артефакт» - из DbC и OpenAPI; обязательность тестов до кода - из TDD (часто прописывается в constitution). Новое - то, что спецификация теперь исполняется не компилятором и не runtime, а LLM-агентом. Это меняет требования к структуре spec.md: текст должен быть достаточно чётким, чтобы агент сгенерировал из него ожидаемый код, и достаточно гибким, чтобы человек мог его быстро ревьюить.

Когда какой подход применять

Подход	Уровень спецификации	Кто пишет	Кто исполняет	Когда уместен
DbC	Метод/класс	Инженер	Runtime	Критические инварианты, библиотечный код
TDD	Юнит/метод	Инженер	Test runner	Любая разработка, где тесты применимы
BDD	Сценарий/поведение	Инженер + продукт	Cucumber-подобные runners	Сложная бизнес-логика, регрессии важны
OpenAPI / spec-as-API	Интерфейс	Инженер	Code generator + проверки	API между командами или клиентами
SDD	Фича целиком	Инженер + AI-агент совместно	AI-агент	Работа с агентами на нетривиальных задачах

Подходы не взаимоисключающие. Хорошо работающая команда обычно использует несколько одновременно: SDD на уровне фичи (Spec Kit), BDD-сценарии внутри spec.md (User Stories и acceptance criteria), TDD на уровне реализации (тесты до кода как принцип constitution), OpenAPI для контрактов между сервисами. Spec Kit явно поддерживает это наслоение: шаблон spec.md содержит и BDD-стилизованные сценарии, и success criteria; шаблон constitution часто содержит NON-NEGOTIABLE Test-First принцип.

Реальное внедрение: greenfield, brownfield, гибрид

Документация Spec Kit (и большинство демо-видео) показывают workflow на чистом проекте: specify init my-project, потом по фазам до production. На практике 80% задач - это работа в существующем коде, где spec нужно вписывать в чужие конвенции. Ниже разобраны три типичных режима внедрения с примерами того, как они выглядят в работе живой команды.

Greenfield: новая фича с нуля в новом проекте

Самый простой случай и тот, для которого Spec Kit задумывался. Команда инициализирует проект, пишет constitution, потом по каждой фиче проходит шесть фаз. Constitution здесь играет роль «генетического кода» - агент использует его при каждом /speckit-plan, чтобы выбирать совместимые с принципами решения.

Реальный пример (стилизованный пример на основе типичных паттернов): стартап на 3 инженеров запускает SaaS на TypeScript + Next.js + Postgres. Constitution фиксирует: TDD не обязателен (стартап оптимизирует время до фидбэка), но интеграционные тесты на критических флоу обязательны; стек гвоздями (TypeScript, Next.js App Router, Drizzle ORM, Postgres, Vercel deploy); монорепа не нужна, отдельный backend через tRPC. Дальше каждая фича начинается с /speckit-specify: описание из 5-10 предложений, агент генерирует spec.md с user stories и success criteria, инженер ревьюит, дальше /speckit-plan, /speckit-tasks, /speckit-implement.

Эффект, который команды стабильно фиксируют в community discussions: первая фича занимает на 30-50% больше времени, чем «обычная работа с агентом», потому что инженер учится формулировать spec и отвыкает писать код руками. К пятой-десятой фиче скорость выравнивается, а доля переделок падает. Точные цифры публично не агрегированы (Spec Kit вышел в 2024, репрезентативной статистики пока нет), но самим репозиторием GitHub spec-kit и по тональности discussions это типичный паттерн.

Brownfield: фича в существующем production-проекте

Самый частый сценарий и самый болезненный. Документация Spec Kit фокусировалась на greenfield почти до 2025; brownfield-workflow задокументирован после issue #1285. Главные сложности:

• Constitution для существующего проекта. Дефолтный шаблон описывает идеальные принципы (Library-First, NON-NEGOTIABLE TDD, Simplicity - не более 3 проектов). На пятилетнем проекте с 400k строк это смешно. Constitution приходится переписывать под реальность: «фактический стек - X, тестовый фреймворк - Y, новые модули добавляются по правилу Z, не пытаемся переписать historical legacy».
• Spec не должен описывать то, что уже есть. Если в проекте есть сервис аутентификации, spec.md новой фичи не должен переописывать его - только то, что добавляется. Без дисциплины агент будет генерировать в spec длинные секции про существующее, замусоривая артефакт.
• Plan должен ссылаться на существующие паттерны. Хороший plan.md в brownfield говорит: «следуем тому же паттерну, что в app/services/billing/, повторно используем SharedAuth middleware, добавляем новый модуль рядом». Без этого агент проектирует параллельную архитектуру, не знающую, что половина уже написана.

Стилизованный пример на основе типичных паттернов: команда из 12 инженеров на Rails-монолите (250k строк, 6 лет в production) внедряет Spec Kit для всех новых фич. Первый шаг - попросить агента проанализировать кодовую базу и сгенерировать черновик constitution: фактические конвенции, используемый тестовый фреймворк (RSpec + FactoryBot), доменная структура (модульный монолит с пятью bounded contexts), запреты («не вводим новые ORM», «не пишем новые сервисы на Sinatra»). Этот черновик дорабатывается людьми и становится constitution.md. Дальше каждая фича начинается с /speckit-specify, ссылающейся на конкретный domain. В community walkthroughs описаны схожие случаи на ASP.NET CMS (~307k строк) и Java runtime (~420k строк) - детали в разделе ниже про case study.

Гибрид: SDD только для архитектурных задач

Третий распространённый режим: команда не использует Spec Kit для каждой задачи, только для тех, где цена ошибки высокая. Точечные правки и баги делаются обычным prompting-ом. Новые сервисы, миграции, изменения схем БД, новые интеграции - проходят через полный SDD-цикл.

Этот режим работает, потому что constitution и существующие spec-артефакты остаются доступны агенту. Когда агент работает над «маленькой» задачей в обычном режиме, он всё равно видит constitution.md в контексте и не нарушает её. Когда задача вырастает в архитектурную - команда переключается в Spec Kit-режим, и агент уже знаком с проектом.

Гибрид требует дисциплины: команда должна явно решать, какой режим применять, и не «по дефолту» спускаться в обычный prompting на задачах, где SDD оправдан. Простое правило: если перед началом работы непонятно, какой будет архитектурный выбор, - в Spec Kit; если выбор очевиден из существующего кода - без spec.

Команда и роли

Spec Kit меняет распределение работы внутри команды. Классическая модель «PM пишет требования, инженер реализует» сжимается: spec.md часто становится продуктом совместной работы инженера и агента, а PM подключается на ревью. Plan.md - почти полностью инженерная зона. Tasks.md - либо генерируется агентом, либо распределяется между несколькими агентами через MAQA-extension.

Эффект: инженер тратит больше времени на формулировку и ревью артефактов и меньше - на собственно написание кода. Junior-инженер выигрывает быстрее, потому что spec.md и plan.md компенсируют недостаток опыта (агент задаёт правильные вопросы). Senior-инженер выигрывает медленнее, потому что для него часть работы по spec.md - это то, что он раньше делал в голове за 5 минут. Зато senior выигрывает на масштабе: spec.md, написанный senior-инженером, потом исполняется агентом без supervision, и senior может вести три фичи параллельно вместо одной.

Антипаттерны в работе со спецификациями

Spec Kit даёт инструменты, но не гарантирует, что команда применяет их правильно. Большинство неудачных внедрений ломаются не на технической стороне, а на дисциплине работы со spec-артефактами. Ниже - семь антипаттернов, которые повторяются в community discussions и которые стоит распознавать заранее.

1. Spec drift: спецификация и код расходятся

Самый классический антипаттерн, наследуемый от любой документации. Spec.md написан, реализация ушла, через три месяца code и spec описывают разные системы. Агент при следующей задаче читает spec.md, генерирует план на основе устаревшей картины мира, реализация ломает что-то в production. Spec Sync extension обнаруживает drift, но не предотвращает его. Лекарство - правило «при изменении кода обновить spec в том же PR» и автоматическая проверка drift в CI.

2. Premature design: spec написан до понимания проблемы

Команда, которая ещё не понимает, что делает, торопится сесть за /speckit-specify. Spec получается формально валидным (все секции заполнены), но содержательно описывает не ту проблему. Через пять задач становится понятно, что нужно было совсем другое - но spec уже зацементировал неверное направление и агент по нему уверенно реализует.

Лекарство - не пропускать фазу discovery. Если ответ на вопрос «зачем это нужно» формулируется в виде «потому что нас попросили», - сначала продуктовый research, потом spec. Spec Kit здесь даёт /speckit-clarify: агент задаёт уточняющие вопросы, и часть из них вскрывает, что задача не разобрана.

3. Spec without tasks: артефакт есть, действий нет

Команда останавливается на /speckit-specify или /speckit-plan, не доводя до /speckit-tasks и /speckit-implement. Spec.md лежит в репозитории, но никто по нему не работает. Через месяц spec уже не соответствует тому, что обсуждается в чатах, - он становится shelfware.

Лекарство - правило «если spec не приведёт к коду в течение N дней, мы его не пишем». Spec.md без tasks.md - это документ, не исполняемая спецификация. Нет смысла платить overhead SDD, если не планируется исполнять.

4. Documentation theater: spec пишется для галочки

Команда формально следует процессу: spec, plan, tasks, implement. Но никто реально не читает spec.md перед ревью PR. Артефакт создаётся, потому что «у нас так принято», но не используется как контракт. Это худший вариант - overhead есть, пользы нет.

Лекарство - встроить spec в код-ревью. PR должен содержать ссылку на spec, ревьюер должен читать оба. Если spec не помогает понять PR - это сигнал, что spec написан плохо или что фича уже не совпадает со спекой. В обоих случаях нужно действовать, а не закрывать глаза.

5. Over-specification: спека ограничивает реализацию преждевременно

Spec.md детально описывает, какие классы создать, какие методы они должны содержать, как именно хранить состояние. Агент в /speckit-implement просто транскрибирует spec в код. Проблема: spec становится псевдокодом, и его проще читать как код. Любая попытка инженера улучшить дизайн в фазе implementation наталкивается на «но в spec написано иначе».

Лекарство - дисциплина уровней. Spec.md описывает что: user stories, requirements, success criteria. Plan.md описывает как: стек, архитектурный паттерн. Tasks.md описывает что нужно сделать: список задач. Реальные имена классов и методов появляются только в коде. Шаблоны Spec Kit жёстко разграничивают эти уровни (в spec.md явный запрет упоминать стек: «Focus on WHAT users need and WHY, avoid HOW to implement»). Команды, которые этот запрет игнорируют, скатываются в over-specification.

6. No validation gates: spec уходит без ревью

Инженер запускает /speckit-specify, получает spec.md, сразу запускает /speckit-plan, потом /speckit-tasks, потом /speckit-implement. Все артефакты сгенерированы агентом без human-review между фазами. Это буквальное использование spec-kit без spec-driven подхода: artifacts есть, контроля - нет. Любая ошибка в spec каскадируется во все следующие фазы.

Лекарство - встроенные gates: disable-model-invocation: true на skills, явное human-approval перед каждой фазой, Plan Review Gate extension для критичных фич. Если команда не готова делать паузы между фазами, SDD не приживётся.

7. Single-author spec: нет ревью спеки

Spec.md написан одним инженером и сразу пошёл в реализацию. Никто из команды его не читал. Через неделю всплывает, что предполагаемое поведение не то, что ждали другие команды. Spec.md в этом смысле ничем не отличается от обычного кода: ему нужен ревью, и без второго пары глаз качество просядет.

Лекарство - правило «spec.md ревьюится как код». Лучше всего работает создание PR с spec.md и planом до того, как запускается /speckit-tasks. Это и есть Plan Review Gate extension. На больших командах добавляется Staff Review extension - ревью уровня staff-engineer перед merge.

Валидация через checklist

Spec Kit встроенно поддерживает чеклисты: /speckit-checklist генерирует «unit tests for English» - проверки качества требований. Шесть категорий проверок: Requirement Completeness, Clarity, Consistency, Acceptance Criteria Quality, Scenario Coverage, Edge Cases, Non-Functional Requirements, Dependencies & Assumptions, Ambiguities & Conflicts. Если команда регулярно прогоняет чеклист, большинство антипаттернов выше отлавливаются автоматически.

Как измерить эффект SDD

Команды, которые внедряют Spec Kit, обычно через 2-3 месяца сталкиваются с вопросом «работает ли это на самом деле или мы просто дольше пишем». Без метрик ответ субъективен, и спор разрешается голосованием авторитетов. Ниже - набор метрик, которые имеют смысл измерять, и предостережения, которые с ними связаны. Точных индустриальных бенчмарков для SDD пока нет (подход слишком новый), но методология измерений переносима из соседних областей.

Метрики качества спецификации

• Checklist pass rate. Сколько процентов чеклист-вопросов из /speckit-checklist проходят с первого прогона. Низкий процент - сигнал, что spec.md написан плохо. Тренд этой метрики за квартал показывает, учится ли команда писать спеки лучше.
• Constitution-check failure rate. Сколько раз агент в фазе planning сообщает о нарушении конституционных принципов и попадает в Complexity Tracking. Высокая частота - либо constitution слишком жёсткая, либо команда выбирает компромиссы вместо честного анализа.
• Rounds of revision per spec. Сколько раз spec.md пересматривается до того, как пройти ревью. Тренд - индикатор того, насколько хорошо команда формулирует требования с первого раза.
• Lines of spec per feature. Объём spec.md как показатель «правильного уровня детализации». Слишком короткий spec - вероятно under-specified. Слишком длинный - вероятно over-specified или содержит детали реализации. Оптимум для типичной фичи в B2B SaaS - 200-500 строк spec.md, по опыту команд в community discussions; цифра не нормативная.

Метрики корреляции spec и кода

• Spec adherence score. Какой процент requirements из spec.md покрыт реализацией. Метрика встроена в Retrospective extension (adherence_threshold: 95 по умолчанию). Снижение тренда - сигнал spec drift.
• Phantom completions count. Сколько задач отмечено как выполненные ([x] в tasks.md), но без реального изменения в коде. Verify Tasks extension это автоматически детектит. Здоровая команда имеет 0 - любая задача либо реально сделана, либо честно открыта.
• Drift detection alerts per quarter. Сколько расхождений spec ↔ code находит Spec Sync. Растущий тренд - сигнал, что команда обновляет spec реже, чем код. Если drift не лечится - спека постепенно становится shelfware.

Метрики выхода AI-агента

• Agent acceptance rate of generated code. Какой процент кода, сгенерированного агентом, попадает в production без правок руками. На задачах со spec и без spec эта метрика обычно различается заметно. Точных цифр публично не агрегировано, но качественная разница описана в community walkthroughs - на нетривиальных задачах spec-kit-ed агент даёт более accept-абельный код, потому что архитектурный выбор согласован заранее.
• AI hallucination rate vs. spec presence. Сколько раз агент придумывает несуществующие API, библиотеки, аргументы. На spec-driven задачах этот показатель ниже, потому что plan.md фиксирует реальные библиотеки, а constitution исключает несуществующий или запрещённый стек. Метрика косвенная (нужен ручной обзор подвыборки PR), но даёт ощущение качества.
• Rework cycles per feature. Сколько раз PR возвращается на доработку. Сравнение SDD vs. non-SDD в одной команде - честная метрика, потому что контролируется опыт исполнителя. Здесь и проявляется главный экономический эффект SDD: rework стоит дорого, и снижение даже на 20-30% быстро отбивает overhead spec-фазы.

Метрики процесса

• Time-to-first-spec. Сколько от получения задачи до утверждённого spec.md. Если эта величина растёт без улучшения качества - команда тонет в spec-bureaucracy.
• Time-from-spec-to-merged-PR. Сколько от утверждённого spec.md до merge готового PR. Здоровая команда сокращает эту метрику с опытом: лучше написанный spec даёт более быструю реализацию.
• Skill recall: какой процент инженеров команды реально использует spec-kit. Если из 10 инженеров пять обходят процесс - это либо неподходящий процесс, либо неправильно настроенные стимулы. Метрика собирается через анализ git-логов: фичи, которые приехали в production без соответствующего specs/-каталога.

Что не стоит мерить

Velocity в story points до и после. Story points в SDD-контексте теряют смысл: декомпозиция меняется, размер задач меняется, сравнение «было/стало» становится сравнением яблок с грушами.

Время на написание spec.md. В отрыве от качества - бессмысленная метрика. Быстро написанная плохая spec приводит к долгой переделке. Медленно написанная хорошая spec экономит rework. Время имеет смысл смотреть только в паре с другой метрикой - например, lines-of-spec или rework cycles.

Количество спек как индикатор успеха. Команда, которая хвастается «у нас 50 spec.md», может либо реально работать в SDD, либо генерировать spec для каждой мелочи. Без проверки качества - цифра не говорит ничего.

Зачем нужен Spec Kit

Разрыв между спецификацией и реализацией существует столько же, сколько программирование. Аналитик пишет требования, разработчик интерпретирует их по-своему, QA находит расхождения. AI-агенты обостряют проблему: агент, получивший задачу «добавь авторизацию через WebAuthn», сразу начинает писать код. Он выбирает библиотеки, проектирует API, создаёт миграции - и инженер видит результат только когда PR готов. Если агент выбрал неподходящую библиотеку или спроектировал API несовместимо с архитектурой - весь код на переделку.

Spec-Driven Development инвертирует модель: спецификация становится первичным артефактом, код - производным. Три тренда делают это возможным именно сейчас:

• AI-возможности - natural language спецификации надёжно генерируют работающий код. Спецификация перестаёт быть документом «для людей» и становится исполняемым контрактом
• Сложность систем - десятки сервисов, микрофронтенды, мультиоблако. Ручная координация не масштабируется, нужна системная генерация из единого источника
• Скорость изменений - pivot и итерации постоянны. Традиционная разработка трактует изменения требований как disruption. SDD трактует их как штатную перегенерацию

На практике это означает: сначала агент описывает что нужно построить (spec.md) - инженер проверяет. Затем агент предлагает как реализовать (plan.md) - инженер проверяет. Только после двух одобрений агент декомпозирует задачу и пишет код. Ошибка в выборе библиотеки ловится на этапе plan.md - стоимость исправления: один абзац текста вместо переписывания кода.

Ключевое следствие: debugging становится исправлением спецификации, которая генерирует некорректный код. Рефакторинг - реструктуризацией spec для ясности. Maintenance - эволюцией спецификаций, а не ручным обновлением кода. Баг в production - обновление acceptance criteria в spec.md, чтобы следующая генерация учитывала этот сценарий.

Spec Kit формализует этот подход: шаблоны ограничивают поведение агента (запрещают писать про стек в фазе specify, обязывают маркировать неясности), скрипты создают ветки и директории детерминированно, gates блокируют переходы между фазами до одобрения человеком, extensions добавляют валидацию и интеграции с трекерами задач. Без фреймворка SDD - дисциплина, которую легко нарушить. С Spec Kit - процесс, управляемый программно.

Как это работает: скрипты, шаблоны, контроль

Spec Kit - прослойка между инженером и AI-агентом. Под капотом каждая skill-команда запускает bash-скрипт, который создаёт артефакты (ветки, директории, файлы), а затем передаёт агенту JSON с путями и контекстом. Агент заполняет артефакты по шаблонам. Инженер ревьюит результат и запускает следующую фазу.

Что происходит при вызове /speckit-specify

Когда инженер набирает /speckit-specify Приложение для организации фотографий, происходит следующее:

1. Claude Code загружает skill из .claude/skills/speckit-specify/SKILL.md. Skill помечен user-invocable: true и disable-model-invocation: true - агент не может вызвать его самостоятельно, только по команде человека
2. Skill вызывает скрипт .specify/scripts/bash/create-new-feature.sh. Скрипт сканирует существующие specs, определяет следующий номер (001, 002, ...), проверяет коллизии с remote и local branches, создаёт Git branch 001-photo-albums и директорию specs/001-photo-albums/
3. Скрипт возвращает JSON с путями к созданным артефактам:

   {
     "FEATURE_DIR": "specs/001-photo-albums",
     "BRANCH": "001-photo-albums",
     "SPEC_TEMPLATE": ".specify/templates/spec-template.md"
   }

4. Агент парсит JSON, загружает шаблон из spec-template.md и генерирует spec.md в указанной директории. Шаблон ограничивает агента: запрещает писать про стек, обязывает маркировать неясности через [NEEDS CLARIFICATION]
5. Агент останавливается и ждёт следующей команды от инженера

Скрипты в каждой фазе

Каждая skill-команда опирается на свой скрипт. Все скрипты лежат в .specify/scripts/bash/ (или .specify/scripts/powershell/ на Windows) и используют общую библиотеку common.sh для поиска путей к артефактам и форматирования JSON.

Фаза	Скрипт	Что делает	Что создаёт/изменяет
/speckit-specify	create-new-feature.sh	Создаёт branch и директорию фичи, проверяет коллизии	Git branch, specs/NNN-*/
/speckit-plan	setup-plan.sh	Инициализирует plan.md из шаблона, подставляет имя branch и дату	plan.md
/speckit-plan (авто)	update-agent-context.sh	Синхронизирует технические решения из plan.md в контекст агента	По умолчанию перезаписывает CLAUDE.md, отключается в конфиге
/speckit-tasks	check-prerequisites.sh	Проверяет, что spec.md и plan.md существуют. Блокирует генерацию задач при отсутствии	Ничего (валидация)

Почему скрипты, а не просто промпты

Скрипты решают задачи, которые LLM выполняет ненадёжно: создание Git branches с проверкой коллизий, автонумерация директорий, валидация наличия артефактов перед переходом фазы. Скрипт детерминированно создаёт структуру и возвращает агенту JSON с точными путями - агенту не нужно угадывать, куда писать файлы.

Контроль инженера

Контроль реализован на трёх уровнях:

Уровень	Механизм	Что делает
Шаблоны	Templates в .specify/templates/	Определяют структуру артефактов. Агент заполняет секции шаблона, а не пишет в свободной форме. Переопределяются через presets
Gates	Встроенные паузы + скрипты + extensions	disable-model-invocation: true гарантирует, что агент не запустит следующую фазу без команды человека. check-prerequisites.sh блокирует tasks при отсутствии spec и plan. Plan Review Gate формализует ревью через PR
Валидация	Post-implementation extensions	Verify проверяет покрытие requirements. Verify Tasks ловит задачи, отмеченные как выполненные без реальных изменений. Cleanup автоматически фиксит мелкие проблемы

Подключение extensions

Минимальный workflow работает без extensions - только core skills, скрипты и шаблоны. По мере роста проекта инженер добавляет расширения:

# Начало: только core
specify init . --ai claude --here

# Проект растёт: добавляем gate для планов
specify ext add plan-review-gate

# Команда растёт: добавляем ревью и Jira
specify ext add review
specify ext add staff-review
specify ext add jira

# Нужен multi-agent: подключаем MAQA
specify ext add maqa
specify ext add maqa-github-projects

Extension добавляет либо новые slash commands (/speckit.jira.specstoissues), либо hooks - скрипты, которые срабатывают автоматически после определённых фаз. Cleanup запускается hook-ом после /speckit-implement, Review - после завершения реализации. Extension не меняет core workflow - он расширяет его дополнительными проверками и интеграциями.

Установка и структура проекта

Spec Kit распространяется как Python CLI (specify-cli). Требования: Python 3.11+, uv, Git, установленный AI-агент.

Persistent установка (рекомендуется):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Одноразовый запуск:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init my-project --ai claude

Инициализация в существующем проекте:

specify init . --ai claude --here

Флаги: --ai выбирает агента (claude, copilot, cursor-agent, gemini, и т.д.), --script sh или --script ps для Bash/PowerShell, --ignore-agent-tools пропускает проверку установки агента.

После инициализации создаётся структура:

project-root/
├── .specify/
│   ├── memory/
│   │   └── constitution.md      # Принципы проекта
│   ├── templates/               # Шаблоны спецификаций
│   ├── scripts/                 # Скрипты интеграции
│   │   └── update-context.sh
│   └── integrations/
│       └── claude/
│           └── scripts/
├── .claude/
│   └── skills/                  # Skills для Claude Code
│       ├── speckit-constitution.md
│       ├── speckit-specify.md
│       ├── speckit-plan.md
│       ├── speckit-tasks.md
│       └── speckit-implement.md
├── specs/
│   └── 001-feature-name/       # Артефакты по фичам (автонумерация)
│       ├── spec.md
│       ├── plan.md
│       ├── tasks.md
│       ├── data-model.md
│       ├── contracts/
│       └── research.md
└── .speckit/
    ├── agents.yml               # Конфигурация AI-агента
    ├── extensions.yml           # Подключённые расширения
    ├── presets.yml              # Активные presets
    └── preferences.yml          # Пользовательские настройки

Верификация окружения:

specify check

Команда проверяет наличие Python, uv, Git, CLI агента и корректность структуры проекта.

Для non-Git окружений конфигурация активной фичи задаётся через .specify/init-options.json.

Обновление и поддержка

Spec Kit состоит из двух компонентов, которые обновляются отдельно: CLI и проектные файлы.

Обновление CLI:

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Обновление проектных файлов:

specify init --here --force --ai claude

Эта команда обновляет skills, templates и scripts. Важно понимать, что именно сохраняется, а что перезаписывается:

Категория	При upgrade	Действие
specs/ (спецификации, планы, задачи)	Сохраняется	Безопасно
Исходный код	Сохраняется	Безопасно
Git history	Сохраняется	Безопасно
.specify/memory/constitution.md	Перезаписывается	Сделать бэкап
.specify/templates/	Перезаписывается	Сделать бэкап кастомных шаблонов
.claude/skills/	Перезаписывается	Skills обновятся

После обновления:

specify check

CLI и проектные файлы синхронизированы в рамках major version. При переходе между major версиями возможны breaking changes.

Обновление extensions:

specify ext add <name>

Повторная установка скачивает актуальную версию. Каждый extension ведёт CHANGELOG.md с описанием изменений между версиями.

Air-gapped окружения (закрытые контуры без интернета):

# На подключённой машине
pip download specify-cli -d ./dist

# На закрытом контуре
pip install --no-index --find-links=./dist specify-cli

Создаётся OS-специфичный wheel bundle, который переносится на изолированную машину.

Внедрение в существующий проект

Spec Kit документация изначально фокусировалась на greenfield-проектах (specify init <PROJECT_NAME>). Но CLI всегда поддерживал инициализацию в существующих директориях. После issue #1285 brownfield-workflow задокументирован явно.

Инициализация в существующей кодовой базе

specify init . --here --force --ai claude

Флаг --force пропускает предупреждение «Current directory is not empty» и запускает merge. Merge работает атомарно: файлы извлекаются во временную директорию и переносятся в проект. Если что-то пойдёт не так, оригинальные файлы не затрагиваются.

Что происходит с существующими файлами:

• .git/ - не затрагивается. Если Git уже инициализирован, повторная инициализация пропускается
• .claude/ - существующие конфигурации сохраняются, новые skills добавляются рядом
• .vscode/settings.json - глубокий recursive merge: вложенные настройки объединяются, а не перезаписываются
• CLAUDE.md - по умолчанию обновляется скриптом update-agent-context.sh после /speckit-plan. Скрипт можно отключить, чтобы root-файл не трогался - см. case study ниже

Constitution для существующего проекта

Дефолтный constitution.md содержит принципы для нового проекта (library-first, TDD). Для brownfield-проекта его нужно переписать под реальные конвенции команды. Рекомендуемый подход:

1. Попросить агента проанализировать существующую кодовую базу: паттерны, стек, конвенции именования, архитектурные решения
2. Зафиксировать в constitution то, что уже является фактом: используемый стек, тестовый фреймворк, структуру модулей, стандарты code style
3. Добавить ссылки на существующую документацию (ADR, README секции, архитектурные гайды)

Constitution для brownfield-проекта фиксирует реальность, а не идеал. Если проект использует REST и переходить на gRPC не планируется - это записывается как constitutional constraint. Агент не будет предлагать gRPC в plan.md.

Brownfield Bootstrap extension

Community extension brownfield-bootstrap автоматизирует анализ существующего проекта:

• Определяет стек и архитектурные паттерны (Maven, Gradle, Node.js workspaces, Go modules, Rust crates, Python monorepo)
• Генерирует constitution.md на основе реальных конвенций проекта, а не дефолтного шаблона
• Создаёт «brownfield skills» - контекстные документы, которые дают агенту знания о существующей кодовой базе

Валидация подхода

В community walkthroughs задокументированы brownfield-кейсы:

• ASP.NET CMS, ~307k строк - добавление фичей через spec-kit в существующую кодовую базу (стилизованный пример на основе типичных паттернов в community discussions)
• Java runtime, ~420k строк - multi-module проект с Spec Kit в отдельном репозитории design-notes (стилизованный пример на основе типичных паттернов)
• Multi-repo workspace (GitHub Discussion #1119) - VS Code workspace из пяти репозиториев, Spec Kit в одном из них. Агент автономно обнаружил Go version, HTTP-фреймворк (go-chi/chi), паттерны логирования и использовал их в plan.md

Интеграция с Claude Code

При инициализации с --ai claude Spec Kit создаёт файлы в .claude/skills/ - нативный механизм skills Claude Code. Каждый файл - Markdown с YAML frontmatter:

---
description: "Establish project principles and development guidelines"
---

Based on $ARGUMENTS, create the project constitution...

$ARGUMENTS - placeholder, через который передаются параметры команды.

Доступные skills (вызываются как slash commands):

Команда	Назначение
/speckit-constitution	Создать принципы проекта
/speckit-specify	Описать требования (что и зачем)
/speckit-clarify	Разрешить неоднозначности в spec
/speckit-plan	Технический план (стек, архитектура)
/speckit-tasks	Декомпозиция на задачи
/speckit-analyze	Валидация плана перед реализацией
/speckit-implement	Реализация по задачам
/speckit-checklist	Проверка полноты спецификации
/speckit-taskstoissues	Создать GitHub Issues из tasks.md

Контекстная автодетекция. Claude Code определяет активную фичу по имени Git branch. Если branch называется 001-photo-albums, команды автоматически работают с specs/001-photo-albums/. Переключение branch = переключение фичи.

Пример workflow в Claude Code:

# 1. Инициализация (один раз)
specify init . --ai claude --here

# 2. В Claude Code
/speckit-constitution Проект следует library-first подходу.
Все фичи сначала как standalone библиотеки. Строгий TDD.
Минимализм: не более 3 проектов на старте.

/speckit-specify Приложение для организации фотографий в альбомы.
Альбомы группируются по дате. Drag-and-drop для реорганизации.
Превью фотографий в tile-интерфейсе внутри каждого альбома.

/speckit-clarify Нужна ли поддержка видео? Какой максимальный размер альбома?

/speckit-plan Стек: Vite, vanilla HTML/CSS/JS, SQLite на бэкенде.

/speckit-tasks

/speckit-analyze

/speckit-implement

Каждая команда работает с артефактами предыдущей фазы. /speckit-plan читает spec.md, /speckit-tasks анализирует plan.md + data-model.md + contracts/.

SDLC workflow: фазы, артефакты, переходы

Workflow Spec Kit - конвейер из шести основных фаз и трёх опциональных. Каждая фаза принимает артефакты предыдущей, создаёт новые и предлагает конкретные следующие шаги. Агент не может перейти к следующей фазе без команды инженера (disable-model-invocation: true).

Обзор конвейера

Constitution ──► Specify ──► Plan ──► Tasks ──► Implement
                    │           │        │
                    ▼           ▼        ▼
                 Clarify    Checklist  Analyze
                (optional)  (optional) (optional)

Фаза	Команда	Что читает	Что создаёт	Следующий шаг
Constitution	/speckit-constitution	Описание принципов от инженера	.specify/memory/constitution.md	/speckit-specify
Specify	/speckit-specify	Описание фичи + constitution	Git branch, specs/NNN-*/spec.md, checklists/requirements.md	/speckit-plan или /speckit-clarify
Clarify	/speckit-clarify	spec.md	Обновлённый spec.md + секция ## Clarifications	/speckit-plan
Plan	/speckit-plan	spec.md + constitution	plan.md, research.md, data-model.md, contracts/, quickstart.md	/speckit-tasks или /speckit-checklist
Checklist	/speckit-checklist	spec.md, опционально plan.md, tasks.md	checklists/<domain>.md (ux, api, security...)	/speckit-tasks или /speckit-implement
Tasks	/speckit-tasks	plan.md, spec.md, data-model.md, contracts/	tasks.md	/speckit-analyze или /speckit-implement
Analyze	/speckit-analyze	spec.md, plan.md, tasks.md, constitution	Отчёт в консоль (read-only, файлы не меняет)	/speckit-specify, /speckit-plan или ручная правка
Implement	/speckit-implement	tasks.md, plan.md, checklists/, все артефакты	Исходный код, tasks.md с отметками [X], ignore-файлы	Extensions: Verify, Review, Cleanup

1. Constitution

Вход	Описание принципов от инженера
Выход	.specify/memory/constitution.md
Следующий шаг	/speckit-specify - описать первую фичу

Constitution - «законодательная база» проекта. Все последующие артефакты подчиняются этим принципам. Шаблон содержит пять именованных принципов с описаниями, секции для дополнительных ограничений и блок Governance с процедурой внесения изменений и контроля соответствия.

Примеры принципов из дефолтного шаблона:

• Library-First - каждая фича начинается как standalone библиотека. Код не пишется напрямую в приложение без абстрагирования в переиспользуемый компонент
• Test-First - NON-NEGOTIABLE правило: тесты пишутся до реализации и должны упасть (Red phase) до начала написания кода
• Simplicity - не более 3 проектов на старте, прямое использование фреймворков без wrapping-абстракций
• Integration Testing - реальные базы данных вместо моков, контрактные тесты обязательны до реализации

Constitution обеспечивает три вида консистентности: across time (код через год следует тем же принципам), across LLMs (разные AI-модели генерируют архитектурно совместимый код), architectural integrity (каждая фича усиливает, а не подрывает дизайн системы).

Plan.md операционализирует constitution через gates, которые агент обязан пройти перед реализацией. Если gate не пройден, агент документирует обоснование в секции Complexity Tracking.

2. Specify

Вход	Описание фичи от инженера + constitution.md
Выход	Git branch NNN-feature-name, директория specs/NNN-feature-name/, spec.md, checklists/requirements.md
Следующий шаг	/speckit-plan (технический план) или /speckit-clarify (если есть неясности)

Шаблон ограничивает агента: описывать что и зачем, без деталей реализации. Явный запрет упоминать технический стек: «Focus on WHAT users need and WHY, avoid HOW to implement».

Структура генерируемого spec.md:

• User Scenarios & Testing - User Stories с приоритетами (P1/P2/P3), acceptance scenarios в формате Given/When/Then, edge cases
• Requirements - функциональные требования (FR-001, FR-002...) и ключевые сущности (Key Entities)
• Success Criteria - измеримые метрики успеха (SC-001, SC-002...)
• Assumptions - зафиксированные допущения

При неопределённости агент ставит маркер [NEEDS CLARIFICATION: ...] (максимум 3) вместо того, чтобы угадывать. Автоматически генерируется checklist requirements.md с 6 подфазами валидации качества спецификации.

Контрольная точка: spec.md ревьюится человеком. Все [NEEDS CLARIFICATION] должны быть разрешены до перехода к планированию.

2.5. Clarify (опциональная)

Вход	spec.md
Выход	Обновлённый spec.md с секцией ## Clarifications > ### Session YYYY-MM-DD
Следующий шаг	/speckit-plan (технический план)

Структурированное уточнение спецификации. Агент сканирует spec.md по 10 категориям таксономии неоднозначностей (Functional Scope, Domain & Data Model, Interaction & UX Flow, Non-Functional Quality Attributes, Integration & Dependencies, Edge Cases, Constraints & Tradeoffs, Terminology, Completion Signals, Miscellaneous), генерирует до 5 приоритизированных вопросов и задаёт их по одному. После каждого ответа spec.md обновляется инкрементально.

Агент ищет конкретные сигналы: TODO-маркеры, vague adjectives («robust», «intuitive»), неразрешённые решения. Каждый аспект спецификации получает статус покрытия: Clear, Partial или Missing.

3. Plan

Вход	spec.md + constitution.md
Выход	plan.md, research.md, data-model.md, contracts/, quickstart.md
Следующий шаг	/speckit-tasks (декомпозиция) или /speckit-checklist (валидация требований)

Фаза планирования работает в два этапа. Phase 0 (Research) - агент разрешает все NEEDS CLARIFICATION из Technical Context, исследует совместимость библиотек, benchmarks, security implications. Результат - research.md. Phase 1 (Design) - извлечение сущностей в data model, определение interface contracts, создание quickstart-сценариев для валидации.

Структура генерируемого plan.md:

• Technical Context - язык, зависимости, хранилище, тестирование, платформа, тип проекта, performance goals, constraints
• Constitution Check - gate, который агент обязан пройти перед Phase 0 и повторно после Phase 1
• Project Structure - дерево документации и исходного кода (три варианта: single project, web app, mobile + API)
• Complexity Tracking - таблица обоснований нарушений конституционных принципов

Каждый технический выбор ссылается на конкретное требование из spec.md - это обеспечивает traceability. После генерации plan.md скрипт update-agent-context.sh синхронизирует технические решения в контекст агента.

Контрольная точка: plan.md может быть заблокирован через extension Plan Review Gate - требует PR/MR approval до перехода к tasks.

3.5. Checklist (опциональная)

Вход	spec.md (обязательно), plan.md и tasks.md (опционально)
Выход	checklists/<domain>.md (ux, api, performance, security, test...)
Следующий шаг	/speckit-tasks или /speckit-implement

«Unit tests for English» - чеклисты проверяют качество требований, а не работоспособность системы. Каждый элемент - вопрос вида «Are [requirement] defined with measurable criteria?», а не «Verify that page displays 3 cards».

Категории проверок: Requirement Completeness, Clarity, Consistency, Acceptance Criteria Quality, Scenario Coverage, Edge Cases, Non-Functional Requirements, Dependencies & Assumptions, Ambiguities & Conflicts. Элементы маркируются ID (CHK001...) и содержат traceability-ссылки на секции spec ([Spec section X.Y]). Софт-лимит: 40 items, ≥80% должны содержать traceability-ссылку.

4. Tasks

Вход	plan.md (обязательно), spec.md (обязательно), data-model.md, contracts/, research.md, quickstart.md
Выход	tasks.md
Следующий шаг	/speckit-analyze (проверка консистентности) или /speckit-implement (реализация)

Декомпозиция плана в упорядоченный список задач с фиксированной структурой фаз:

Фаза в tasks.md	Содержание	Зависимости
Phase 1: Setup	Shared infrastructure - инициализация проекта, конфигурации	Нет
Phase 2: Foundational	Blocking prerequisites - то, без чего ни одна user story не начнётся	Phase 1. CRITICAL: блокирует все последующие фазы
Phase 3: User Story 1	P1 (MVP) - тесты + реализация	Phase 2
Phase 4: User Story 2	P2 - тесты + реализация	Phase 2, возможно Phase 3
Phase 5: User Story 3	P3 - тесты + реализация	Phase 2, возможно предыдущие
Phase N: Polish	Cross-cutting concerns, финальные доработки	Все предыдущие

Формат задачи: - [ ] T001 [P] [US1] Description with src/path/to/file.py. Маркер [P] обозначает параллелизуемые задачи (разные файлы, нет зависимостей) - сигнал для multi-agent extensions типа MAQA. [US1]/[US2] - привязка к user story. После каждой фазы - маркер **Checkpoint**.

Три стратегии реализации: MVP First (только US1), Incremental Delivery (последовательно по stories), Parallel Team Strategy (несколько агентов на независимых stories).

4.5. Analyze (опциональная)

Вход	spec.md, plan.md, tasks.md (все обязательны), constitution.md
Выход	Отчёт в консоль (строго read-only, файлы не модифицируются)
Следующий шаг	/speckit-specify (уточнить spec), /speckit-plan (скорректировать архитектуру) или ручная правка tasks.md

Неразрушающая cross-artifact проверка консистентности перед реализацией. Агент строит семантические модели: инвентарь требований (FR-###, SC-###), инвентарь задач (T###), coverage mapping, constitution rule set. Затем выполняет 6 проходов детекции (лимит 50 findings):

• Duplication - near-duplicate требования
• Ambiguity - vague adjectives без метрик, неразрешённые placeholders (TODO, TKTK, ???)
• Underspecification - недостающие детали
• Constitution Alignment - нарушения принципов = CRITICAL severity
• Coverage Gaps - требования без задач или задачи без требований
• Inconsistency - терминологический drift, расхождения data entities, противоречия в ordering

Severity levels: CRITICAL (нарушение constitution MUST, отсутствие core artifact), HIGH (duplicate/conflicting requirement), MEDIUM (terminology drift), LOW (style improvements). Агент предлагает remediation, но не применяет изменения без одобрения.

5. Implement

Вход	tasks.md (обязательно), plan.md (обязательно), все артефакты, checklists/
Выход	Исходный код, обновлённый tasks.md с [X] на выполненных задачах, ignore-файлы
Следующий шаг	Extensions: Verify, Review, Staff Review, Cleanup, Retrospective

Перед началом реализации агент проверяет статус checklists: если есть незавершённые - блокирует работу (если инженер не подтвердит продолжение). Затем определяет tech stack из plan.md и создаёт/верифицирует ignore-файлы (.gitignore, .dockerignore, .eslintignore и т.д.) с паттернами под конкретный стек.

Порядок реализации внутри каждой фазы: Setup → Tests → Core → Integration → Polish. Это следствие Test-First принципа из constitution - агент обязан написать тесты и убедиться, что они падают, до написания кода реализации. При неудаче непараллельной задачи - halt. Параллельные задачи ([P]) выполняются независимо.

Extension Checkpoint (specify ext add checkpoint) делает промежуточные коммиты по ходу работы, предотвращая один гигантский PR.

6. Verify/Review (extensions)

Вход	Исходный код + все spec-артефакты
Выход	Отчёты, автофиксы (до 50 строк), новые задачи (50-200 строк)
Следующий шаг	PR/merge или повторная итерация

Post-implementation фаза. Набор extensions проверяет результат: соответствие spec, качество кода, тесты, безопасность. Подробнее - в секции Валидация артефактов.

Полный пример: артефакты одной фичи

После прохождения всех фаз для фичи 001-photo-albums директория specs/ содержит:

specs/001-photo-albums/
├── spec.md                    # Phase 2: Specify
├── research.md                # Phase 3: Plan (Phase 0)
├── plan.md                    # Phase 3: Plan
├── data-model.md              # Phase 3: Plan (Phase 1)
├── quickstart.md              # Phase 3: Plan (Phase 1)
├── contracts/                 # Phase 3: Plan (Phase 1)
│   └── api-spec.md
├── tasks.md                   # Phase 4: Tasks
└── checklists/
    ├── requirements.md        # Phase 2: Specify (авто)
    ├── ux.md                  # Phase 3.5: Checklist
    └── security.md            # Phase 3.5: Checklist

Валидация артефактов и quality gates

Вся валидация реализована через extensions - core Spec Kit минимален. Проверки подключаются по потребности через specify ext add <name>.

Между фазами

Plan Review Gate - блокирует переход к /speckit-tasks до одобрения plan.md через pull request. Workflow: создать spec.md → создать plan.md → merge через PR с ревью → только тогда tasks.

Checklist (/speckit-checklist) - встроенная команда, проверяет полноту спецификации: все ли требования testable, есть ли measurable success criteria, разрешены ли все [NEEDS CLARIFICATION].

Post-implementation

Verify - проверяет соответствие кода спецификации. Adherence scoring: все ли требования покрыты, соответствуют ли задачи коду, нет ли scope creep.

Verify Tasks - обнаруживает «phantom completions»: задачи, отмеченные [x] в tasks.md, но без реальных изменений в коде. Сравнивает checkbox-состояния с git diff.

Cleanup - quality gate по принципу scout rule. Три уровня реакции:

• Small issues (до 50 строк) → автоматический фикс
• Medium issues (до 200 строк) → создание новых задач
• Large issues (500+ строк) → детальный анализ без автофикса

Review - 7 специализированных проверок: качество кода, комментарии, тесты, обработка ошибок, типы, упрощение. Каждая проверка запускается как отдельный анализ.

Staff Review - ревью уровня staff-engineer. Проверяет: 100% spec adherence, security best practices, performance, покрытие тестами.

Документация и traceability

DocGuard - Canonical-Driven Development. 6 команд: validate, score, trace, analyze, fix, report. Вычисляет score по четырём измерениям: completeness (30%), clarity (30%), consistency (20%), traceability (20%). Генерирует traceability matrix. Поддерживает автофикс форматирования и орфографии.

validation_level: strict
traceability:
  enabled: true
  enforce_100_percent: true
scoring:
  completeness_weight: 0.3
  clarity_weight: 0.3
  consistency_weight: 0.2
  traceability_weight: 0.2

Regulatory-grade: V-Model

Для regulated industries (медицина, финансы) - V-Model extension. Реализует парную генерацию design specs + test specs с traceability matrices по стандартам INCOSE, IEEE 1016/42010, ISO 29119/14971, IEC 62304.

5 матриц traceability:

Матрица	Связь
A	Requirements ↔ Acceptance Tests
B	System Design ↔ System Tests
C	Architecture ↔ Integration Tests
D	Modules ↔ Unit Tests
H	Hazards → Mitigations → Verifications

Принцип: scripts verify (детерминированный bash), AI generates (контент). Coverage validation - 100%, audit-grade. Ingestion результатов тестов из JUnit XML и Cobertura coverage reports.

CI/CD Gate

MAQA CI Gate - автоматически определяет CI-платформу (GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines) и блокирует переход к QA до зелёного pipeline.

ci_cd:
  provider: "auto"
  required_status: "success"
  check_coverage: true
  coverage_min: 80

Drift detection

Reconcile / Spec Sync - обнаруживает расхождения между спецификацией и реализацией. Analyze-команда выдаёт отчёт: specs analyzed, requirements covered, aligned specs, drifted specs, unverifiable items. Spec Sync предлагает AI-assisted resolution с обязательным human approval.

Интеграция с Jira

Jira extension (v2.1.0) требует MCP-сервер «atlassian» для доступа к Jira API.

Конфигурация

Файл .specify/extensions/jira/jira-config.yml:

mcp_server: "atlassian"

project:
  key: "PROJ"

mapping:
  spec_artifact: "Epic"
  phase_artifact: "Story"
  task_artifact: "Task"

relationships:
  spec_phase: "Epic Link"
  phase_task: "Relates"
  spec_task: "Epic Link"

defaults:
  spec:
    labels: ["spec-driven"]
    custom_fields:
      customfield_10002: 2
  task:
    labels: ["implementation"]
    custom_fields:
      customfield_10002: 2

status_mapping:
  completed: "Done"
  pending: "To Do"
  in_progress: "In Progress"

Два режима маппинга

3-level (по умолчанию): spec.md → Jira Epic, заголовки фаз из tasks.md → Stories, отдельные задачи → Task issues. Полная гранулярность - каждая задача трекается как отдельный issue.

2-level: spec.md → Epic, задачи встраиваются в описания Stories. Меньше issues в Jira, но нет индивидуального трекинга задач.

Переключение: task_artifact: "" в mapping для 2-level режима.

Команды

Команда	Назначение
/speckit.jira.specstoissues	Создать иерархию Jira issues из spec.md и tasks.md
/speckit.jira.discover-fields	Обнаружить custom fields инстанса и сгенерировать конфигурацию
/speckit.jira.sync-status	Синхронизировать checkbox states в Jira issue statuses

Артефакты синхронизации

После создания issues генерируются:

• specs/<feature>/jira-mapping.json - маппинг spec-артефактов на Jira issue IDs
• specs/<feature>/jira-sync-log.json - лог операций синхронизации

Local overrides и CI

Для разных окружений - jira-config.local.yml (добавляется в .gitignore):

# .specify/extensions/jira/jira-config.local.yml
project:
  key: "MYTEST"

Для CI - environment variables:

export SPECKIT_JIRA_PROJECT_KEY="DEVTEST"
export SPECKIT_JIRA_SPEC_ARTIFACT="Epic"
export SPECKIT_JIRA_TASK_ARTIFACT="Task"

Ограничения

Custom field IDs (customfield_XXXXX) специфичны для каждого Jira-инстанса - /speckit.jira.discover-fields помогает их найти. Relationship types зависят от конфигурации Jira (Parent, Epic Link, Relates, Blocks, Implements, is child of, none). Двунаправленная синхронизация статусов требует предварительного создания mapping через specstoissues.

Интеграция с GitHub

GitHub Projects

MAQA board companion синхронизирует spec-артефакты с GitHub Projects v2. Установка и подключение:

specify ext add maqa-github-projects

После установки draft issues создаются автоматически из спецификаций. По мере работы агента статусы обновляются по lifecycle: todo → in_progress → in_review → done. Task lists внутри issues отражают содержимое tasks.md - checkbox-состояния синхронизируются при каждом вызове /speckit.maqa.sync.

Для команд на GitHub это даёт единую точку: spec-артефакты, PR с кодом и project board живут в одном месте. Ревьюер видит и спецификацию, и реализацию, и статус задач.

GitHub Issues из tasks.md

Встроенная skill /speckit-taskstoissues конвертирует задачи из tasks.md в GitHub Issues без дополнительных extensions. Каждая задача становится отдельным issue с описанием и acceptance criteria из spec. Это базовый механизм для команд, которым не нужен полноценный project board, но нужен трекинг задач через GitHub.

Git workflow

Spec Kit использует Git как основу контекстного переключения между фичами:

• При /speckit-specify автоматически создаётся feature branch (001-feature-name) и директория specs/001-feature-name/
• Claude Code определяет активную фичу по имени branch - переключение git checkout 002-another-feature переключает контекст всех spec-kit команд
• Plan Review Gate использует стандартный PR workflow - spec.md и plan.md проходят ревью через pull request, /speckit-tasks заблокирован до merge
• Extension Checkpoint (specify ext add checkpoint) делает промежуточные коммиты по ходу /speckit-implement, предотвращая один гигантский diff

Project Health Check

specify ext add project-health-check

Диагностика проекта одной командой. Проверяет: корректность структуры .specify/, установленные extensions и их версии, состояние feature branches, наличие незавершённых specs, валидность скриптов. Полезно после upgrade Spec Kit или при onboarding нового участника - показывает, в каком состоянии находится spec-driven workflow.

Другие интеграции: Azure DevOps, Linear, Trello

Azure DevOps

Extension v1.0.0. OAuth-аутентификация через Azure CLI (без Personal Access Tokens).

• User Stories из spec.md → Azure DevOps User Story work items
• Tasks из tasks.md → Task work items (linked to parent stories)
• Automatic priority mapping: P1-P4 из spec-kit → Azure DevOps priorities
• Duplicate prevention через work item mapping
• Interactive selection - выбор конкретных items для синхронизации

Конфигурация (~/.speckit/ado-config.json):

{
  "Organization": "org-name",
  "Project": "project-name",
  "AreaPath": "path\\to\\area"
}

Или через environment variables:

export AZURE_DEVOPS_ORG="org-name"
export AZURE_DEVOPS_PROJECT="project-name"

Linear и Trello

Оба - MAQA board companions, работают по одному принципу: расширение создаёт issues/cards из spec-артефактов и синхронизирует статусы при прогрессе фичи. Установка аналогична GitHub Projects:

# Linear
specify ext add maqa-linear

# Trello
specify ext add maqa-trello

Linear companion создаёт issues и переключает workflow states (todo → in_progress → done). Trello companion заполняет board из specs, перемещает cards по колонкам и обновляет checklists внутри cards по мере выполнения задач. Оба требуют предварительной настройки MAQA (/speckit.maqa.setup) и работают только в связке с базовым MAQA extension.

Confluence

Прямой интеграции нет - Spec Kit хранит спецификации в Git как Markdown файлы. Для команд с Confluence есть два частичных решения: DocGuard (specify ext add docguard) валидирует документацию проекта и генерирует traceability matrix между spec-артефактами, а Spec Sync (specify ext add spec-sync) обнаруживает расхождения между specs и внешней документацией. Экспорт Markdown в Confluence требует сторонних инструментов (например, mark CLI или GitHub Action confluence-wiki-sync).

Кастомизация: presets и шаблоны

Дефолтные шаблоны Spec Kit рассчитаны на greenfield-проект. Для других сценариев (миграция, brownfield, regulated industries) нужны другие структуры артефактов. Presets решают эту задачу: переопределяют шаблоны spec.md, plan.md и терминологию команд без изменения CLI.

Структура preset

my-preset/
├── preset.yml          # Manifest (обязательно)
├── templates/          # Переопределения шаблонов (обязательно)
├── commands/           # Переопределения команд (опционально)
├── README.md           # Документация (обязательно)
├── LICENSE             # Лицензия (обязательно)
└── CHANGELOG.md        # История изменений (опционально)

Manifest (preset.yml)

id: my-migration-preset
version: 1.0.0
description: "Preset for technology migration projects"
repository: https://github.com/org/my-migration-preset
license: MIT
requires:
  speckit_version: ">=0.1.0"
provides:
  templates:
    - spec.md
    - plan.md
  commands:
    - speckit-migrate
tags:
  - migration
  - brownfield

Механизм работы

Preset override templates заменяют дефолтные шаблоны. При вызове /speckit-specify агент использует кастомный шаблон вместо стандартного. Это меняет структуру генерируемых артефактов без модификации CLI.

Проверка итогового шаблона (после наложения presets):

specify preset resolve

Разработка и тестирование

# Локальная разработка
specify preset add --dev /path/to/my-preset

# Проверка в реальном workflow
/speckit-specify Test feature for preset validation

Стэкинг presets

Несколько presets могут быть активны одновременно. Порядок в presets.yml определяет приоритет - при конфликтах побеждает последний preset. Presets нужно проектировать с учётом совместимости при стэкинге.

Пример: AIDE In-Place Migration

Специализированный preset для проектов, где нужно мигрировать с технологии X на технологию Y (например, с jQuery на React или с REST на gRPC). Добавляет в шаблоны секции: анализ совместимости source и target стеков, пошаговый migration path, стратегия rollback на каждом этапе, план миграции данных. Требует предварительной установки AIDE extension:

specify ext add aide
specify preset add aide-in-place-migration

После активации /speckit-specify генерирует spec.md с секциями, специфичными для миграции, а /speckit-plan включает поэтапный план перехода вместо стандартного greenfield-плана.

Extensions: архитектура и каталог

40+ community extensions в пяти категориях. Каждый extension маркирован effect level: read-only (генерирует отчёты без изменения файлов) или read+write (модифицирует файлы и артефакты). Это позволяет оценить риск при подключении нового extension.

Категория	Назначение	Примеры
docs	Валидация и генерация spec-артефактов	DocGuard, Spec Sync
code	Ревью и модификация кода	Review, Cleanup, Staff Review
process	Оркестрация workflow	MAQA, Conduct, Fleet Orchestrator
integration	Синхронизация с внешними платформами	Jira, Azure DevOps, Linear
visibility	Отчёты и диагностика	Project Health, Retrospective

Управление extensions

# Поиск
specify ext search jira

# Установка
specify ext add jira
specify ext add my-ext --from https://github.com/org/repo/archive/v1.0.0.zip

# Список установленных
specify ext list

Каталоги

Два каталога: community (catalog.community.json) и organization (catalog.json - пустой по умолчанию). Организации курируют свой каталог одобренных extensions. Приватный каталог настраивается через SPECKIT_CATALOG_URL.

Ключевые extensions

MAQA (Multi-Agent QA) - coordinator agent распределяет задачи feature-агентам, которые работают в параллельных Git worktrees. QA agent проверяет каждую фичу отдельно. Claude Code использует нативные субагенты (.claude/agents/) после /speckit.maqa.setup.

max_parallel: 3
qa_cadence: per_feature
auto_push: false

qa:
  security: true
  accessibility: false
  spelling: true
  links: true

test_command: "npm test"
test_file_command: "npm test -- {file}"

Conduct (specify ext add conduct) - делегирует каждую фазу SDD отдельному субагенту. На практике это означает, что specify-фаза запускает один субагент с контекстом constitution + шаблон спецификации, plan-фаза - другой субагент с контекстом spec.md + шаблон плана. Каждый субагент видит только свой домен, что снижает context pollution при больших проектах, где артефакты не помещаются в одно контекстное окно.

Fleet Orchestrator (specify ext add fleet-orchestrator) - добавляет обязательные human gates между каждой фазой. В отличие от дефолтного workflow (где агент может перейти к следующей фазе по команде пользователя), Fleet Orchestrator программно блокирует переход без явного approval. Используется в командах, где нужна формальная приёмка каждого артефакта - например, при работе по compliance-процессу.

FixIt (specify ext add fixit) - при работе с багом автоматически находит связанный requirement в spec.md и acceptance criteria в tasks.md. Фикс делается с учётом контекста спецификации, а не только кода. После фикса extension предлагает обновить spec - добавить edge case, который привёл к багу, чтобы будущие реализации учитывали этот сценарий.

Retrospective (specify ext add retrospective) - post-implementation анализ. Вычисляет spec adherence score (0-100%): какой процент requirements из spec.md покрыт реализацией. Обнаруживает drift между спецификацией и кодом. Предлагает обновления specs, но при require_approval: true ни одно изменение не применяется без одобрения инженера.

adherence_threshold: 95
drift_tolerance: 5
require_approval: true
track_trends: true

Публикация extension

Требования: valid extension.yml manifest, public GitHub repo, open-source лицензия, README, тестирование на реальном проекте. Review 3-7 рабочих дней.

Case study: кастомизация под внутренний стек

Дефолтный Spec Kit рассчитан на greenfield и GitHub. На реальном brownfield-проекте (Rails monorepo, GitLab, тикеты в Jira) пришлось подрезать дефолты и заменить часть команд под внутренние конвенции. Итоговая инициализация - Spec Kit под Claude с адаптацией под существующий стек команды.

Ключевой плюс github/spec-kit в этом сценарии - модульность. Skills, scripts, templates, hooks и extensions лежат отдельными файлами в .specify/ и .claude/, поэтому любую фазу можно выключить, переписать или заменить своей. У нас это вылилось в две стороны кастомизации: убрали то, что дублирует существующие процессы (constitution, навязываемое соглашение по именам веток, auto-update root CLAUDE.md), и добавили нужное - community-extension staff-review для код-ревью после implement и самописный skill /speckit-update-domain-docs, который фиксирует новые знания в domain-specific CLAUDE.md после выполнения задачи.

Кастомизации

• Директории specs по Jira-тикетам. Вместо авто-инкремента 001-feature/, 002-feature/ используется specs/<TICKET-ID>-feature/. /speckit-specify требует тикет как обязательный аргумент - это даёт traceability spec ↔ ticket без дополнительного extension
• Валидация веток. Принимается любое имя ветки, блокируются только protected (main/master/develop). Создание и переключение веток - вручную, без автоматики spec-kit
• Root CLAUDE.md редактируется только вручную. Дефолтный auto-update через update-agent-context.sh отключён. Доменные знания живут в per-domain CLAUDE.md (архитектура проекта - модульный монолит с несколькими доменами, у каждого своя документация)
• Дефисная нотация команд. Spec Kit местами использует точечную нотацию (/speckit.git.commit) в prompts у hooks. Заменено на /speckit-git-commit - Claude Code ожидает дефисы в slash-командах

Установленные skills

Что убрано

• speckit-constitution - роль constitution уже играют существующие CLAUDE.md (root + domain-specific)
• speckit-taskstoissues, speckit-git-remote, speckit-git-initialize - GitHub-specific, проект на GitLab
• speckit-git-feature, speckit-git-validate - ветки создаются вручную

План проверки

• /speckit-specify <TICKET-ID> ... создаёт specs/<TICKET-ID>-feature-name/spec.md
• /speckit-plan читает .specify/feature.json и генерирует plan без правок root CLAUDE.md
• /speckit-tasks предлагает следующий шаг (/speckit-analyze или /speckit-implement)
• /speckit-implement выполняет задачи и предлагает /speckit-staff-review-run
• Hook prompts используют дефисный формат (/speckit-git-commit, не /speckit.git.commit)
• check_feature_branch принимает любую non-protected ветку

Ограничения

Overhead спецификаций. Constitution, templates, specs, plans, tasks - всё нужно поддерживать. Для маленьких проектов overhead может превышать пользу. Spec Kit оправдан при командной разработке и кодовых базах, где контекст не помещается в одну сессию агента.

Устаревание артефактов. Drift detection (Reconcile, Spec Sync) помогает, но не панацея. Устаревшая спецификация хуже отсутствующей - агент уверенно реализует неактуальные требования. Регулярный аудит при каждом рефакторинге обязателен.

Constitution как single point of failure. Плохо написанная constitution порождает плохие спецификации. Ошибки на этом уровне каскадируются во все фичи.

Нет Confluence интеграции. Для команд с knowledge base в Confluence остаётся gap. DocGuard и Spec Sync частично закрывают задачу валидации, но прямой синхронизации нет.

Безопасность extensions. Community extensions не проходят security audit от GitHub. 40+ extensions от разных авторов - ответственность за проверку на команде.

Разная глубина интеграции. 25+ агентов «поддерживаются», но глубина различается. Claude Code и Copilot - нативная интеграция через skills. Для менее популярных агентов - --ai generic с базовым набором.

Источники и смежные статьи

Исходники и документация Spec Kit

• github/spec-kit - основной репозиторий, документация и исходники.
• Spec Kit community extensions - каталог расширений.
• brownfield-bootstrap - community extension для brownfield-инициализации.

Книги и статьи о spec-driven подходах

• Kent Beck, «Test-Driven Development: By Example» (Addison-Wesley, 2002) - канонический источник по TDD; практика «сначала тест, потом код».
• Dan North, «Introducing BDD» (Better Software, March 2006) - первая публикация термина Behavior-Driven Development и формата Given/When/Then.
• Bertrand Meyer, «Object-Oriented Software Construction», 2nd edition (Prentice Hall, 1997) - Design by Contract как ранний предшественник spec-driven подхода.
• OpenAPI Initiative - стандарт описания REST API как первичного артефакта.
• Brandur Leach - публикации Stripe-инженера о spec-as-source-of-truth для API.
• Karate framework - test-as-spec, BDD-стилизованные API-тесты, исполняемые как контракт.

Смежные статьи на этом сайте

• SDLC для AI-агентов - общая модель spec-driven workflow, сравнение шести фреймворков (Spec Kit, BMAD, OpenSpec, cc-sdd, SPECTRE, IDD).
• Инфраструктура контекста для AI-агентов - трёхуровневая архитектура памяти, constitution как Tier 1.
• Как устроен Claude Code - skills, субагенты, hooks - механизмы, через которые Spec Kit интегрируется с Claude Code.