Урок 16.2. Установка и обновление

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

Урок 16.1 ввел ментальную модель Spec Kit: CLI specify плюс агентные команды /speckit.*. Чтобы работать с остальными уроками модуля, нужно корректно поставить CLI, инициализировать хотя бы один тестовый проект и уметь обновлять и инструмент, и файлы проекта между релизами.

Установка Spec Kit нетривиальна в трех местах: два официальных канала дистрибуции (GitHub-исходник и PyPI) с разными стратегиями пиновки версий; специфичные сценарии enterprise (air-gapped, приватные индексы); и апгрейд, который разделен на два независимых действия - обновление CLI и обновление файлов проекта. Этот урок закрывает все три.

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

Spec Kit распространяется через два официальных канала, оба поддерживаются мейнтейнерами: репозиторий https://github.com/github/spec-kit (установка из исходника) и пакет specify-cli на PyPI. Обычной установке подходят оба маршрута. Проверка после установки:

specify version

Команда подтверждает, что specify доступен и сообщает версию, но не доказывает, откуда исполняемый файл - из PyPI или GitHub. Для offline- и air-gapped-сред валидны также локально собранные wheel-пакеты из репозитория.

Требования

Компонент	Примечание
ОС	Linux, macOS; Windows поддерживается напрямую (PowerShell-скрипты работают без WSL)
AI-агент	Claude Code, GitHub Copilot, CodeBuddy CLI, Gemini CLI, Pi Coding Agent, Oh My Pi и другие (38 интеграций, урок 16.10)
Менеджер пакетов	uv (рекомендуется) или pipx для постоянной установки
Python	3.11+
Git	опционально - нужен только при включенном git-расширении

Маршрут 1: установка из исходника (GitHub, рекомендуется)

Постоянная установка «один раз и везде». Пинуйте release-тег из Releases - с ведущей v: например, v0.12.11, а не 0.12.11:

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

Требуется uv. Если command not found: uv - сначала установите uv (раздел ниже).

Затем инициализируйте проект:

bash
specify init <PROJECT_NAME> --integration copilot

Установка uv

uv - быстрый Python-менеджер пакетов от Astral. Spec Kit использует его (через uvx или uv tool install), чтобы запускать CLI, не засоряя глобальное окружение Python.

bash
# macOS / Linux - официальный скрипт
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows - Command Prompt или PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# альтернативы
brew install uv            # macOS, Homebrew
winget install --id=astral-sh.uv -e   # Windows, WinGet
scoop install uv           # Windows, Scoop

После установки следуйте инструкциям установщика о добавлении uv в PATH и откройте новый терминал. Проверка:

uv --version

Маршрут 2: установка из PyPI

Пакет specify-cli опубликован на PyPI; версия на PyPI отслеживает GitHub-теги (PyPI 0.12.11 соответствует тегу v0.12.11). Используйте привычный Python-инструмент:

bash
# uv (рекомендуется)
uv tool install specify-cli

# или pipx
pipx install specify-cli

# или pip
pip install specify-cli

Пиновка конкретного релиза для воспроизводимых установок:

bash
uv tool install specify-cli==0.12.11

Приватный индекс пакетов

Корпоративные сети, зеркала и прокси могут требовать индекс, отличный от публичного PyPI:

bash
# uv - через переменную окружения
UV_DEFAULT_INDEX=https://your-index.example.com/pypi/simple/ uv tool install specify-cli

# uv - через флаг
uv tool install --default-index https://your-index.example.com/pypi/simple/ specify-cli

# pipx - прокинуть аргумент pip
pipx install specify-cli --index-url https://your-index.example.com/pypi/simple/

# pip
pip install specify-cli --index-url https://your-index.example.com/pypi/simple/

Та же конфигурация индекса применяется к пинованным установкам, апгрейдам и разовому использованию. Если индекс требует аутентификации, используйте переменные окружения, keyring или netrc - не встраивайте секреты в URL командной строки: они утекают через историю шелла, списки процессов и логи.

Как проверить, откуда установлен CLI

specify version - только локальная проверка и источник не различает. Смотрите метаданные пакетного менеджера:

pipx list --json - точная спецификация установки каждого инструмента;
для uv/pip - файл PEP 610 direct_url.json внутри *.dist-info пакета: установка из Git или URL записывает адрес репозитория/архива, обычная установка с PyPI этот файл не создает;
pip show specify-cli печатает только метаданные пакета и не видит окружения, управляемые uv/pipx.

Установка через pipx без uv

pipx ставит Python CLI-приложения в изолированные окружения и uv не требует:

bash
# конкретный стабильный релиз (рекомендуется, vX.Y.Z с ведущей v)
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

# или последний main (может содержать невыпущенные изменения)
pipx install git+https://github.com/github/spec-kit.git

Проверка, апгрейд и удаление:

bash
specify version
pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z
pipx uninstall specify-cli

Разовое использование (uvx)

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

bash
# новый проект (последний main)
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# конкретный релиз
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

# инициализация в текущем каталоге
uvx --from git+https://github.com/github/spec-kit.git specify init . --integration copilot
# или флаг --here
uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration copilot

Когда переходить на постоянную установку: если планируете регулярную работу, инструмент остается в PATH, нет повторной загрузки на каждый вызов, доступны uv tool list, uv tool upgrade, uv tool uninstall.

Enterprise / Air-Gapped установка

Если среда блокирует PyPI и GitHub, соберите переносимый набор wheel-пакетов на подключенной машине и перенесите на изолированную цель.

Шаг 1 - собрать wheel на подключенной машине:

bash
git clone https://github.com/github/spec-kit.git
cd spec-kit

pip install build
python -m build --wheel --outdir dist/

# скачать wheel и все runtime-зависимости
pip download -d dist/ dist/specify_cli-*.whl

Важно: pip download резолвит платформозависимые wheels (например, PyYAML с нативными расширениями). Шаг выполняется на машине с теми же ОС и версией Python, что и целевая. Несколько платформ - повторите для каждой.

Шаг 2 - перенести каталог dist/ (wheel пакета плюс все зависимости) на целевую машину через USB, сетевую шару или одобренный канал.

Шаг 3 - установить без сети:

bash
pip install --no-index --find-links=./dist specify-cli

Шаг 4 - инициализировать проект; сеть не нужна, bundled-ассеты используются по умолчанию:

bash
specify init my-project --integration copilot

Требуется Python 3.11+. Windows-нюанс: офлайн-scaffolding требует PowerShell 7+ (pwsh), а не Windows PowerShell 5.x (powershell.exe).

Отдельное замечание документации - Git Credential Manager на Linux: при проблемах с Git-аутентификацией установите GCM (.deb-пакет с релизной страницы git-credential-manager) и включите git config --global credential.helper manager.

Инициализация проекта: опции

Выбор интеграции

В интерактивном терминале CLI предложит выбрать агента; неинтерактивные сессии (CI, пайплайны) по умолчанию берут GitHub Copilot, если не передан --integration:

bash
specify init <project_name> --integration claude
specify init <project_name> --integration gemini
specify init <project_name> --integration copilot
specify init <project_name> --integration codebuddy
specify init <project_name> --integration pi
specify init <project_name> --integration omp

Тип скриптов: shell, PowerShell или Python

Автоматизационные скрипты ставятся в трех вариантах: Bash (.sh), PowerShell (.ps1) и Python (.py). Автоповедение: Windows - ps, другие ОС - sh; в интерактиве будет запрос, если не передан --script:

bash
specify init <project_name> --script sh
specify init <project_name> --script ps
specify init <project_name> --script py

Скрипты попадают в подкаталог варианта: .specify/scripts/bash/, .specify/scripts/powershell/, .specify/scripts/python/ (вариант py также ставит платформенный shell-fallback).

CI и окружения агентов

В средах без клавиатуры или PTY, не умеющего стрелки, передавайте --non-interactive, чтобы инициализация не ждала пикера:

bash
specify init my-project --non-interactive --ignore-agent-tools

--ignore-agent-tools пропускает проверку исполняемых файлов агента - полезно, когда агент будет работать в другом месте. Для непустого каталога --force подтверждает предупреждение о слиянии (сначала закоммитьте или забэкапьте локальные изменения):

bash
specify init --here --force --non-interactive --integration claude

Проверка: что должно появиться

После установки и инициализации в coding-агенте должны быть доступны команды:

Команда	Назначение
`/speckit.constitution`	создать или обновить принципы проекта
`/speckit.specify`	создать спецификацию
`/speckit.clarify`	выявить и снять неоднозначности
`/speckit.plan`	сгенерировать план реализации
`/speckit.checklist`	сгенерировать чек-листы качества
`/speckit.tasks`	разбить план на задачи
`/speckit.analyze`	проверить кросс-артефактную консистентность
`/speckit.implement`	выполнить задачи реализации
`/speckit.converge`	сверить кодовую базу с артефактами и дописать остаток задач
`/speckit.taskstoissues`	конвертировать задачи в issues (мигрирует в bundled-расширение `github` как `/speckit.github.taskstoissues`; ставится `specify extension add github`)

Интеграция generic также регистрирует команды расширений в настроенном --commands-dir: поставленный github дает /speckit.github.taskstoissues как файл команды или /speckit-github-taskstoissues при включенном --skills.

После инициализации запустите агента в каталоге проекта и выберите точку входа: SDD-quickstart (урок 16.3), багфикс (урок 16.6) или оценка идей (урок 16.7).

Обновление

Апгрейд разделен на две независимые части: CLI-инструмент и файлы проекта. Краткая карта:

Что обновляем	Команда	Когда применять
CLI (рекомендуется)	`specify self upgrade`	последний стабильный релиз, in place; автоопределение uv tool / pipx
CLI - пин версии	`specify self upgrade --tag vX.Y.Z[suffix]`	конкретный release-тег вместо последнего стабильного
CLI - ручной fallback (uv)	`uv tool install specify-cli --force --from git+...@vX.Y.Z`	старые установки или явный контроль
CLI - ручной fallback (pipx)	`pipx install --force git+...@vX.Y.Z`	то же для pipx
Файлы проекта	`specify integration upgrade <key>`, затем `specify extension update`	обновить файлы интеграции и расширения в проекте
Все вместе	сначала CLI, затем проект	рекомендуется при мажорных обновлениях

Часть 1: обновление CLI

Две self-management-команды закрывают типовой случай:

bash
# проверить наличие нового релиза (read-only)
specify self check

# предпросмотр без фактического апгрейда
specify self upgrade --dry-run

# апгрейд in place до последнего стабильного
specify self upgrade

# или пин конкретного тега
specify self upgrade --tag vX.Y.Z[suffix]

Голый specify self upgrade выполняется сразу - поведение в духе pip install -U. CLI классифицирует окружение: uv tool, pipx, uvx (ephemeral), source checkout или unsupported. Автоматически обновляются только uv tool и pipx; для uv tool под капотом выполняется uv tool install specify-cli --force --from <git ref>, так что пинованные теги работают. Остальные пути печатают руководство и выходят с кодом 0, ничего не трогая.

Пинованные теги обязаны начинаться с vMAJOR.MINOR.PATCH; суффиксы ограничены dev/alpha/beta/rc и build-метаданными (v1.0.0-rc1, v0.8.0.dev0, v1.0.0-rc1+build.42). Имена веток, hash-ссылки, latest и версии без v отклоняются.

Таймаут субпроцесса установщика задается SPECIFY_UPGRADE_TIMEOUT_SECS (по умолчанию без лимита). Если таймаут сработал, команда выйдет с кодом 124; такой же код возможен от самого установщика - скриптам следует считать 124 неоднозначным и разбирать сообщение.

Если установленная CLI старше релиза, вводившего specify self upgrade, используйте ручные эквиваленты:

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

# pipx
pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z

Для разовых uvx-команд просто указывайте нужный тег в --from; помните: uvx не обновляет постоянный specify.

Нюанс PyPI-маршрута: specify self upgrade сейчас пересобирает установки uv tool и pipx из GitHub-URL, а не сохраняет PyPI-базу. Чтобы остаться на PyPI, обновляйтесь пакетным менеджером: uv tool install --force specify-cli, pipx install --force specify-cli или pip install --upgrade specify-cli. Учтите: uv tool upgrade сохраняет пиновку - чтобы снять пин и получить свежий релиз, используйте непинованную команду установки.

Проверка после апгрейда:

bash
specify check       # окружение инструментов
specify self check  # версия против последнего GitHub-релиза

Часть 2: обновление файлов проекта

Новые релизы приносят новые слэш-команды, шаблоны и изменения расширений - файлы Spec Kit в проекте нужно обновить.

Manifest-aware путь (основной). Сначала проверьте установленные интеграции:

specify integration status

Отчет покажет дефолтную интеграцию, все установленные и модифицированные/отсутствующие managed-файлы (можно смотреть .specify/integration.json, ключ installed_integrations). Затем обновите каждую интеграцию и расширения:

bash
specify integration upgrade claude
specify integration upgrade codex
specify extension update   # все расширения; или specify extension update <id> - одно

Что обновляется: файлы команд/скиллов интеграции (.claude/skills/, .github/prompts/, .agents/skills/ и др.); managed-скрипты и шаблоны (.specify/scripts/, .specify/templates/) - если они не менялись относительно предыдущей managed-копии; установленные расширения - при specify extension update. Команда использует манифест установки: если managed-файл правился локально, она остановится и попросит разобрать diff или перезапустить с --force.

Что никогда не трогается этим путем:

ваши спецификации (specs/001-my-feature/spec.md и весь каталог specs/) - каталог полностью исключен из template-пакетов;
планы и задачи (plan.md, tasks.md);
конституция (.specify/memory/constitution.md) при specify integration upgrade;
исходный код и git-история.

Fallback: повторный specify init --here --force --integration <agent> - запасной путь для проектов старше манифестов или требующих широкого восстановления. Он обновляет выбранную интеграцию и общее scaffolding, но не делает per-integration проверок перед перезаписью. Коммитите или бэкапите кастомизации до его использования.

Изменение поведения: `/constitution` больше не копируется в шаблоны

Команда /constitution теперь ограничена собственным артефактом: она обновляет .specify/memory/constitution.md и пишет Sync Impact Report, но не редактирует plan-template.md, spec-template.md, tasks-template.md, файлы команд и guidance-документы.

Причина - runtime resolution: команды plan, tasks и analyze читают конституцию живьем при каждом запуске, а analyze является выделенным дрейф-чекером. Управляемые шаблоны несут указатель, а не копию: plan-template.md содержит плейсхолдер [Gates determined based on constitution file], который /plan заполняет из живой конституции. Прежняя пропагация дублировала единый источник правды и конфликтовала с системой композиции пресетов/оверрайдов (пресет replace затеняет отредактированный core-шаблон). Политика общих ассетов теперь управляется пресетами и расширениями, а не правкой файлов на месте.

Это не breaking change: даже если старый запуск /constitution вписал конкретный текст ворот в plan-template.md, живая конституция остается источником правды в рантайме; при нефорсированном апгрейде такой шаблон сохраняется как кастомизация. Опциональный возврат к указателю - сбросить секцию в шаблоне до плейсхолдера. Если команда хочет сохранить старое поведение (материализованные шаблоны как reviewed-артефакты), ставится bundled-пресет constitution-sync:

bash
specify preset add constitution-sync

Сценарии и частые проблемы

Сценарий «просто хочу новые слэш-команды»:

bash
specify self upgrade
specify integration status
specify integration upgrade <key>
specify extension update

Сценарий «кастомизировал шаблоны и конституцию»: закоммитьте/забэкапьте, апгрейдните CLI, пройдите manifest-aware путь, разберите diff перед --force.

«Дубликаты слэш-команд в IDE» (Kilo Code, Cline): после апгрейда могут висеть старые и новые версии - удалите старые файлы команд из папки агента вручную и перезапустите IDE.

«Команды не появились после апгрейда»: полностью перезапустите IDE/редактор (не reload window); проверьте наличие файлов (.claude/skills/, .gemini/commands/, .cursor/skills/, .pi/prompts/, .omp/commands/); для Codex требуется переменная CODEX_HOME; некоторым агентам нужен рестарт workspace или сброс кэша.

«Предупреждение о непустом каталоге» при specify init --here: означает, что шаблонные файлы будут слиты с существующими и часть перезаписана. Перезаписывается только инфраструктура Spec Kit (команды агентов, .specify/scripts/, .specify/templates/, создание отсутствующей конституции); specs/, исходники и .git/ не трогаются. Подтверждение y/n или флаг --force.

«Нужно ли запускать specify каждый раз?» Нет: specify init выполняется один раз на проект (далее - апгрейды и диагностика). Слэш-команды постоянно лежат в папке агента проекта; агент читает их напрямую.

Проекты без Git: git-расширение теперь opt-in и не ставится при апгрейде. Если Git не используется, задайте SPECIFY_FEATURE_DIRECTORY (путь к каталогу фичи) перед planning-командами или запустите /speckit.specify, который создаст .specify/feature.json автоматически.

bash
# Bash/Zsh
export SPECIFY_FEATURE_DIRECTORY="specs/001-my-feature"

# PowerShell
$env:SPECIFY_FEATURE_DIRECTORY = "specs/001-my-feature"

Совместимость версий: Spec Kit следует семверу для мажорных релизов; CLI и файлы проекта совместимы внутри одного мажора. Лучшая практика - апгрейдить обе части вместе при смене мажора.

Практика

Установите Spec Kit рекомендуемым способом с пином последнего стабильного тега и проверьте specify version и specify check.
Инициализируйте тестовый проект с вашей интеграцией: specify init demo --integration <agent>. Найдите в проекте каталоги .specify/scripts/, .specify/templates/ и папку команд вашего агента; сверьте список команд /speckit.* с таблицей этого урока.
Выполните specify self check - убедитесь, что команда read-only и ничего не меняет. Сделайте specify self upgrade --dry-run и разберите, какой путь установки определила CLI.

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

Установка Spec Kit - это выбор канала (GitHub-исходник с пином тега или PyPI-пакет specify-cli), менеджера (uv, pipx, pip) и опций specify init: интеграция, тип скриптов, интерактивность. Enterprise-среды обслуживаются wheel-бандлами без сети и приватными индексами. Апгрейд двухчастен: specify self upgrade для CLI и manifest-aware specify integration upgrade <key> + specify extension update для файлов проекта; спецификации и конституция при этом не трогаются.

Главное из урока:

два официальных канала: git+https://github.com/github/spec-kit.git@vX.Y.Z (тег с ведущей v) и PyPI specify-cli;
specify version проверяет доступность, но не источник установки; источник смотрится в метаданных менеджера (pipx list --json, PEP 610 direct_url.json);
air-gapped: wheel плюс зависимости собираются на совместимой машине, ставятся pip install --no-index --find-links;
после specify init слэш-команды живут в проекте постоянно, повторный запуск specify не нужен;
конституция и specs/ неприкосновенны для апгрейдов; кастомизированные managed-файлы блокируют апгрейд до разбора diff или --force.

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

Какие два официальных канала дистрибуции Spec Kit существуют и чем отличается пиновка версии в каждом?
Почему specify version не distinguishes источник установки? Как узнать источник фактически?
Что делает флаг --ignore-agent-tools и в каких окружениях он нужен?
Из каких двух независимых частей состоит обновление Spec Kit? Какими командами выполняется каждая?
Какие файлы проекта никогда не изменяются при manifest-aware апгрейде? Почему каталог specs/ в этом списке?
Куда теперь копируется результат /constitution и почему пропагация в шаблоны была убрана?

Что дальше

Инструмент установлен. Урок 16.3 проводит полный цикл Spec-Driven Development на сквозном примере - от конституции и /speckit.specify до /speckit.converge - и показывает, какие артефакты появляются на каждом шаге.