GitHub Spec Kit

Spec Kit от GitHub — набор шаблонов, навыков агента и CLI specify, который ведёт фичу от конституции через спецификацию, план и задачи к коду и сверке с ним. Установка, структура папок, что создаёт каждая команда, расширения, практика на листе ожидания онлайн-школы, сильные стороны и ограничения.

УРОКsdd/sdd-3-tools/01-spec-kit.mdx2 чУрок 1 из 3

После урока вы сможете

Установить CLI specify, подготовить проект под своего агента и объяснить, зачем нужна каждая появившаяся папка
Пройти цикл Spec Kit — конституция, specify, clarify, plan, checklist, tasks, analyze, implement, converge — и знать, какие файлы пишет каждый шаг
Читать и править артефакты Spec Kit на примере листа ожидания онлайн-школы и возвращаться к нужному шагу, когда проверка нашла проблему
Оценить сильные стороны и ограничения Spec Kit и договориться в команде, что делать со спецификацией после реализации

Зачем это нужно

В модуле SDD.2 вы писали спецификацию, план, задачи и конституцию руками: требования, план и контракты, задачи и принципы. Это работает, но каждый раз приходится заново объяснять агенту, какой документ писать, в каком порядке и что в нём должно быть. Spec Kit упаковывает этот процесс: шаблоны документов, готовые инструкции для агента и маленькую программу, которая раскладывает всё по местам.

Владелец курса описал SDD так: хорошенько подумать на этапе планирования, родить тонну md-файлов, скормить их агенту и спокойно идти пить кофе. Spec Kit — самый честный станок для производства этой «тонны»: около десятка документов на фичу. Разберём роль каждого и где кофе пить можно, а где нужно сидеть и читать.

Что такое Spec Kit

Spec Kit — открытый набор инструментов GitHub (лицензия MIT, первый коммит — 21 августа 2025 года). README описывает его как набор, который даёт агентам для кода структурированные процессы, переиспользуемые шаблоны и задокументированные результаты.

Процессов три, и это независимые точки входа, а не обязательные фазы:

Процесс	Зачем	Где живёт
Spec-Driven Development	построить фичу или приложение по спецификации	в ядре, ставится всегда
Исправление багов (bug fixing)	разделить диагностику, исправление и проверку	расширение `bug`
Оценка идеи (idea assessment)	собрать доказательства и решить «делать / уточнить / бросить»	расширение `assess`

Устроен Spec Kit из трёх частей:

CLI specify на Python. Работает в терминале: создаёт проект, ставит расширения и интеграции.
Папка .specify/ в вашем репозитории: шаблоны документов, вспомогательные скрипты, конституция.
Навыки агента speckit-* в папке вашего агента. Это обычные markdown-файлы с подробной инструкцией: что прочитать, какой шаблон заполнить, куда записать результат.

Третий пункт — главный. Про навыки агента вы читали в уроке SDD.1.2: в контексте лежит только короткое описание навыка, полный текст агент загружает, когда вы его вызываете. Spec Kit — это прежде всего десять хорошо написанных навыков.

Терминал и чат агента: не перепутайте

Самая частая ошибка новичка — набрать /speckit-specify в терминале. Команды Spec Kit живут в двух местах:

Где	Что делаете	Примеры
Терминал	ставите Spec Kit, создаёте проект, подключаете расширения	`specify init`, `specify extension add bug`, `specify integration list`
Чат агента	ведёте фичу по шагам процесса	`/speckit-constitution`, `/speckit-specify`, `/speckit-plan`

Внутри агента команда пишется по-разному — смотря как агент загружает навыки. По таблице из docs/reference/integrations.md:

Агент или режим	Как вызвать шаг specify
Claude Code, GitHub Copilot (режим навыков по умолчанию) и другие агенты с навыками: Zed, Grok Build, Devin for Terminal…	`/speckit-specify`
Codex, Command Code, ZCode	`$speckit-specify`
Kimi Code	`/skill:speckit-specify`
Агенты с командными файлами вместо навыков (например, Gemini CLI) и справочник документации	`/speckit.specify`

Дальше в уроке — форма для Claude Code: /speckit-specify. Это слэш-команда: вы печатаете её в чате, агент находит файл навыка и выполняет инструкцию.

Точка или дефис: как правильно на октябрь 2026

Обе записи правильные, но означают разное. /speckit.specify с точкой — каноническое имя команды: так её называют справочник docs/reference/agentic-sdd.md, манифест spec-driven.md и внутренний реестр (specify artifact list показывает command:speckit.specify). Так же команда вызывается у агентов, которым Spec Kit ставит командные файлы. /speckit-specify с дефисом — имя навыка: у агентов с навыками точку заменяют дефисом, потому что имя навыка — это имя папки. В уроках модулей SDD.1 и SDD.2 (например, SDD.1.1 и SDD.2.1) и в ссылках на справочник в модуле SDD.4 команды записаны с точкой, как в справочнике; в чате Claude Code набирайте их с дефисом.

Почему в статьях и видео встречается разное, видно по CHANGELOG:

Версия и дата	Что изменилось
0.4.0, 23 марта 2026	Codex и Antigravity переведены на навыки
0.4.5, 2 апреля 2026	Claude Code получает команды как навыки в `.claude/skills` вместо командных файлов
0.7.1, 15 апреля 2026	ключ `specify init --ai` объявлен устаревшим, вместо него `--integration`
0.10.0, 9 июня 2026	ключи `--ai`, `--ai-commands-dir`, `--ai-skills` удалены
0.11.2, 18 июня 2026	добавлена команда `/speckit.converge`
0.16.0, 5 августа 2026	GitHub Copilot по умолчанию ставится в режиме навыков
1.0.0, 21 августа 2026	первый мажорный релиз

Практический вывод: инструкция с specify init --ai claude или с цепочкой без converge написана для версии до лета 2026 года. Какую форму понимает ваш агент, подскажет сам specify init: в конце вывода он печатает список команд в нужном написании.

Установка и что появляется в репозитории

По README нужны Python 3.11+, менеджер пакетов uv и поддерживаемый агент на Linux, macOS или Windows. Постоянная установка CLI и создание проекта:

uv tool install specify-cli                 # CLI specify с PyPI
specify init school --integration claude    # новая папка school под Claude Code
cd school

Попробовать без установки можно одноразовым запуском через uvx — он скачает Spec Kit во временное окружение:

uvx --from git+https://github.com/github/spec-kit.git specify init school --integration claude

Ключ --integration выбирает агента. Команда specify integration list в версии из main выводит 42 интеграции, среди них claude, copilot, codex, cursor-agent, gemini, qwen, kiro-cli и generic для любого другого агента. Без ключа init спросит агента интерактивно. Для уже существующего кода есть specify init --here --integration claude: тогда Spec Kit ставится в текущую папку, а ваш код не трогает.

Вот что в итоге оказывается в репозитории. Это настоящий результат specify init school --integration claude, запущенного 6 октября 2026 года (дерево сокращено: девять папок навыков устроены одинаково):

school/
├── .claude/
│   └── skills/
│       ├── speckit-analyze/SKILL.md
│       ├── speckit-checklist/SKILL.md
│       ├── speckit-clarify/SKILL.md
│       ├── speckit-constitution/SKILL.md
│       ├── speckit-converge/SKILL.md
│       ├── speckit-implement/SKILL.md
│       ├── speckit-plan/SKILL.md
│       ├── speckit-specify/SKILL.md
│       ├── speckit-tasks/SKILL.md
│       └── speckit-taskstoissues/SKILL.md
└── .specify/
    ├── init-options.json          # что выбрали при init: агент, скрипты, нумерация фич
    ├── integration.json           # какие интеграции стоят
    ├── integrations/              # манифесты установленных файлов (с хешами)
    ├── memory/
    │   └── constitution.md        # конституция — пока это шаблон с заглушками
    ├── scripts/bash/              # 6 скриптов: создать папку фичи, подготовить план и т. п.
    ├── templates/                 # spec, plan, tasks, checklist, constitution
    └── workflows/speckit/workflow.yml   # автоматический прогон цикла с остановками на ревью

Обратите внимание, чего здесь нет:

Нет CLAUDE.md. Сам Spec Kit файл памяти агента не трогает. Если хотите, чтобы он вписывал туда ссылку на текущий план, поставьте расширение agent-context (specify extension add agent-context).
Нет git-репозитория и веток. Нумерованные ветки вида 001-feature-name делает необязательное расширение git. Активную фичу Spec Kit помнит в файле .specify/feature.json, а не по текущей ветке.
Нет папки specs/. Она появится при первом /speckit-specify.

В конце вывода init есть предупреждение: агенты иногда хранят в своей папке токены и личные настройки, поэтому подумайте, что из .claude/ добавить в .gitignore. Навыки коммитить стоит — это часть процесса команды; локальные настройки и всё, где могут оказаться секреты, — нет.

Цикл SDD в Spec Kit

README формулирует цикл одной строкой: конституция — один раз на проект, а specify → plan → tasks → implement → converge — на каждую фичу. Между шагами можно вставить три необязательные проверки качества.

flowchart LR
C["constitution<br/>(один раз)"] --> S["specify"]
S --> CL["clarify<br/>(по желанию)"] --> P["plan"]
S --> P
P --> CH["checklist<br/>(по желанию)"] --> T["tasks"]
P --> T
T --> A["analyze<br/>(по желанию)"] --> I["implement"]
T --> I
I --> CV["converge"]
CV -->|"дописал задачи"| I
CV -->|"Converged"| PR["ревью и PR"]

Цикл Spec Kit: обязательные шаги и три необязательные проверки

Что делает каждый шаг и что он пишет на диск (по docs/reference/agentic-sdd.md и текстам навыков):

Команда в чате	Что делает	Что появляется или меняется
`/speckit-constitution`	записывает принципы проекта, ставит версию по правилам MAJOR/MINOR/PATCH	`.specify/memory/constitution.md`
`/speckit-specify`	пишет спецификацию «что и зачем» по описанию фичи	`specs/001-<имя>/spec.md`, `checklists/requirements.md`, `.specify/feature.json`
`/speckit-clarify`	задаёт до 5 точных вопросов и вписывает ответы в спецификацию	раздел `## Clarifications` в `spec.md`
`/speckit-plan`	технический план по спецификации и вашему стеку	`plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`
`/speckit-checklist`	чек-лист качества требований — «юнит-тесты для требований»	новый файл в `checklists/`
`/speckit-tasks`	задачи по фазам с зависимостями и метками параллельности	`tasks.md`
`/speckit-analyze`	только читает: ищет противоречия и пробелы между spec, plan и tasks	ничего, выводит отчёт
`/speckit-implement`	выполняет задачи по порядку, отмечает сделанные `[X]`	код, тесты, отметки в `tasks.md`
`/speckit-converge`	сверяет код с артефактами	либо ничего (Converged), либо раздел Convergence в конце `tasks.md`

Короткий путь для небольших фич — specify, plan, tasks, implement, converge. Полный путь для продакшена добавляет clarify, checklist и analyze. Ещё есть /speckit-taskstoissues: превращает задачи в issues на GitHub; эта функция переезжает в расширение github.

Конституция в Spec Kit

Конституцию вы уже писали в уроке SDD.2.3. В Spec Kit у неё две особенности. Во-первых, шаблон плана содержит раздел Constitution Check с пометкой «GATE: Must pass before Phase 0 research. Re-check after Phase 1 design» — план проверяют на соответствие принципам дважды. Во-вторых, если план нарушает принцип, нарушение нужно обосновать в таблице Complexity Tracking: что нарушаем, зачем, почему простая альтернатива не подошла.

Манифест spec-driven.md предлагает девять «статей» в качестве примера: сначала библиотека, интерфейс командной строки у каждой библиотеки, тесты сначала, простота, никаких лишних абстракций, интеграционные тесты на реальной базе. Это пример, а не закон. Шаблон constitution-template.md даёт пустые слоты, и /speckit-constitution заполняет их вашими принципами.

Что происходит со спецификацией после реализации

В уроке SDD.1.1 были три уровня по Биргитте Бёккелер: spec-first, spec-anchored и spec-as-source. Документация Spec Kit сама ссылается на эту классификацию и добавляет второй вопрос: что делать с файлами фичи, когда требования меняются. Выбор она оставляет команде — это модель сохранения спецификаций:

Модель	Правило	Подходит, когда	Риск
Flow-forward	готовая папка фичи не меняется, новые требования — новая папка `specs/00N-…`	важны аудит и история решений	контекст фичи размазан по нескольким папкам
Flow-back	правка начинается в любом артефакте или в коде, потом всё сводят	маленькая команда, быстрые итерации	тихое расхождение spec и кода
Living spec	сначала правят `spec.md`, план и задачи выводят заново	спецификация — контракт	теряются обоснования из старого плана

По умолчанию Spec Kit ближе всего к spec-first: каждая фича получает свою папку, и папки копятся. Чтобы получить spec-anchored, нужна договорённость — например, living spec, записанная в конституции.

Расширения, пресеты и рабочие процессы

Spec Kit расширяется четырьмя способами: расширения (extensions) добавляют команды, пресеты (presets) меняют шаблоны и формулировки (в том числе переводят процесс на другой язык), рабочие процессы (workflows) автоматизируют шаги, бандлы (bundles) собирают всё это под роль. С Spec Kit поставляются пять расширений:

Расширение	Что даёт
`bug`	`/speckit-bug-assess` → `/speckit-bug-fix` → `/speckit-bug-test`; отчёты в `.specify/bugs/<slug>/`, вердикт `verified`, `partial` или `failed`
`assess`	`/speckit-assess-intake` → `research` → `define` → `shape` → `decide`; итог в `.specify/assessments/<slug>/`: go, needs-clarification или kill
`git`	инициализация репозитория, нумерованные ветки, автокоммиты до и после шагов
`agent-context`	поддерживает блок со ссылкой на текущий план в `CLAUDE.md`, `AGENTS.md` и т. п.
`github`	задачи из `tasks.md` в issues на GitHub

Ставятся они из терминала: specify extension add bug. В каталоге сообщества на 6 октября 2026 года 178 расширений, и README каталога предупреждает: мейнтейнеры проверяют только формат записи, а не код. Расширение — инструкции, которые агент выполнит с вашими правами; читайте их перед установкой, как чужой скрипт (об инъекциях — в уроке SDD.1.2).

Рабочий процесс speckit из .specify/workflows/ прогоняет specify → plan → tasks → implement сам и останавливается на «воротах» (gate), где человек одобряет или отклоняет результат:

specify workflow run speckit -i spec="Лист ожидания для заполненных потоков"

Практика: лист ожидания онлайн-школы

Сквозной пример — контекст Набора онлайн-школы из программы DDD. Запись на поток уже умеет учитывать вместимость. Новая фича: если мест нет, студент встаёт в лист ожидания (Waitlist); освободившееся место предлагается первому в очереди (FIFO), у него 24 часа на подтверждение. Числа — условия учебного примера.

Шаги ниже делаются на вашем компьютере с вашим агентом. Терминальные команды и их вывод в уроке настоящие. Тексты документов, которые пишет агент, — наш пример на русском: у вас они будут другими, потому что модель недетерминирована. Шаблоны Spec Kit приведены в оригинале на английском (MIT).

Шаг 1. Создать проект

uv tool install specify-cli
specify init school --integration claude
cd school
git init && git add . && git commit -m "Spec Kit: init"

Сокращённый вывод init (в песочнице без агента мы добавили ключи --script sh --non-interactive --ignore-agent-tools; у вас они не нужны):

Initialize Specify Project
├── ● Install integration (Claude Code)
├── ● Constitution setup (copied from template)
└── ● Finalize (project ready)

Project ready.
│  2. Start Claude in this project directory; spec-kit skills were installed to .claude/skills
│  3. Start using skills with your coding agent:
│     3.1 /speckit-constitution - Establish project principles
│     3.2 /speckit-specify - Create baseline specification

Ожидаемый результат: дерево как в разделе «Установка»: десять папок в .claude/skills/ и папка .specify/. Коммит нужен, чтобы каждый следующий шаг был виден как дифф: Spec Kit сам git не инициализирует.

Шаг 2. Конституция

Запустите агента в папке проекта (claude) и вызовите навык:

/speckit-constitution Проект — модуль Набора онлайн-школы на Python 3.12. Принципы: тесты сначала — каждый
сценарий приёмки из spec.md становится тестом pytest до кода; имена в коде только из глоссария школы (Cohort,
Enrollment, Waitlist, EnrollmentStatus); простота — стандартная библиотека и SQLite, новая зависимость только
с обоснованием; все документы пиши на русском, заголовки шаблонов не переводи.

Что изменится: только .specify/memory/constitution.md. Заглушки вида [PRINCIPLE_1_NAME] заменятся принципами, внизу появится строка версии, а в начале файла — HTML-комментарий Sync Impact Report о том, что поменялось. Пример результата:

# Конституция модуля Набора онлайн-школы

## Core Principles

### I. Тесты сначала (NON-NEGOTIABLE)
Каждый сценарий приёмки из spec.md превращается в тест pytest до реализации.
Тест должен упасть до того, как появится код.

### II. Единый язык
Имена в коде и документах берутся из глоссария школы. Синонимы (Order, Booking) запрещены.

### III. Простота
Стандартная библиотека Python и SQLite. Новая зависимость — только с обоснованием в research.md.

**Version**: 1.0.0 | **Ratified**: 2026-10-06 | **Last Amended**: 2026-10-06

Строчка «тесты сначала» здесь не для красоты. Шаблон задач Spec Kit по умолчанию говорит: «Tests are OPTIONAL — only include them if explicitly requested». Если тесты не потребовать в конституции или спецификации, задач на тесты в tasks.md может не оказаться вовсе.

Шаг 3. Спецификация

/speckit-specify Лист ожидания для потоков онлайн-школы. Если на потоке нет свободных мест, студент может
встать в лист ожидания. Когда место освобождается (отмена или автоотмена неоплаченной записи), его предлагают
первому в листе ожидания; у него 24 часа на подтверждение, потом предложение переходит следующему.

Что появится:

specs/
└── 001-waitlist/
    ├── spec.md
    └── checklists/
        └── requirements.md      # встроенный чек-лист качества спецификации
.specify/feature.json            # {"feature_directory": "specs/001-waitlist"}

Шаблон spec-template.md задаёт разделы: пользовательские истории с приоритетами P1, P2, P3, каждая проверяемая независимо, сценарии приёмки, крайние случаи, функциональные требования FR-001…, ключевые сущности, измеримые критерии успеха SC-001… и допущения. Фрагмент шаблона (MIT):

### User Story 1 - [Brief Title] (Priority: P1)

**Independent Test**: [Describe how this can be tested independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

### Functional Requirements

- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]

Так может выглядеть заполненный фрагмент нашей фичи:

### User Story 1 - Встать в лист ожидания (Priority: P1)

Студент хочет попасть на заполненный поток и встаёт в очередь, чтобы получить место, если оно освободится.

**Independent Test**: заполнить поток, записать ещё одного студента и проверить, что он стал первым в листе ожидания.

**Acceptance Scenarios**:

1. **Given** поток вместимостью 20 и 20 активных записей, **When** студент записывается,
   **Then** он попадает в лист ожидания под номером 1.
2. **Given** студент уже стоит в листе ожидания потока, **When** он записывается снова,
   **Then** второй раз в очередь он не попадает.

### Functional Requirements

- **FR-001**: Система должна добавлять студента в конец листа ожидания, если свободных мест нет.
- **FR-002**: Система должна предлагать освободившееся место первому в листе ожидания.
- **FR-003**: Предложение должно действовать 24 часа, затем место предлагается следующему.
- **FR-004**: После подтверждения студент получает запись [NEEDS CLARIFICATION: подтверждение — это сразу
  оплата или только согласие на место, после которого идут обычные 48 часов на оплату?]

## Success Criteria *(mandatory)*

- **SC-001**: Освободившееся место предлагается студенту из листа ожидания не позже чем через 5 минут.

Обратите внимание на нумерацию: здесь FR-… — требования, а SC-… — измеримые критерии успеха. В формате курса из урока SDD.2.1 всё иначе: требования — REQ-…, а SC-… — сценарии «Дано / Когда / Тогда». Подробная таблица соответствий — ниже, после практики.

Пометка в FR-004 — тот самый открытый вопрос глоссария из урока DDD.1.2: что подтверждает студент за 24 часа. В программе DDD его уже закрыли в уроке DDD.2.3: подтверждается согласие занять место, после чего появляется обычная запись «ожидает оплаты» с 48 часами на оплату. Но агент этого не знает, пока вы не скажете, и правильно делает, что спрашивает, а не угадывает. Навык speckit-specify ограничивает такие пометки тремя на спецификацию и велит в остальных местах брать разумные значения по умолчанию и записывать их в раздел Assumptions. Значит, раздел допущений надо читать особенно внимательно: там решения, которые агент принял за вас.

Шаг 4. Уточнения

/speckit-clarify Сосредоточься на подтверждении места из листа ожидания и на сроках.

Навык задаёт до пяти вопросов, по одному, обычно с вариантами ответа. Каждый принятый ответ он вписывает в spec.md и правит затронутые требования. Что изменится: только spec.md (и, возможно, отметки встроенного чек-листа):

## Clarifications

### Session 2026-10-06

- Q: Что подтверждает студент из листа ожидания за 24 часа? → A: Согласие занять место; пока идут 24 часа,
  место закреплено за ним; после подтверждения создаётся запись «ожидает оплаты» с обычными 48 часами на оплату.

Ответ мы взяли из решения DDD.2.3, а пометка [NEEDS CLARIFICATION] в FR-004 после этого шага исчезает.

Шаг 5. План

/speckit-plan Python 3.12, стандартная библиотека, SQLite, pytest. Лист ожидания хранится внутри агрегата
Cohort модуля src/school/enrollment.py. Истечение предложений проверяет периодическая задача.

Под капотом навык сначала запускает скрипт .specify/scripts/bash/setup-plan.sh --json, который копирует шаблон плана в папку фичи. Мы запустили этот скрипт сами — вот его настоящий вывод (пути сокращены):

Copied plan template to …/school/specs/001-waitlist/plan.md
{"FEATURE_SPEC":"…/specs/001-waitlist/spec.md","IMPL_PLAN":"…/specs/001-waitlist/plan.md",
 "FEATURE_DIR":"…/specs/001-waitlist","BRANCH":"001-waitlist"}

Дальше агент заполняет plan.md (технический контекст, Constitution Check, структура проекта), в фазе 0 пишет research.md в форме «решение — обоснование — рассмотренные варианты», в фазе 1 — data-model.md, contracts/ и quickstart.md со сценариями проверки. Что в них должно быть, разобрано в уроке SDD.2.2. Что появится:

specs/001-waitlist/
├── spec.md
├── checklists/requirements.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/

Пример раздела проверки по конституции в нашем плане:

## Constitution Check

- [x] I. Тесты сначала: сценарии US1–US2 → tests/integration/test_waitlist.py до кода
- [x] II. Единый язык: Waitlist, Cohort, Enrollment — из глоссария
- [x] III. Простота: только стандартная библиотека и sqlite3, новых зависимостей нет

Шаг 6. Задачи и проверка согласованности

/speckit-tasks
/speckit-analyze

/speckit-tasks создаёт tasks.md: фаза Setup, фаза Foundational (без неё ни одна история не начнётся), по фазе на каждую пользовательскую историю в порядке приоритета и фаза Polish. Формат строки — [ID] [P?] [Story] Описание с путём к файлу; [P] значит «можно параллельно». Пример:

## Phase 3: User Story 1 - Встать в лист ожидания (Priority: P1)

**Independent Test**: заполнить поток и записать ещё одного студента

- [ ] T005 [P] [US1] Тест «поток заполнен → студент в листе ожидания» в tests/integration/test_waitlist.py
- [ ] T006 [US1] Добавить Waitlist в агрегат Cohort в src/school/enrollment.py (после T005)

/speckit-analyze только читает и печатает отчёт: задача без требования, требование без задачи, план, который противоречит спецификации. Если отчёт не пустой, возвращайтесь к шагу-владельцу проблемы: требования — specify или clarify, дизайн — plan, задачи — tasks. Что изменится: появится tasks.md; analyze ничего не меняет.

Шаг 7. Реализация и сверка

/speckit-implement Выполни только фазы Setup и Foundational и остановись.
/speckit-implement Теперь User Story 1.
/speckit-converge

Для небольшой фичи хватит одного /speckit-implement, большую документация советует делать по фазам, проверяя каждую. Перед стартом implement считает отметки в чек-листах и спрашивает разрешения, если там остались пустые пункты. Сделанные задачи он помечает [X].

/speckit-converge сравнивает код со spec, plan и tasks и выводит находки по важности. Дальше один из двух исходов: «✅ Converged» — tasks.md не тронут ни на байт, можно идти на ревью; или в конец tasks.md дописан раздел ## Phase N: Convergence с новыми задачами — тогда снова implement и converge. Что изменится: код и тесты в src/ и tests/, отметки в tasks.md, возможно — раздел Convergence.

Итог

Сводка «шаг → файлы» — в таблице раздела «Цикл SDD в Spec Kit». Девять файлов документов на одну фичу из четырёх требований. Сколько из них вы реально прочитали? Ответ на этот вопрос — лучший показатель того, подходит ли вам полный путь.

Упражнения

В spec.md агент написал: «FR-005: Лист ожидания хранится в таблице waitlist SQLite с индексом по cohort_id». Что не так и куда это перенести?

Разбор

Это решение «как», а не требование «что». Шаблон спецификации прямо требует писать о том, что нужно пользователям и зачем, без стека, API и структуры кода. Таблица и индекс — место в plan.md или data-model.md. В спецификации останется проверяемое поведение: «студенты в листе ожидания обслуживаются в порядке постановки». Если хранить требование про SQLite в spec.md, при смене хранилища придётся менять спецификацию, хотя поведение не изменилось.

/speckit-analyze сообщил: «FR-004 не покрыто ни одной задачей; задача T012 не ссылается ни на одно требование». Что делать?

Разбор

Не править tasks.md руками наугад, а вернуться к шагу-владельцу. Сначала решить, нужна ли T012: если это лишняя «полезная» функция, её убирают; если она закрывает реальную потребность, значит, в спецификации не хватает требования — его добавляют через /speckit-specify или /speckit-clarify. Затем перегенерировать задачи /speckit-tasks, чтобы FR-004 получило задачу, и снова запустить /speckit-analyze до чистого отчёта.

Третий прогон /speckit-converge подряд снова дописывает задачи. Какие две причины вероятнее всего?

Разбор

Первая — спецификация размыта: требование можно понять по-разному, и converge каждый раз находит новое расхождение. Лечится уточнением спецификации, а не ещё одним прогоном. Вторая — фича слишком большая для одного контекста: агент на implement теряет детали. Лечится разбиением на несколько фич или реализацией по фазам. В обоих случаях человек должен прочитать находки converge, а не нажимать «повторить».

Школа через полгода меняет правило: предложение из листа ожидания действует не 24, а 12 часов. Как поступить в каждой из трёх моделей сохранения?

Разбор

Flow-forward: новая папка specs/00N-waitlist-offer-12h/ со ссылкой на 001-waitlist, старая остаётся историей. Living spec: правим FR-003 в specs/001-waitlist/spec.md, затем план, задачи, analyze, implement, converge. Flow-back: можно начать хоть с кода, но потом обязательно поправить spec.md, иначе следующий читатель поверит старым 24 часам.

Формат курса и шаблоны Spec Kit и OpenSpec

В модуле SDD.2 вы писали спецификации в формате курса. Инструменты используют похожие, но не одинаковые обозначения, и путаница в номерах — частая причина ошибок при ревью. Сопоставление на октябрь 2026 года (OpenSpec подробно — в следующем уроке):

Что	Формат курса (SDD.2.1)	Spec Kit, `spec-template.md`	OpenSpec, схема `spec-driven`
Требование	`- REQ-001: … система должна …`	`- FR-001: System MUST …`	`### Requirement: <название>` без номера; в тексте SHALL или MUST
Сценарий	`### SC-001: …` со строкой «Требования: REQ-…» и шагами Дано / Когда / Тогда	нумерованные Acceptance Scenarios внутри истории: Given / When / Then	`#### Scenario: <название>` внутри требования; пункты WHEN / THEN, в примерах документации — также GIVEN
Код `SC-…` означает	сценарий	измеримый критерий успеха (Success Criteria)	номеров нет
Пользовательская история	`US-1 (P1)`	`User Story 1 - … (Priority: P1)` с Independent Test	нет; «зачем» — в `proposal.md`
Неясность	`[УТОЧНИТЬ: вопрос]`	`[NEEDS CLARIFICATION: вопрос]`, не больше трёх	маркера нет; неизвестное — в Open Questions в `design.md`
Что не делаем	раздел «Вне рамок»	раздел Assumptions	Non-Goals в `design.md`
Связь сценария с требованием	строка «Требования: REQ-…»	сценарий лежит внутри истории; требования FR — отдельным списком	сценарий лежит внутри своего требования

Если команда пишет спецификации в формате курса, а работает через Spec Kit, есть два честных пути. Первый — принять нумерацию инструмента и договориться в конституции, что SC в спецификациях Spec Kit значит «критерий успеха». Второй — подменить шаблон своим: Spec Kit разрешает переопределять шаблоны в .specify/templates/overrides/ или пресетом. Хуже всего — смесь, где в одном файле SC-003 сценарий, а в соседнем — метрика.

Сильные стороны и ограничения

Сильные стороны:

Шаблоны дисциплинируют модель. Спецификация без стека, пометки [NEEDS CLARIFICATION] вместо догадок, чек-листы как самопроверка, ворота конституции против переусложнения.
Полный набор документов для серьёзной фичи: модель данных, контракты, исследование, сценарии проверки. Хорошо ложится на новый проект и на большую фичу, где нужен настоящий план.
Петля сверки. analyze до кода и converge после — встроенный ответ на вопрос «а сделали ли то, что специфицировали».
Агенты и открытость. 42 интеграции с одинаковым процессом, MIT, все навыки — читаемые markdown-файлы.

Ограничения:

Многословие. Девять документов на фичу из четырёх требований. Документы пишет агент за минуты, а читать их вам — и ревью markdown легко становится дороже ревью кода. Бёккелер в своей статье задаётся тем же вопросом.
Ложное чувство контроля. Навык — это инструкция, а не компилятор. Агент может её пропустить, понять по-своему, «отметить» задачу, не сделав её. converge снижает риск, но тоже выполняется моделью.
Один процесс на всё. Короткий путь есть, но даже он — пять вызовов на правку в одну строку. Для мелочи быстрее режим планирования агента без Spec Kit.
Нет единой картины текущего поведения. Папки фич копятся; «как сейчас работает отмена записи» приходится собирать из нескольких spec.md, если команда не держит дисциплину living spec. Именно эту боль решает OpenSpec из следующего урока.
Быстрые изменения. Синтаксис команд уже менялся; расширения сообщества никто не проверяет.

Проверь себя

Проверь себя6 вопросов

1 Вы набрали /speckit-specify Лист ожидания… в терминале и получили «command not found». Почему?Не установлен uvЭто навык агента: его вызывают в чате агента, а в терминале работает только CLI specifyНужно сначала выполнить /speckit-constitutionКоманда устарела, теперь пишут /speckit.specify

Терминал — для specify init, specify extension add и т. п. Шаги процесса выполняет агент: вы вызываете их в его чате. Точечная запись /speckit.specify — это форма из справочника документации, у Claude Code и Copilot навыки вызываются через дефис.

2 Какие файлы создаёт /speckit-plan? Выберите все верные.Можно выбрать несколько ответовplan.mdtasks.mddata-model.mdspec.mdresearch.md

План пишет plan.md, research.md, data-model.md, contracts/ и quickstart.md. spec.md создаёт specify, tasks.md — tasks.

3 Откуда команды Spec Kit узнают, над какой фичей вы сейчас работаете?По имени текущей git-веткиИз файла .specify/feature.json (или переменной SPECIFY_FEATURE_DIRECTORY)Из последнего изменённого файла в specs/Каждый раз спрашивают пользователя

Активная фича — это папка, записанная в .specify/feature.json. Ветки делает необязательное расширение git, но git checkout сам по себе активную фичу не меняет.

4 Какая команда после реализации сравнивает код со спецификацией, никогда не правит код и может только дописать задачи в tasks.md?/speckit-analyze/speckit-checklist/speckit-converge/speckit-clarify

converge работает в режиме «только дописать»: либо Converged и tasks.md не меняется, либо новые задачи в разделе Convergence. analyze тоже ничего не меняет, но запускается до реализации и сверяет документы между собой, а не с кодом.

5 Сколько пометок [NEEDS CLARIFICATION] самое большее разрешает оставить навык speckit-specify в одной спецификации? (целое число)

6 Команда хочет, чтобы spec.md всегда описывал текущее поведение, а план и задачи выводились из него заново. Какая это модель сохранения спецификаций?Flow-forwardFlow-backLiving specSpec-as-source

Living spec: сначала правят spec.md, потом перегенерируют plan.md и tasks.md. Spec-as-source — уровень по Бёккелер, где код целиком генерируется из спецификации; Spec Kit так не работает.

Итоги

Spec Kit — это CLI specify для терминала, папка .specify/ с шаблонами, скриптами и конституцией и десять навыков speckit-* для агента. Шаги процесса вызывают в чате агента, а не в терминале.
Цикл: конституция один раз, затем specify → plan → tasks → implement → converge на каждую фичу; clarify, checklist и analyze — необязательные проверки качества. Каждая команда пишет свои файлы в specs/00N-<имя>/.
Шаблоны держат модель в рамках: «что» без «как», пометки неясностей, ворота конституции. Но навык — инструкция, а не гарантия: читать результаты и диффы по-прежнему вам.
Расширения bug и assess дают процессы исправления багов и оценки идей; расширения сообщества не проверяются.
Что делать со спецификацией после реализации, Spec Kit оставляет команде: flow-forward, flow-back или living spec. Договоритесь заранее и запишите в конституцию.

Дальше: урок SDD.3.2 — OpenSpec. Там спецификации живут в одном месте и описывают текущее поведение системы, а каждая доработка оформляется как предложение изменения с дельтами требований. Это ответ на главную слабость Spec Kit в старых проектах.