Spec Kit без тяжёлого CLI: как адаптировать Spec-Driven подход под свой проект в Cursor

Для кого: разработчики, аналитики и технические писатели, которые хотят вести работу с ИИ по спецификациям, но не готовы разворачивать полный Spec Kit от GitHub со всем конвейером команд.

О чём: адаптация разработки на основе спецификаций (Spec-Driven Development) под один репозиторий в Cursor – без универсальной командной строки инструмента, с той же дисциплиной: сначала согласовать спецификацию, затем реализовать.

Зачем разработка на основе спецификаций и зачем не весь Spec Kit

Идея проста: сначала зафиксировать что делаем, затем дать агенту как реализовать в рамках правил проекта.

Официальный Spec Kit – инструментарий для такой разработки с ИИ-агентами: шаги constitution, specify, plan, tasks, implement и каталог .specify/. Он рассчитан на полный конвейер в проекте (в том числе создание с нуля, новые возможности в сложной кодовой базе, модернизация унаследованных систем).

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

• конституция – незыблемые правила репозитория;

• спецификация задачи;

• явное согласование человеком (агент сам себе статус согласия не выставляет);

• реализация по согласованному;

• указатель текущей активной работы.

Отдельные plan, clarify, tasks и пакетная полная пересборка нередко избыточны: множат файлы, повышают риск перезаписать согласованное и увеличивают шум для модели. Целесообразнее не отказываться от методологии, а сжать её до рабочего минимума и встроить в Cursor.

Суть в одной формуле

Черновик (по желанию) → спецификация → agreed → реализация.

Агент не импровизирует продукт. Он опирается на источники (код, тикеты, вики и иные материалы проекта) и согласованную спецификацию либо явно фиксирует [НЕ ИЗВЕСТНО] / TODO. Отсутствие доступа ко всем источникам не отменяет работу по уже имеющимся материалам. Режим reasoning_temperature: low по умолчанию запрещает домыслы.

Метка статуса (draft / agreed или, например, черновик / согласовано) – по соглашению проекта. Смысл один: без согласия человека implement запрещён.

Два слоя не смешивать:

Спецификация – договорённость. Результат – следствие. Пока нет статуса согласия, результат не пишем.

Адаптация: три части вместо полного конвейера

В Cursor тот же смысл собирается из трёх составляющих:

1. Rules – .cursor/rules/*.mdc: всегда в контексте (источники истины, конвейер, запреты). После изменения конституции rules синхронизируют с ней.

2. Skills – .cursor/skills/*/SKILL.md: явные команды /project-init, /project-specify, /project-implement.

3. Артефакты в репозитории – конституция, спецификации, черновики, указатель активной задачи.

Имена project-* – шаблон: замените префиксом своего проекта.

.cursor/  rules/project.mdc  skills/    project-init/SKILL.md    project-specify/SKILL.md    project-implement/SKILL.mdproject-spec/  feature.json              # { "active_spec": "specs/002-….md" }  memory/constitution.md  requirements/             # черновики до формальной спецификации (необязательно)  specs/                    # 001 – видение; далее – задачи  prompts/prompt-init.md    # контрольный список первичной настройки / повторного init

Для кода implement пишет в src/ и tests/. Для документации – в принятый формат публикации. Методология одна; меняется только целевой слой результата.

Указатель активной спецификации

feature.json – аналог фокуса из полного Spec Kit:

{  "active_spec": "specs/002-user-login.md"}

При specify агент обновляет указатель; при implement читает его, если путь не задан явно. Смена фокуса – обновить файл или указать: «активная спецификация – specs/004-…».

Конституция: обязательный минимум

В constitution.md:

• цель проекта и границы;

• конвейер: requirements (необязательно) → specify → согласие человека → implement;

• что сознательно не используем (plan / tasks / массовая полная пересборка);

• что относится к слою смысла, что – к слою результата;

• верность источникам и пометки [НЕ ИЗВЕСТНО];

• reasoning_temperature (для финальной реализации – low);

• запрет секретов в публикации;

• порядок изменения самой конституции (только явно) и синхронизация rules.

Три команды

Ролевые skills («аналитик», «технический писатель») обычно не нужны – роли задаются текстом в конституции. Skill предпочтительно вызывать явно (disable-model-invocation: true).

Порядок работы

1. /project-init → при необходимости скорректировать конституцию и синхронизировать rules.

2. При необходимости – черновик в requirements/ (можно сразу запрос на specify).

3. /project-specify → отредактировать спецификацию, закрыть блокирующие [НЕ ИЗВЕСТНО].

4. Согласование человеком → статус согласия (agreed / согласовано).

5. Только после этого /project-implement.

6. Проверка результата, ревью, запрос на слияние → следующая спецификация через feature.json.

Условия перед implement

В каждой спецификации:

• статус черновика или согласия;

• список открытых неизвестных;

• при необходимости контрольный список файлов / разделов / критериев готовности;

• правило: implement только при статусе согласия и без блокирующих [НЕ ИЗВЕСТНО].

Исключение: specs/001-*-view – обзорное видение проекта (назначение системы, границы, крупные пакеты). Его согласуют, но implement по нему не выполняют.

Спецификация отвечает на четыре вопроса: зачем; что входит и что нет; по каким критериям готово; что ещё неизвестно. Пока неизвестное блокирует результат – статус согласия недопустим.

План без отдельного tasks.md

Отдельный файл задач не нужен. План живёт так:

• в видении 001 – крупные пакеты;

• в контрольном списке внутри каждой спецификации – файлы, разделы, критерии готовности;

• в статусах и в feature.json – что сейчас в фокусе.

Чего избегать: не запускать весь контур сразу по всем спецификациям. Массовый init / specify легко перезаписывает конституцию и согласованное. Достаточно одной активной спецификации. Несколько согласованных подряд – только по явному запросу и по одной за раз.

Отложено: после первой сборки по спецификациям не пересобирать всё с нуля. Далее – по различиям в источниках актуализировать только изменившееся и выпускать версию на дату. Политику хранения версий определяет проект; на старте достаточно явного решения, без усложнения конвейера.

Частые ошибки

1. Implement из черновика – requirements/ не даёт права на результат.

2. Смешение видения и черновика – requirements/… ≠ specs/001-….

3. Избыток skills – роли в конституции; команды только init / specify / implement.

4. Смешение слоёв – исходные материалы и договорённости не становятся продуктом без переработки.

5. Повторный init без необходимости – перезаписывает канон; только явно.

6. Высокая temperature на финале – для согласованного результата оставляйте low.

7. Самосогласование агентом – статус согласия выставляет человек.

Когда достаточно упрощённого контура

Упрощённого контура достаточно, если задачи идут по одной, важны согласование и защита от выдуманных фактов моделью, а отдельный plan / tasks / analyze увеличивает шум без выигрыша; цель – код или документация в Cursor.

Полный Spec Kit целесообразен, если нужен готовый интерфейс командной строки и стандартный многошаговый конвейер (specify → plan → tasks → implement, плюс clarify / analyze), жёсткие шаблоны артефактов в стандартной поставке или команда уже работает в экосистеме specify.

Подходы совместимы: конституцию и спецификации можно переиспользовать при переходе на полный Spec Kit; командную строку и остальные шаги конвейера настраивают отдельно.

Заключение

Необязательно разворачивать весь Spec Kit, чтобы получить дисциплину «спецификация → согласие → реализация» в Cursor. Достаточно конституции, трёх skills, указателя активной спецификации и правила: не выдумывать факты и не писать результат до согласования человеком.

Так ведутся два контура:

1. Документация продукта – implement собирает публикуемые страницы только из согласованных спецификаций.

2. Платформа (клиентская часть, серверная часть, поиск и анализ кода) – тот же каркас, но implement пишет и сопровождает код.

Порядок внедрения: init → однократное согласование конституции → затем создание спецификаций. Дисциплина конвейера важнее структуры каталогов.

Контрольные точки после настройки

Префикс project замените своим.

• Канон: project-spec/memory/constitution.md

• Фокус: project-spec/feature.json

• Видение: project-spec/specs/001-project-view.md

• Правила агента: .cursor/rules/project.mdc

• Команды: .cursor/skills/project-*