Урок 2.8. GitHub Spec Kit

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

GitHub Spec Kit полезен как один из самых понятных baseline-инструментов для Specification-Driven Development. Он показывает простую, но важную идею:

Сначала формулируем, что строим.
Потом планируем, как строим.
Потом разбиваем на tasks.
И только затем реализуем.

Для AI agent это критично. Если сразу попросить agent написать код, он будет заполнять пробелы собственными assumptions. Spec Kit заставляет вынести эти assumptions в artifacts, которые можно читать, обсуждать, проверять и версионировать в Git.

Основная идея

Spec Kit - это intent-driven harness для coding agents. Он делает specification главным артефактом разработки.

Вместо такого сценария:

Prompt
-> code
-> maybe tests
-> "done"

Spec Kit предлагает:

constitution
-> specification
-> clarification
-> technical plan
-> task breakdown
-> analysis
-> implementation

Главное отличие от ручного spec.md в том, что Spec Kit дает standardized workflow и commands. Агент не просто получает документ. Он проходит этапы в заранее заданном порядке.

Ключевые термины

Термин	Значение
Constitution	Governing principles проекта: testing standards, quality rules, UX principles, performance constraints.
Specify	Этап описания what and why: behavior, users, requirements, acceptance criteria.
Clarify	Этап устранения ambiguity до technical planning.
Plan	Этап technical design: stack, architecture, data model, risks, trade-offs.
Tasks	Этап декомпозиции plan в executable implementation tasks.
Analyze	Cross-artifact проверка consistency, coverage и gaps.
Implement	Выполнение tasks агентом с учетом specs and plans.
Preset	Настройка формата и правил workflow под команду или domain.
Extension	Добавление новых commands/capabilities к Spec Kit.

Как это устроено

flowchart TD A[Project principles] --> B[Constitution] B --> C[Feature idea] C --> D[Specify] D --> E[Clarify] E --> F[Plan] F --> G[Tasks] G --> H[Analyze] H --> I[Implement] I --> J[Verify and review]

Constitution стоит в начале не случайно. Если у проекта есть принципы вроде "Library-first", "Strict TDD", "No new dependencies without justification", agent должен учитывать их во всех следующих artifacts.

Базовый workflow

Типовая последовательность:

/speckit.constitution
-> /speckit.specify
-> /speckit.clarify
-> /speckit.plan
-> /speckit.tasks
-> /speckit.analyze
-> /speckit.implement

Форма command зависит от agent integration. В slash-command environments это часто /speckit.*. В skills-based environments команда может выглядеть иначе. Важно понимать не синтаксис, а phases.

Как пользоваться

На обзорном уровне:

Установить Specify CLI по официальной инструкции.
Инициализировать проект с нужной integration.
Создать или обновить constitution.
Создать feature specification через specify.
Запустить clarification, если требования неполные.
Создать technical plan.
Сгенерировать tasks.
Выполнить analyze перед implementation.
Запустить implement или попросить agent реализовать выбранную часть tasks.
Проверить diff, tests и evidence.

Пример initialization для Codex-style skills mode может выглядеть так:

specify init --here --integration codex --integration-options="--skills"

Не запоминайте эту строку как вечную. Инструменты быстро меняются. В production всегда сверяйтесь с README и docs.

Какие artifacts появляются

Типичные artifacts:

.specify/
  memory/
    constitution.md
  templates/
  specs/
    <feature>/
      spec.md
      plan.md
      tasks.md
      research.md
      quickstart.md

Набор файлов может отличаться по версии и preset, но смысл остается:

constitution.md задает постоянные правила проекта;
spec.md описывает what and why;
plan.md описывает how;
tasks.md делает work executable;
research.md фиксирует researched decisions;
quickstart.md помогает проверить usage scenario.

Spec Kit как change lifecycle

Важно не воспринимать Spec Kit как "генератор документов перед кодом". Более полезная mental model:

каждая feature = отдельный change lifecycle

Внутри lifecycle есть несколько checkpoints:

Checkpoint	Что проверяется
Constitution	Не нарушает ли feature постоянные принципы проекта.
Spec	Понятны ли users, scenarios, requirements, non-goals и acceptance criteria.
Clarify	Нет ли unresolved ambiguity, из-за которой agent будет угадывать.
Plan	Есть ли технический путь, constraints, risks, research и rejected alternatives.
Tasks	Можно ли выполнить работу маленькими проверяемыми шагами.
Analyze	Нет ли противоречий между spec, plan и tasks.
Implement	Изменения соответствуют tasks, а не новым догадкам агента.

Такой lifecycle ближе к spec-anchored подходу: artifacts живут в repository и могут быть review'ены до implementation. Но нужно понимать границу. Если spec создается только на время feature branch и после merge перестает обновляться, это spec-first, а не полноценный long-lived source of truth.

Для курса это не проблема. Начинать можно со spec-first. Но зрелый процесс должен отвечать:

Что происходит со spec после merge?
Он архивируется как история change?
Или обновляет current product specification?

Context grounding: discovery и validation

Исследования agent workflows показывают полезный паттерн: качество растет, когда агент получает context не только в начале задачи, но и проходит validation после каждой фазы.

В Spec Kit это можно применить так:

Before phase:
- найти relevant specs/docs/code/tests;
- проверить constitution;
- определить missing context.

After phase:
- проверить artifact checklist;
- найти contradictions;
- сравнить output с previous artifacts;
- остановиться, если нужен human decision.

Пример для /speckit.plan:

Before plan:
- прочитать approved spec;
- найти existing architecture patterns;
- найти похожие tests;
- проверить constraints из constitution.

After plan:
- проверить, что каждый requirement покрыт design decision или task direction;
- отметить risks и rejected alternatives;
- не переходить к tasks, если есть unresolved open question.

Это важная мысль: SDD workflow становится сильнее, когда между фазами есть не только "следующая команда", но и context-grounding checks. Иначе agent может механически создать красивые файлы, которые не согласованы между собой.

Пример: Taskify project creation

Feature:

Build project creation in Taskify.
Users can create projects, choose a Kanban template,
and invite predefined team members.

Плохой prompt:

/speckit.implement Build project creation.

Лучше:

/speckit.specify
Build project creation for Taskify.

Users:
- product manager
- engineers

Requirements:
- user can create project with name and description
- user can choose empty or Kanban template
- duplicate project name in same team is not allowed
- no authentication changes in this feature

Non-goals:
- billing
- external invitations
- custom templates

После этого:

/speckit.clarify
/speckit.plan
/speckit.tasks
/speckit.analyze

Только затем:

/speckit.implement

Как давать задачу агенту

До implementation

Use Spec Kit workflow.
Do not implement yet.

First create/update the feature spec.
Then identify ambiguities and ask clarification questions.
Stop before technical planning.

После spec approval

The feature spec is approved.
Create the technical plan.
Make sure the plan follows `.specify/memory/constitution.md`.
Highlight risks, dependencies, and rejected alternatives.

Перед implementation

Generate tasks from the approved plan.
Each task must include:
- exact files or areas
- dependency order
- verification command
- whether it can run in parallel

Run analysis before implementation.

Когда Spec Kit полезен

Spec Kit хорошо подходит, когда:

команда учится SDD;
нужно явно разделить spec, plan и tasks;
feature достаточно большая для approval gates;
важно хранить artifacts в Git;
нужна project constitution;
нужно привести разных agents к одному process;
команда хочет расширяемый workflow через presets/extensions.

Когда не стоит брать

Spec Kit может быть лишним, если:

задача занимает 10 минут и не меняет behavior;
у проекта еще нет понятных tests;
команда не готова review artifacts;
нужен быстрый throwaway prototype;
existing process уже строгий и лучше подходит проекту.

Spec Kit не обязан быть первым шагом. Для маленького проекта можно начать с ручных spec.md, design.md, tasks.md, а затем перейти к Spec Kit, когда ручная дисциплина перестанет масштабироваться.

Типичные ошибки

Ошибка 1. Пропустить constitution

Без constitution agent создает spec и plan в вакууме. Он может выбрать architecture, dependencies или testing approach, которые не совпадают с принципами проекта.

Ошибка 2. Использовать specify как длинный prompt

Spec должен быть reviewable artifact, а не просто dumping ground для мыслей. Хороший spec имеет структуру, non-goals, acceptance criteria и edge cases.

Ошибка 3. Не запускать analyze

Analyze нужен, чтобы найти несогласованность между spec, plan и tasks. В AI workflow это особенно важно, потому что agent может создать красивый plan, который не покрывает часть requirements.

Ошибка 4. Выполнять все tasks одним огромным run

Даже если /speckit.implement умеет идти по tasks, для большой feature лучше работать staged:

Implement only setup and data model.
Stop after verification.

Потом продолжать следующую часть.

Checklist

Перед implementation:

constitution существует и актуальна;
spec содержит non-goals;
ambiguity закрыта через clarify;
plan объясняет architecture decisions;
tasks достаточно малы;
tasks содержат verification;
analyze не нашел blocking gaps;
allowed scope понятен;
есть test strategy.

Практика

Возьмите feature из своего проекта и напишите input для /speckit.specify.

Минимум:

Feature:
Users:
Requirements:
Non-goals:
Constraints:
Acceptance criteria:
Open questions:

Затем отдельно напишите, какие вопросы должен задать /speckit.clarify.

Критерии готовности

После урока студент должен уметь:

объяснить Spec Kit как SDD harness;
описать роль constitution;
назвать основные phases Spec Kit;
понять разницу между specify, plan и tasks;
написать initial prompt для feature spec;
объяснить, почему analyze важен перед implementation.

Краткое резюме

GitHub Spec Kit дает простую, ясную модель SDD для AI agents: сначала principles, затем specification, затем plan, tasks, analysis and implementation. Его главная ценность - не в магии commands, а в том, что он делает intent and planning visible in Git.

Вопросы для самопроверки

Зачем нужна constitution?
Чем /speckit.specify отличается от /speckit.plan?
Почему clarify должен идти до technical planning?
Что проверяет analyze?
Когда Spec Kit будет слишком тяжелым?

Источники для актуализации

GitHub Spec Kit repository: https://github.com/github/spec-kit
Spec Kit documentation: https://github.github.com/spec-kit/

Что дальше

Следующий урок разберет Get Shit Done / GSD - lightweight SDD и context engineering system, который делает акцент на context rot, phase loop и практическое shipping.

Глубокий разбор Spec Kit по официальной документации - установка, процессы (SDD, багфикс, оценка идей), справочники CLI и агентных команд, кастомизация через extensions/presets/workflows/bundles, монорепозитории и экосистема сообщества - вынесен в отдельный модуль 16.