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

6 апреля 2026

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

Spec Kit от GitHub - реализация этого подхода. CLI-фреймворк с шестью фазами workflow, bash-скриптами для управления артефактами, 40+ extensions для валидации и интеграций с Jira, GitHub Projects и CI/CD. Поддерживает 25+ AI-агентов, но статья фокусируется на связке с Claude Code - от первой установки до production workflow в существующем проекте.

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

Зачем нужен 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 в существующую кодовую базу
• 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 — каталог расширений.