Урок 16.20. Разработка и вклад в Spec Kit

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

Иногда недостатка документации нет - нужна правка в самом инструменте: новая интеграция для внутреннего агента, фикс бага CLI, изменение шаблона ядра. Гайд локальной разработки показывает, как итерировать по specify CLI без публикации релиза и без коммита в main.

Параллельно урок закрывает модуль: сопоставляет Spec Kit с OpenSpec (модуль 15), возвращает к capstone-материалу курса и фиксирует, куда смотреть дальше.

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

Быстрейший цикл обратной связи - запуск CLI напрямую как модуля (python -m src.specify_cli), без установки. Для симуляции пользовательских потоков - editable-установка в изолированное окружение uv или uvx --from на локальный путь/ветку. Проект использует собственные процессы для существенных изменений (урок 16.4); мелкие фиксы идут обычным issue/PR-путем.

Клонирование и ветки

git clone https://github.com/github/spec-kit.git
cd spec-kit
git checkout -b your-feature-branch

Скрипты проекта - в вариантах Bash (.sh), PowerShell (.ps1) и Python (.py): интерактивный specify init предложит выбор, неинтерактивные запуски возьмут дефолт по ОС; явно - --script sh|ps|py.

О том, как проект применяет к себе SDD и оценку - раздел «Does Spec Kit use Spec Kit?» гайда контрибуторов (CONTRIBUTING.md); подробный разбор - урок 16.4.

Запуск CLI напрямую (быстрейший фидбек)

Исполнение через entrypoint модуля без установки чего-либо:

# из корня репо
python -m src.specify_cli --help
python -m src.specify_cli init demo-project --integration claude --ignore-agent-tools --script sh

Предпочитаете стиль «запуск файла» (с shebang):

python src/specify_cli/__init__.py init demo-project --script ps

Editable-установка в изолированном окружении

Окружение uv, чтобы зависимости резолвились ровно как у конечных пользователей:

# создать и активировать venv (uv управляет .venv сам)
uv venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1

# установить проект в editable-режиме
uv pip install -e .

# entrypoint 'specify' доступен
specify --help

Правки кода не требуют переустановки - режим editable.

uvx напрямую из Git (текущая ветка)

uvx умеет запускать из локального пути (или Git-ссылки), симулируя пользовательские потоки:

uvx --from . specify init demo-uvx --integration copilot --ignore-agent-tools --script sh

Можно нацеливаться на ветку без мержа - запушьте рабочую ветку и:

git push origin your-feature-branch
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps

Абсолютный путь uvx (из любого каталога)

Из другого каталога используйте абсолютный путь вместо .:

uvx --from /mnt/c/GitHub/spec-kit specify --help
uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --integration copilot --ignore-agent-tools --script sh

Удобно - переменная окружения или shell-функция:

export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
uvx --from "$SPEC_KIT_SRC" specify init demo-env --integration copilot --ignore-agent-tools --script ps

specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
specify-dev --help

Тестирование логики прав на скрипты

После init проверьте на POSIX, что shell-скрипты исполняемы:

ls -l scripts | grep .sh
# ожидается бит исполнения владельца (например, -rwxr-xr-x)

На Windows вместо этого используются .ps1-скрипты (chmod не нужен).

Scaffold встроенной интеграции

Команда scaffold создает начальный Python-пакет и тестовый каркас новой встроенной интеграции:

specify integration scaffold my-agent --type markdown
specify integration scaffold my-agent --type toml
specify integration scaffold my-agent --type yaml
specify integration scaffold my-agent --type skills

Ключи с дефисами конвертируются в Python-безопасные имена пакетов: my-agent создаст src/specify_cli/integrations/my_agent/ и tests/integrations/test_integration_my_agent.py. Автоматической регистрации не происходит: отревьюйте метаданные и добавьте импорт и вызов _register() в src/specify_cli/integrations/__init__.py.

Lint и базовые проверки

CI требует ruff check src tests (см. .github/workflows/test.yml) - прогоняйте локально до push:

uvx ruff check src tests

Быстрая проверка импортируемости:

python -c "import specify_cli; print('Import OK')"

Сборка wheel локально (опционально)

Валидация упаковки до публикации:

uv build
ls dist/

Артефакт можно поставить в свежее одноразовое окружение.

Временный workspace и сетевые проблемы

При тестировании init --here в «грязном» каталоге создавайте временный workspace:

mkdir /tmp/spec-test && cd /tmp/spec-test
python -m src.specify_cli init --here --integration claude --ignore-agent-tools --script sh

TLS-проблемы (корпоративные сети): флаг --skip-tls deprecated и не делает ничего; настраивайте хранилище сертификатов или прокси окружения - например, SSL_CERT_FILE или HTTPS_PROXY/HTTP_PROXY.

Сводка цикла правки

Очистка и частые проблемы

rm -rf .venv dist build *.egg-info

Следующие шаги контрибьютора

1. Обновите документацию и пройдите Quick Start с модифицированным CLI.
2. Откройте PR, когда удовлетворены результатом.
3. (Опционально) tag релиза, когда изменения попали в main.

Напомним из урока 16.4: существенные изменения приветствуются протестированными через SDD; agent-помощь раскрывается в PR (инструмент, модель, настройки, степень); каталог-сабмишены проходят валидацию и ревью мейнтейнеров.

Место модуля в курсе

Модуль 16 расширил урок 2.8 в полный разбор Spec Kit. Сопоставление с модулем 15 (OpenSpec) по ключевым осям:

В capstone-потоке (модуль 14) Spec Kit фигурировал как вариант SDD-workflow; теперь вы знаете его достаточно, чтобы осознанно выбирать между ним, OpenSpec и ручной дисциплиной spec/design/tasks - или собрать свое из пяти примитивов.

Практика

1. Склонируйте репозиторий Spec Kit и прогоните python -m src.specify_cli --help без установки; затем editable-установка в uv-окружении и specify version.
2. Скаффолдните тестовую интеграцию my-agent --type skills, изучите сгенерированные пакет и тест-каркас; найдите место регистрации в src/specify_cli/integrations/__init__.py.
3. Модифицируйте любой шаблон ядра в локальном чекауте и проверьте эффект через uvx --from . specify init во временном workspace.

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

Локальная разработка Spec Kit - это лестница циклов обратной связи: прямой запуск модуля (мгновенно), editable-установка (пользовательские зависимости), uvx из пути или ветки (симуляция установки). Scaffolding интеграций, ruff-проверки до push, локальная сборка wheel и временные workspace закрывают остальное. Вклад в проект подчиняется правилам agentic SDLC из урока 16.4: существенное - через SDD, agent-помощь - с раскрытием.

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

• правки не требуют установки - python -m src.specify_cli;
• editable-режим переживает правки без переустановки;
• scaffold не регистрирует интеграцию сам - импорт и _register() добавляются вручную;
• --skip-tls deprecated: настраивайте сертификаты/прокси окружения;
• существенные изменения проекта принято тестировать через собственный SDD-процесс.

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

1. Перечислите три способа запустить локально измененный CLI - от быстрейшего к наиболее близкому к пользовательской установке. Когда каждый уместен?
2. Чем editable-установка отличается от uvx-запуска из пути? Что она дает для отслеживания правок?
3. Что делает specify integration scaffold и чего он не делает? Какие шаги регистрации остаются за вами?
4. Какие проверки обязан прогнать контрибьютор до push? Где закреплено требование?
5. Как оформить «свой агент» для тестирования без добавления интеграции в upstream?
6. Назовите три правила контрибуции из agentic SDLC проекта, применимые к вашему PR.

Что дальше

Модуль 16 завершен. Вы прошли путь от философии SDD и установки до пяти примитивов кастомизации, контрактов и экосистемы. Если вы выполняли практики уроков - у вас уже есть проект с конституцией, спецификацией и пройденным converge-циклом; возвращайтесь к capstone-модулю 14 и примените Spec Kit к собственному продукту, а при выборе инструментов сверьтесь с картой SDD-рынка урока 2.6.

Источники

• https://github.com/github/spec-kit/blob/main/docs/local-development.md