Урок 16.10. Интеграции с coding-агентами

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

Интеграция - интерфейс между CLI specify (урок 16.9) и вашим coding-агентом: именно она определяет, куда лягут файлы команд, как будут выглядеть слэш-команды и можно ли держать в проекте нескольких агентов одновременно. Spec Kit поддерживает 38+ агентов - от Copilot и Claude Code до Zed и Docker Agent - и переключение одной командой, без lock-in.

Этот урок - справочник: каталог агентов, синтаксис вызова, команды управления интеграциями (install/switch/use/upgrade/status), управление каталогами обнаружения и правила мульти-установки. Дата среза каталога: 2026-10-03.

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

specify init --integration <key> разворачивает для выбранного агента подходящие файлы команд и структуру каталогов. Дальше процесс не зависит от инструмента: шаги везде одни, меняется написание вызова. Активен один дефолтный агент; дополнительные интеграции ставятся рядом (с ограничениями), расширения и пресеты регистрируются только для дефолтной.

Каталог агентов

Каталог на дату среза (ключ - для --integration; полный актуальный список: specify integration list):

Агент	Ключ	Примечание
Alquimia AI	`alquimia`	skills в `.alquimia/skills`, вызов `/speckit-<command>`
Amp	`amp`	-
Antigravity (agy)	`agy`	skills в `.agents/skills/`; в headless-режиме авто-аппрув тулов - `SPECKIT_AGY_ALLOW_ALL_TOOLS=1`
Auggie CLI	`auggie`	-
Claude Code	`claude`	skills в `.claude/skills`
Cline	`cline`	IDE-based
CodeBuddy CLI	`codebuddy`	-
Codex CLI	`codex`	skills в `.agents/skills/`, вызов `$speckit-<command>`
Command Code	`command-code`	skills в `.commandcode/skills/`, вызов `$speckit-<command>`
Cursor	`cursor-agent`	-
DeepSeek Harness	`dsh`	skills в `.dsh/skills`
Devin for Terminal	`devin`	skills в `.devin/skills`
Docker Agent	`docker-agent`	skills в `.agents/skills/` (общая с Codex/Zed папка - не multi-install safe); конфигурация через `SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS=./agent.yaml`
Factory Droid	`droid`	skills в `.factory/skills/`
Firebender	`firebender`	IDE-based (Android Studio / IntelliJ)
Forge	`forge`	-
Gemini CLI	`gemini`	-
GitHub Copilot	`copilot`	skills по умолчанию (`speckit-<command>/SKILL.md` в `.github/skills/`); `--integration-options="--commands"` дает commands-раскладку (`.github/agents/`, `.github/prompts/`, merge `.vscode/settings.json`)
Goose	`goose`	YAML-рецепты в `.goose/recipes/`
Grok Build	`grok`	skills в `.grok/skills`
Hermes	`hermes`	skills глобально в `~/.hermes/skills/`
IBM Bob	`bob`	skills по умолчанию в `.bob/skills/`; `--legacy-commands` scaffolds устаревшую раскладку Bob 1.x; миграция - `specify integration upgrade bob --integration-options="--skills"`
Junie	`junie`	-
Kilo Code	`kilocode`	команды в `.kilo/commands`; legacy `.kilocode/workflows` - fallback регистрации
Kimi Code	`kimi`	skills в `.kimi-code/skills/`; `--migrate-legacy` переносит старые `.kimi/skills/`
Kiro CLI	`kiro-cli`	не подставляет `$ARGUMENTS` в file-based prompts - Spec Kit шлет prose-fallback (алиас `--integration kiro`)
Lingma	`lingma`	skills ставятся автоматически
MiniMax Code	`mcode`	skills в `.minimax/skills`; headless dispatch через `--permission full`; строгий режим - `SPECKIT_INTEGRATION_MCODE_EXTRA_ARGS="--permission smart"`
Mistral Vibe	`vibe`	-
Muse Code	`muse`	skills в `.agents/skills`
Oh My Pi	`omp`	слэш-команды в `.omp/commands`
opencode	`opencode`	-
Pi Coding Agent	`pi`	без MCP из коробки - `taskstoissues` не заработает; MCP добавляется расширениями Pi
Qoder CLI	`qodercli`	-
Qwen Code	`qwen`	-
RovoDev	`rovodev`	`.rovodev/skills/`, промпт-обертки, `prompts.yml`; dispatch через `acli rovodev`
SHAI (OVHcloud)	`shai`	шаги workflow `command`/`prompt` не работают: CLI отдает промпт auto-fix агенту и не грузит `.shai/commands`
Tabnine CLI	`tabnine`	-
Trae	`trae`	skills ставятся автоматически
ZCode	`zcode`	skills в `.zcode/skills/`, вызов `$speckit-<command>`
Zed	`zed`	skills в `.agents/skills`, вызов `/speckit-<command>`
Generic	`generic`	свой агент: `--integration generic --integration-options="--commands-dir <path>"`; `--skills` - раскладка `speckit-<name>/SKILL.md`

Вызов команд

Шаги процесса Spec Kit вызываются в чате агента, не в терминале; терминальны только установка и настройка CLI. Шаги одинаковы для всех интеграций - написание зависит от агента и режима:

Интеграция / режим	Пример SDD	Пример расширения
GitHub Copilot, skills-режим по умолчанию	`/speckit-specify`	`/speckit-bug-assess`
Dotted-нотация справочников	`/speckit.specify`	`/speckit.bug.assess`
Codex, Command Code, ZCode (skills)	`$speckit-specify`	`$speckit-bug-assess`
Kimi (skills)	`/skill:speckit-specify`	`/skill:speckit-bug-assess`

Skills Copilot по умолчанию ставятся в .github/skills/; commands-раскладка включается --integration-options="--commands" (в ней Copilot CLI выбирает агента через /agents или адресует его прямо в промпте).

Команды управления интеграциями

Все команды требуют проект, инициализированный specify init; для старта нового проекта с агентом используйте specify init <project> --integration <key>.

Список и поиск

bash
specify integration list          # встроенные, установленная, дефолт, CLI/IDE-тип, multi-install safety
specify integration list --catalog  # плюс каталог (встроенный и community)
specify integration search [query]  # поиск по активному стеку каталогов (внутри проекта)
specify integration search --tag <t> --author <a>
specify integration info <integration_id>  # описание, автор, лицензия, теги, источник, активность

Установка

bash
specify integration install <key>

Опция	Описание
`--script sh\|ps\|py`	тип скриптов
`--force`	согласие на установку рядом с интеграциями, не объявленными multi-install safe
`--integration-options`	опции интеграции (например, `--commands-dir`)

Если интеграция уже стоит, команда продолжается автоматически только при multi-install safety всех участников; иначе - switch для замены дефолта или --force для явного согласия. Сбой на полпути откатывается в чистое состояние. Установка дополнительной интеграции дефолт не меняет; расширения и пресеты регистрируются только для активной (дефолтной) интеграции - use/switch пересобирают их для новой активной.

Контроль версий: управляемый multi-install появился в Spec Kit 0.8.5. Если install сообщает «другая интеграция уже установлена» и предлагает только switch/uninstall - проверьте specify version и обновитесь. Разовые uvx --from git+...-команды обновляют лишь временную копию, не постоянный specify в PATH.

Удаление и переключение

bash
specify integration uninstall [<key>]   # --force: удалить даже измененные файлы
specify integration switch <key>        # --script, --force, --refresh-shared-infra, --integration-options
specify integration use <key>           # --force

Uninstall: Spec Kit трекает каждый созданный файл с SHA-256 хэшем оригинала; неизмененные удаляются автоматически, измененные (ваши ручные правки) сохраняются - --force удаляет все.

Switch: если цель еще не установлена - эквивалент uninstall + install одним шагом (--force управляет удалением измененных файлов убираемой интеграции); если установлена - только меняет дефолт, как use (--force - перезапись managed-шаблонов при смене дефолта). --integration-options для уже установленной цели отклоняется: смена опций требует переустановки managed-файлов - сначала upgrade <key> --integration-options ..., затем use <key>.

Use: ставит дефолт, не удаляя другие установленные; обновляет managed-шаблоны под стиль вызова нового дефолта (измененные и untracked сохраняются, кроме --force). Это и точка активации расширений/пресетов: каждый включенный re-register-ится для новой активной интеграции.

Обновление и статус

bash
specify integration upgrade [<key>]     # --force, --script, --integration-options
specify integration status [--json]

Upgrade переустанавливает интеграцию с обновленными шаблонами и командами (например, после апгрейда Spec Kit); дефолт - текущая дефолтная, с ключом - любая установленная. Локально измененные файлы блокируют апгрейд до --force; устаревшие файлы предыдущей установки удаляются автоматически. Расширения и пресеты re-register-ятся только при апгрейде активной интеграции. Если апгрейд меняет раскладку commands <-> skills при зарегистрированных пресетных артефактах - отказ до изменения файлов: снимите пресеты, апгрейдните, верните.

Status (без изменения файлов): дефолт, установленные, multi-install safety, отсутствующие/измененные managed-файлы, невалидные пути манифестов, здоровье общей инфраструктуры. JSON-форма - для CI и агентов; exit 0 при статусе ok/warning, 1 - только при error.

Управление каталогами

Каталоги определяют, где search и info ищут интеграции; проверяются в порядке приоритета:

bash
specify integration catalog list        # активные источники
specify integration catalog add <url>   # --name <name>; URL обязан быть HTTPS
                                        # (кроме localhost/127.0.0.1/[::1] для локальных тестов)
specify integration catalog remove <index>  # по 0-based индексу из catalog list

Порядок резолюции (первый матч выигрывает): переменная SPECKIT_INTEGRATION_CATALOG_URL -> конфиг проекта .specify/integration-catalogs.yml -> пользовательский ~/.specify/integration-catalogs.yml -> встроенные дефолты (официальный + community-каталог). Повторное добавление того же URL с тем же именем - no-op; с другим именем - отказ.

Специфичные опции интеграций

Интеграция	Опция	Описание
`generic`	`--commands-dir`	обязательна: каталог для файлов команд
`generic`	`--skills`	рендер команд и вызовов расширений как `speckit-<name>/SKILL.md` вместо плоских `speckit.<name>.md`
`kimi`	`--migrate-legacy`	миграция `.kimi/skills/` в `.kimi-code/skills/` (включая переименование `speckit.xxx` -> `speckit-xxx`)
`copilot`	`--commands`	commands-раскладка (`.github/agents/` + `.github/prompts/` + merge `.vscode/settings.json`) вместо skills
`copilot`	`--skills`	принудительно skills-раскладка при явной миграции с commands

bash
specify integration install generic --integration-options="--commands-dir .myagent/cmds"
specify integration install generic --integration-options="--commands-dir .myagent/skills --skills"

Когда generic активна, specify extension add регистрирует команды расширений в настроенном --commands-dir (файлами команд или skills по --skills); specify extension remove убирает неизмененные extension-артефакты, не трогая core-команды, пользовательские файлы и правленые файлы расширений.

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

bash
specify integration scaffold <key>   # --type markdown|skills|toml|yaml

Создает минимальный пакет встроенной интеграции и тестовый каркас в репозитории Spec Kit, печатает следующие шаги. Запускается из корня репозитория; <key> - lowercase kebab-case (например, my-agent).

Мульти-установка

Можно ли поставить несколько интеграций в один проект? Да, но это скорее для командной портируемости, чем дефолтный workflow. Автоматически - только когда все участники объявлены multi-install safe; для прочих комбинаций - --force с осознанием, что несколько агентов могут видеть чужие агент-специфичные инструкции. Spec Kit трекает состояние в .specify/integration.json: default_integration, installed_integrations, integration_settings, integration_state_schema (для будущих миграций); legacy-поле integration - алиас дефолта.

Что такое multi-install safe? Интеграция использует статический уникальный корень агента и каталог команд, стабильные настройки вызова и отдельный манифест установки, чьи managed-файлы не пересекаются с другой safe-интеграцией; инварианты закреплены registry-тестами. Общие шаблоны остаются привязаны к единственному дефолту. Таргетинг контекстных файлов - отдельная забота: расширение agent-context управляет per-agent контекст-файлом (AGENTS.md, CLAUDE.md и др.) и может синхронно вести несколько якорей через context_files; несколько агентов на одном контекст-файле - ожидаемо и на multi-install safety не влияет.

Объявленные safe-интеграции (ключ -> каталог команд): alquimia -> .alquimia/skills, auggie -> .augment/commands, claude -> .claude/skills, cline -> .clinerules/workflows, codebuddy -> .codebuddy/commands, codex -> .agents/skills, command-code -> .commandcode/skills, cursor-agent -> .cursor/skills, droid -> .factory/skills, firebender -> .firebender/commands, gemini -> .gemini/commands, grok -> .grok/skills, junie -> .junie/commands, kilocode -> .kilo/commands, kiro-cli -> .kiro/prompts, lingma -> .lingma/skills, mcode -> .minimax/skills, omp -> .omp/commands, opencode -> .opencode/commands, pi -> .pi/prompts, qodercli -> .qoder/skills, qwen -> .qwen/commands, shai -> .shai/commands, tabnine -> .tabnine/agent/commands, trae -> .trae/skills, zcode -> .zcode/skills.

Интеграции с общим каталогом команд (например, docker-agent делит .agents/skills с Codex/Zed), динамическими путями установки (--commands-dir) или merge общих настроек - safe по умолчанию не объявляются; рядом с другой интеграцией ставятся через --force.

Распространенные вопросы. Ключ агента - из specify integration list. CLI-based интеграции требуют установленного инструмента; IDE-based работают через саму IDE. upgrade - обновить managed-файлы установленной интеграции после апгрейда Spec Kit; switch - сменить дефолт (установленной цели - как use). Измененные файлы при uninstall/switch сохраняются автоматически (удаление по SHA-256-матчу); расширения и пресеты применяются только к активной интеграции - до use/switch они не rescaffold-ятся.

Практика

Выполните specify integration list и найдите своего агента; проверьте по таблице урока его каталог команд и написание вызова.
В тестовом проекте поставьте вторую интеграцию: сначала через switch, затем use обратно. Сравните: что произошло с файлами первой, что изменилось в стиле вызова команд?
Добавьте локальный каталог http://localhost/catalog.json через specify integration catalog add и проверьте порядок резолюции с переменной SPECKIT_INTEGRATION_CATALOG_URL.

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

Интеграции подключают Spec Kit к агенту: init --integration <key> разворачивает файлы команд в каталог агента, шаги процесса одинаковы, написание различается (/speckit-*, $speckit-*, /skill:speckit-*). Управление - install/uninstall/switch/use/upgrade/status с манифестом SHA-256 (измененные файлы сохраняются). Мульти-установка автоматична только для multi-install safe интеграций; расширения и пресеты регистрируются исключительно для дефолтной. Каталоги обнаружения резолвятся: env -> проект -> пользователь -> встроенные.

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

38+ интеграций плюс generic с --commands-dir для любого другого инструмента;
use меняет дефолт и пересобирает расширения/пресеты под новый дефолт; switch на неустановленную цель - uninstall+install одним шагом;
multi-install safety - формальное объявление о непересекающихся путях и манифестах, проверяемое registry-тестами;
измененные пользователем файлы не теряются при uninstall/switch/upgrade без явного --force;
каталоги - управляемый стек с HTTPS-ограничением и приоритетом env-переменной.

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

Как ставится интеграция для агента, которого нет в таблице? Какая опция обязательна?
Чем switch отличается от use, когда целевая интеграция уже установлена? А когда не установлена?
Что происходит с вашими правками файлов интеграции при uninstall и switch? Какой механизм это обеспечивает?
Почему расширения и пресеты не видны не-дефолтной интеграции? Какая команда их активирует для новой дефолтной?
Перечислите порядок резолюции каталогов интеграций. Какое ограничение накладывается на URL каталога?
Что делает интеграцию multi-install safe? Приведите пример интеграции, которая safe не объявлена, и объясните почему.

Что дальше

Соединение с агентом настроено. Урок 16.11 открывает тему перестройки самого процесса: карта строительных блоков Spec Kit и как выбирать между расширениями, пресетами, workflows и бандлами.

Источники

https://github.com/github/spec-kit/blob/main/docs/reference/integrations.md