Урок 16.13. Пресеты

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

Пресеты - способ изменить то, как работает Spec Kit: переопределить шаблоны, команды и терминологию, не меняя тулинг. Организационные стандарты, адаптация под методологию (Agile, Kanban, DDD), локализация - все это пресеты; их 33 в каталоге сообщества на срез 2026-10-03.

Справочник пресетов - центральный для всего блока кастомизации: здесь описан стек резолюции файлов - механизм, по которому Spec Kit решает, какой файл шаблона/команды/скрипта использовать при наложении project-local оверрайдов, пресетов, расширений и ядра (урок 16.11 ввел его кратко).

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

Пресеты наслаиваются с приоритетным порядком. Каждый файл (по имени) оценивается независимо: кто первый в стеке - того файл и используется. Стратегии: replace (дефолт), prepend, append, wrap. Пресет ставится из каталога, URL или локальной папки; команды материализуются в каталог активной интеграции и пересчитываются reconciliation-ом при установках и удалениях.

Поиск и установка

bash
specify preset search [query]     # --tag, --author
specify preset add [<preset_id>]

Опция	Описание
`--dev <path>`	установка из локального каталога (разработка)
`--from <url>`	установка из кастомного URL
`--priority <N>`	приоритет резолюции (дефолт 10; меньше = выше)

Команды пресета автоматически регистрируются в поддерживаемых активных интеграциях агента. Интеграция generic сейчас доставляет вызовы расширений, но не регистрирует оверрайды команд и скиллов пресетов. Все команды пресетов требуют проект, инициализированный specify init.

Обновление

bash
specify preset update <preset_id> [--from <url>] [--dev <path>] [--priority <N>]

Заменяет установленный пресет: сначала обычный preset remove, затем обычный preset add; флаги пробрасываются в add (--from и --dev не комбинируются). Без явного источника add резолвит пресет обычным путем (bundled + каталоги).

Update намеренно деструктивен. Аргументы проверяются до removal (--from+--dev совместно - отказ; --priority >= 1; пресет обязан быть установлен), но сам источник замены заранее не инспектируется: если removal прошел, а установка замены упала - прежний пресет уже удален. Команда печатает copy-pastable-повтор specify preset add с источником и приоритетом (на Windows - форматированный для PowerShell). Никаких pre-flight-проверок источника, сравнения версий, diff-ов манифестов, стейджинга, rollback и recovery-транзакций нет; отсутствующий или битый источник может оставить пресет удаленным. С --from/--dev ID пресета в манифесте замены не сверяется с запрошенным до removal - источник с другим ID может поставить другой пресет после удаления запрошенного.

Успешный update следует обычному поведению remove+add: ре-включает пресет, пересоздает installed_at, снимает отслеживаемые пресетом локальные модификации, трактует явный --from/--dev как осознанное изменение источника. Если включена синхронизация конституции - проходят оба обычных reconciliation-прохода; guard сгенерированных файлов по-прежнему защищает рукописный .specify/memory/constitution.md; update-специфичной оптимизации конституции нет.

Удаление, список, информация

bash
specify preset remove <preset_id>   # удалить и вычистить зарегистрированные команды
specify preset list [--json]        # версии, описания, счетчики шаблонов, статус
specify preset info <preset_id>     # шаблоны, метаданные, теги
specify preset resolve <name>       # трассировка стека: какой файл реально используется

--json выводит массив с ключами id, name, description, version, author, priority, enabled, source, provides (commands, templates, scripts); контракт stdout/stderr/exit-кодов как у расширений (урок 16.12). Пресеты печатаются в порядке резолюции: высший приоритет (меньшее число) первым, при равенстве - по алфавиту ID; верхняя запись - та, что выигрывает для пересекающихся файлов.

Enable/disable и приоритеты

bash
specify preset enable <preset_id>
specify preset disable <preset_id>
specify preset set-priority <preset_id> <priority>

Выключенный пресет пропускается при резолюции файлов, но его команды остаются зарегистрированными (см. FAQ ниже). Приоритет: меньше число - выше; при совпадении файлов выигрывает наименьший приоритет.

Каталоги пресетов

Каталоги определяют, где search и add ищут пресеты; проверяются в порядке приоритета. Управление симметрично расширениям:

bash
specify preset catalog list
specify preset catalog add <url>    # --name (обязательно), --priority, --install-allowed|--no-install-allowed, --description
specify preset catalog remove <name>

Предупреждение документации: .specify/preset-catalogs.yml проекта может направить add и search на каталог, который вы не выбирали. Перед установкой пресета в незнакомом проекте выполните specify preset catalog list и инспектируйте все каталоги с install-allowed - конфиг проекта или метка install-allowed не являются доказательством, что пресеты ревьюились. Помечайте install_allowed только каталог, который авторили или провэттили сами; незнакомые и community-каталоги оставляйте discovery-only.

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

yaml
catalogs:
  - name: "my-org-presets"
    url: "https://example.com/preset-catalog.json"
    priority: 5
    install_allowed: true
    description: "Our approved presets"

Резолюция файлов

Пресеты могут давать файлы команд, шаблонов (например, plan-template.md) и скриптов. Каждое имя файла оценивается по стеку приоритетов независимо - разные файлы могут приходить с разных слоев.

Шаблоны и скрипты лукапятся из стека в момент надобности. Команды используют тот же стек для замены и композиции, но материализуются только в каталог активной интеграции - агенты не пересобирают стек и файлы не пишутся во все найденные каталоги агентов. При установке пресета Spec Kit регистрирует его файлы команд против активной интеграции; post-install и post-removal reconciliation пересчитывают и записывают эффективное содержимое затронутых команд по активному стеку. Установка и rescaffold - только активная интеграция; удаление может дополнительно обновить записанные удаляемым пресетом неактивные каталоги, восстанавливая уцелевший слой. Неактивная установленная интеграция получает эти файлы только став дефолтом - specify integration use <key> / switch rescaffold-ят включенные пресеты.

Стратегии композиции

Стратегия	Поведение
replace (дефолт)	первый матч в стеке используется целиком
prepend	контент пресета - перед контентом меньшего приоритета
append	контент пресета - после
wrap	`{CORE_TEMPLATE}` заменяется контентом меньшего приоритета

Скрипты поддерживают replace и wrap; в обертках скриптов плейсхолдер - $CORE_SCRIPT.

Стек резолюции

От высшего приоритета к низшему:

flowchart TB A["1. Project-local overrides .specify/templates/overrides/"] --> B["2. Пресеты - по приоритету .specify/presets/‹id›/"] B --> C["3. Расширения - по приоритету .specify/extensions/‹id›/"] C --> D["4. Ядро Spec Kit .specify/templates/"]

По типам внутри слоя:

Тип	Подкаталог	Путь оверрайда
Шаблоны	`templates/`	`.specify/templates/overrides/`
Команды	`commands/`	`.specify/templates/overrides/`
Скрипты	`scripts/`	`.specify/templates/overrides/scripts/`

Резолюция в действии - plan-template.md с двумя пресетами:

flowchart TB A["Запрошен файл: plan-template.md"] --> B{"Project-local override?"} B -- "найден" --> Z["Используется этот файл"] B -- "нет" --> C{"Пресет: compliance (priority 5)"} C -- "найден" --> Z C -- "нет" --> D{"Пресет: team-workflow (priority 10)"} D -- "найден" --> Z D -- "нет" --> E{"Файлы расширений?"} E -- "найден" --> Z E -- "нет" --> F["Ядро Spec Kit"] F --> Z

Пример:

bash
specify preset add compliance --priority 5
specify preset add team-workflow --priority 10

Для файлов, которые дают оба, выигрывает compliance (5 < 10); файлы, которые дает только один, берутся от него; файлы, которых нет ни у кого, - дефолт ядра.

Частые вопросы

Несколько пресетов одновременно? Да - стек по приоритетам, каждый файл резолвится независимо от источника с высшим приоритетом; порядок управляется set-priority.
Какой файл реально используется? specify preset resolve <name> трассирует стек.
Disable против remove? Disable исключает пресет из будущей резолюции шаблонов и скриптов, но ранее зарегистрированные команды остаются в агенте до удаления - когда нужно, чтобы перестали действовать изменения команд, используйте remove. Disable удобен для временных экспериментов и сравнения вывода с пресетом и без.
Кто поддерживает пресеты? Независимые авторы; мейнтейнеры Spec Kit не ревьюят и не поддерживают код пресетов. Ревью до установки, проблемы - автору пресета.

Практика

Поставьте два пресета с приоритетами 5 и 10, дающие один шаблон, и проверьте specify preset resolve - какой слой выигрывает; поменяйте приоритеты и перепроверьте.
Сравните disable и remove одного пресета: после disable проверьте, что команды остались в агенте, а шаблон вернулся к дефолту.
Сделайте wrap-композицию шаблона: пресет-обертка с {CORE_TEMPLATE} вокруг core-шаблона - убедитесь, что контент ядра оказался внутри обертки.

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

Пресеты переопределяют шаблоны, команды и скрипты без смены тулинга, наслаиваются по приоритетам; файлы резолвятся независимо по стеку оверрайды -> пресеты -> расширения -> ядро со стратегиями replace/prepend/append/wrap. Команды материализуются в активную интеграцию и пересчитываются reconciliation-ом. Обновление деструктивно (remove + add без транзакции); каталоги наследуют модель доверия install-allowed/discovery-only с отдельной env-переменной.

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

preset update без предпроверок: неудачная замена оставляет пресет удаленным - печатается команда повтора;
disable убирает пресет из резолюции файлов, но не команд; remove вычищает все;
конфиг каталогов проекта может вести на непроверенный источник - инспектируйте catalog list в незнакомых проектах;
generic-интеграция не регистрирует командные оверрайды пресетов;
скрипты поддерживают только replace и wrap ($CORE_SCRIPT).

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

Опишите стек резолюции файлов сверху вниз. Почему каждый файл оценивается независимо?
Чем prepend/append/wrap отличаются от replace? Какой плейсхолдер у wrap для шаблонов и для скриптов?
Что происходит при preset update с невалидным источником замены? Какие гарантии отсутствуют по конструкции?
Почему disable пресета не убирает его команды из агента? Когда вместо disable нужен remove?
Где материализуются командные файлы пресетов? Что происходит при переключении дефолтной интеграции?
Какая угроза скрыта в .specify/preset-catalogs.yml проекта и как ее проверить перед установкой?

Что дальше

Workflows автоматизируют многошаговые процессы поверх команд. Урок 16.14 - YAML-синтаксис, типы шагов, условия и циклы, fan-out/fan-in, пауза и возобновление.

Источники

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