Spec Kit 2026: установка и практика спецификационно-ориентированной разработки на Windows, macOS и Linux

Spec Kit, который сопровождает GitHub, превращает спецификационно-ориентированную разработку в CLI для установки и в навыки, которые вызывает агент. Пакет на PyPI называется specify-cli. Репозиторий исходников — github/spec-kit. Он не заменяет Cursor, Claude Code, GitHub Copilot и Codex. Он заставляет этих агентов сначала записать наблюдаемое поведение, затем выбор технологий и только потом правки репозитория. На ноябрь 2026 года Windows использует скрипты PowerShell напрямую. Сначала ставить WSL не нужно. Эта страница — про установку, дерево каталогов и порядок команд. Почему спецификация должна существовать раньше кода, написано в полном руководстве по спецификационно-ориентированной разработке. Где лежат файлы навыков — в руководстве по Agent Skills.

Почему «сделай мне доску» — уже неверный старт

Конфликт старого и нового способа конкретен. Старый способ держится на сессии. Цель, стек и раскладка папок уходят в один чат. Агент угадывает и правит файлы. Смените машину или человека — контекст исчез. Новый способ держится на артефактах. Принципы лежат в .specify/memory/constitution.md. Поведение и причина — в specs/<feature>/spec.md. Стек ждёт plan.md. Исполнимый порядок ждёт tasks.md. Активная функция — каталог, на который указывает .specify/feature.json, а не память о прошлом треде.

В 2026 году это проблема установки, а не отношения, по трём причинам. Во-первых, написание вызова зависит от агента. Cursor, Claude Code и режим skills по умолчанию в Copilot используют /speckit-specify. Codex использует $speckit-specify. Форма с точкой в документации — справочная запись. Во-вторых, установка через uv и ещё одна через pipx оставляют два бинарника specify. Старая копия в PATH отвергает --integration. В-третьих, необязательное git-расширение может создать нумерованные ветки, но сам git checkout не переключает активную функцию. Все три случая случаются до первой строки продуктового кода.

Как Spec Kit делит работу на слои

Не считайте девять slash-навыков одним плоским списком. Они ложатся на три вида артефактов, и законны только два пути.

Слой принципов — один раз на репозиторий. /speckit-constitution записывает жёсткие ограничения качества, тестов, прав и опыта. Дальнейшие шаги меряют по этому файлу. Слой функции — один раз на функцию. /speckit-specify отвечает только на то, что человек может наблюдать, и зачем это нужно. /speckit-clarify спрашивает о неясном и записывает ответы обратно в спецификацию. Слой реализации — первое место, где разрешены фреймворк и каталог. /speckit-plan создаёт план, заметки исследования, модель данных и контракты. /speckit-tasks режет план по зависимостям и помечает параллельную работу [P]. /speckit-implement правит файлы в этом порядке. /speckit-converge сверяет код с артефактами, дописывает недостающие задачи и повторяет, пока не сообщит Converged.

Посередине стоят двое ворот качества. Не путайте их с фразой «код готов». /speckit-checklist строит список качества требований, который остаётся у проверяющего. Галочка значит, что требование ясно, а не что функция реализована. /speckit-analyze только читает. Он сообщает о конфликтах между spec.md, plan.md и tasks.md и не меняет репозиторий. Встроенный checklists/requirements.md ведут specify и clarify. Свои списки остаются у проверяющего. Implement остановится и спросит, если клетки не отмечены. Сам он их не отметит.

Короткий путь подходит маленькому изменению с уже ясной границей: specify, plan, tasks, implement, converge. Полный путь подходит всему, что вы собираетесь выпускать: constitution один раз на проект, затем specify, clarify, plan, checklist, tasks, analyze, implement, converge. Дефект идёт по официальному быстрому старту исправления. Идея, которой вы ещё не обязались, идёт в оценку идеи. Ни то ни другое не является предварительным шагом этого пути.

Установка в Windows, macOS и Linux

Общие условия: Python 3.11 или новее, Git только если включено git-расширение, и тот агент, которым вы действительно пишете код. Для постоянной установки берите uv. Терминал запускает CLI. Slash-навыки работают в чате агента.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

После установки проверьте две вещи. specify version доказывает только, что команда запускается и печатает версию. Он не доказывает, что бинарник пришёл с PyPI, а не с GitHub. specify self check только читает. Он говорит, есть ли более новый релиз, и установку не меняет. Документация показывает теги с начальным v, например v0.12.11. Чтобы закрепить установку из исходников, выполните uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z и не убирайте v. Закрепление PyPI — это uv tool install specify-cli==X.Y.Z. Обновляйте тем же инструментом, что и ставили: uv tool install --force specify-cli, pipx install --force specify-cli или pip install --upgrade specify-cli.

Не инициализируйте репозиторий с уже существующим кодом на грязном рабочем дереве. Сначала сделайте коммит или резервную копию, затем specify init --here --force --non-interactive --integration claude. --force значит только, что вы согласны на слияние шаблонов в существующие файлы. CI без клавиатуры нужен флаг --non-interactive, иначе init остановится на меню со стрелками. Если бинарник агента лежит на другой машине, добавьте --ignore-agent-tools, чтобы пропустить локальную проверку. Неинтерактивный init по умолчанию берёт Copilot, пока вы не передадите другой --integration.

Не угадывайте ключ интеграции. У Cursor это cursor-agent, а не cursor. Другие частые ключи: claude, copilot, gemini, pi, omp, codebuddy. Интерактивный терминал спросит, если опустить --integration. Скрипт или канал обязаны передать ключ явно.

Если specify version показывает старый номер, сначала посмотрите путь через which specify. Оставшийся бинарник 0.1 превращает --integration в No such option: --integration, а старый --ai отвечает No matching release asset found. Это не сбой сети. Начало PATH указывает на другую установку. Удаляйте только ту копию, которой не пользуетесь, и обновляйте исходным инструментом с --force или --upgrade. Если чередовать оба инструмента, снова останутся два бинарника.

Девять команд: где вызываются, что могут менять, для кого

Две следующие таблицы используют один набор столбцов. Настоящая разница — точка входа и граница исполнения, а не имя модели.

Короткий или полный путь выбирают по ситуации

Сквозной пример — доска заметок, которая остаётся на одной машине. Ничего не загружается наружу. В первой фазе нет пароля. Три заранее заданных участника. Четыре колонки проекта: Сделать, В работе, Нужно подтверждение, Готово. Карточка меняет колонку перетаскиванием. Комментарий может править только его автор. Specify фиксирует это поведение и причину. В плане впервые пишут «локальный SQLite, без удалённого API». Если база уже стоит в specify, первая техническая догадка становится требованием, которое больше нельзя оспорить.

Текст specify, который вставляют в чат, останавливается на этой крупности. Три фиксированных человека открывают проект и перетаскивают карточки между четырьмя колонками. Править и удалять комментарий может только автор. При запуске пароль не спрашивают. Место хранения файлов, фреймворк и имя таблицы туда не входят. Как только они там появляются, спецификация обгоняет план. В плане вы фиксируете: хранение в локальном SQLite, одна страница, без выхода в сеть.

Согласовать агента, тип скрипта и изолированную машину

Если вы уже пишете этот репозиторий в Cursor, берите cursor-agent и тип скрипта машины: ps в Windows, sh в macOS и Linux. После init вызывайте в чате по одному навыку, по короткому или полному пути. Прочитайте артефакт до следующего навыка. Не вставляйте все девять команд в один промпт.

Если вы в основном пользуетесь Claude Code, ключ — claude. Когда описания навыков теснят контекст, инициализируйте с --integration-options="--no-model-invocation", чтобы основные команды шли только когда вы набираете /speckit-specify. Пользователи Copilot оставляют раскладку skills по умолчанию. --commands добавляйте только если вам нужны старые файлы агента.

Implement меняет файлы и запускает команды. Не делайте первый проход на ноутбуке с боевыми ключами. Положите репозиторий на удалённый Mac, прочитайте diff и только потом возвращайте его. Как заказать узел — на странице аренды Mac mini. Бюджет — на странице цен. Если в спецификации есть сборка macOS или подпись, эту фазу гоняйте на настоящем узле Mac и отделяйте от повседневного ноутбука через автоматизацию OpenClaw. Если установка не удалась, проверьте соединение и требования в справочном центре, прежде чем винить Spec Kit.

Пять ошибок, из-за которых остальную работу придётся переделать

1. Писать фреймворк и базу уже в specify. Стек принадлежит плану. Как только спецификация говорит «обязательно эта библиотека», clarify и analyze тратят время на защиту этого выбора.
2. Набирать /speckit-specify в терминале. Slash-навыки есть только в чате агента. Терминал запускает сам specify.
3. Вставлять точечную команду из документации в Cursor. Навык Cursor — это /speckit-specify. Форма с точкой — справочная запись.
4. Ставить и через uv, и через pipx. Старый бинарник 0.1.x отвечает No such option: --integration или No matching release asset found на --ai. Сначала выполните which specify, потом решайте, какую копию удалить.
5. Использовать git checkout как переключатель функции. Меняйте .specify/feature.json или задайте SPECIFY_FEATURE_DIRECTORY. Одна смена ветки оставляет команды нацеленными на прошлый каталог функции.

Семь шагов

1. Поставьте uv и specify-cli. Выполните specify version и specify self check. Убедитесь, что PATH находит ровно один бинарник.
2. Выберите --script по операционной системе и --integration по агенту, которым реально пользуетесь, затем выполните specify init. В существующем репозитории сначала сделайте коммит и добавьте --here --force.
3. Один раз выполните /speckit-constitution в чате. Только принципы: проверять ввод, комментарий правит только автор, первая фаза ничего не отправляет наружу.
4. Опишите поведение и причину доски заметок через /speckit-specify. Если будете выпускать, следом /speckit-clarify и закройте вопросы про перетаскивание, права и пустой проект.
5. Только когда спецификация устойчива, выполните /speckit-plan. Затем checklist, tasks и analyze. Если analyze сообщает о конфликте, правьте исходный артефакт. Не латайте его внутри implement.
6. Запустите /speckit-implement на изолированном Mac или в чистом каталоге. Если список длинный, идите по фазам. Не проглатывайте весь tasks.md за один проход.
7. Запускайте /speckit-converge, пока не будет Converged. Затем читайте diff: файлы вне спецификации и любой секрет, записанный в репозиторий.

Вопросы, которые решают установку

Чем Spec Kit отличается от чата в Cursor?

Чат остаётся в сессии. Смените человека или машину — и его нет. Spec Kit записывает принципы, спецификацию, план и задачи в Markdown репозитория. Активная функция — каталог из .specify/feature.json, а не память о прошлом треде.

Команда называется /speckit-specify или /speckit.specify?

Cursor, Claude Code и режим skills по умолчанию в GitHub Copilot используют форму с дефисом, в чате агента, не в терминале. Режим skills в Codex использует $speckit-specify. Форма с точкой в документации — справочная запись. Не вставляйте её в Cursor.

Нужен ли Windows сначала WSL?

Нет. В 2026 году Spec Kit на Windows по умолчанию берёт PowerShell. При init передайте --script ps. macOS и Linux по умолчанию берут bash, это --script sh.

Можно поставить и через uv, и через pipx?

Нет. Останутся два бинарника specify. Старая копия в начале PATH отвергнет --integration или напишет No matching release asset found. Обновляйте исходным инструментом, с --force или --upgrade.

Переключает ли git checkout активную функцию?

Нет. Активная функция задаётся .specify/feature.json. Её можно перекрыть через SPECIFY_FEATURE_DIRECTORY. Необязательное git-расширение создаёт нумерованные ветки, но один checkout это состояние не обновляет.

Сначала поставить верную команду, потом пускать агента в репозиторий

Ценность Spec Kit не в том, что появилась ещё одна slash-команда. Ценность в том, что «спецификация, затем план, затем правки файлов» становятся файлами репозитория, которые может проверить другой человек. Windows использует PowerShell. macOS и Linux используют bash. Cursor использует cursor-agent и навыки с дефисом. Маленькое изменение идёт коротким путём. Функция, которую вы выпускаете, идёт полным путём. Implement работает на изолированном узле. Следующий шаг — не новая коллекция промптов. Выполните specify version и убедитесь, что бинарник перед вами — тот, который вы только что поставили. Если номер не тот, исправьте PATH до того, как наберёте навык.

Дальше по теме

• Полное руководство по спецификационно-ориентированной разработке →
• Agent Skills: что ставить и куда →
• Автоматизация OpenClaw на удалённом Mac →