tl dr:

  • итеративный constitution.md

  • промтинг фич с помощью md-файлов

  • модификация скриптов speckit

  • git-ветки для контроля урона

  • ChatOps с уведомлениями в Telegram

  • вычитка документации вручную

  • авто-кодинг с код-ревью финального mr.

На эксперимент меня сподвигла статья, часть лайфхаков из которой я использую ниже. Автору спасибо — он куда подробнее пишет про суть исполняемых команд. Однако, в моем пайплайне в паре мест я срезаю углы или использую иной формат промтов.

Контекст

Последние дни я плотно работаю над небольшим проектом с Claude Code и speckit. Это библиотека bash-скриптов и контекста для ИИ-агентов, предназначенных для поэтапной генерации требований с помощью ИИ, а затем для поэтапной реализации этих требований. Ставится командами:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
cd <your_project>
specify init .

Проблематика

Многие задачи в разработке можно делать на автопилоте с pure-LLM и без speckit. Сейчас агенты достаточно умны, чтобы планировать и внедрять довольно сложные фичи в качестве MVP. Но мне всегда хотелось немного заземлить «звездолет». Сэмулировать проект со зрелыми процессами, где в разработке появляются декомпозированные, расписанные требования, и нет пространства для фантазий: есть спека, кодстайл, покрытие, архитектура. И разработчик с помощью ИИ должен мочь из коробки запустить внедрение таких строгих фич и быть спокойным за результат. Условно «агент попал на галеру».

Задача

Сделать CRUD-модель аутентификации и авторизации, не используя коробочные решения. Исключения: алгоритмы хеширования паролей и работы с JWT-токенами. Из специальных ограничений.

Нюансы

  1. Домен авторизации – это не рокет-сайенс. Это скорее задача с довольно понятными рамками того, как делать хорошо, а как плохо. Поэтому обрабатывать пайплайн работы с агентом удобно.

  2. Примеров кода не будет. Суть статьи не в коде, а в подходе к сбору и реализации требований.

  3. Кстати, напомню: аутентификация и авторизация – разные вещи. Аутентификация — это подтверждение вашей личности, например, с логином и паролем, а авторизация — это проверка полномочий, когда вы уже залогинены.

  4. Некоторые этапы рекомендованного флоу работы по speckit я не только пропускаю, но еще и выпилил строчки из скриптов и промтов, которые из коробки идут с либой. Подробнее в соответствующих пунктах команд ниже.

Наблюдения

Пока пользовался в процессе speckit, меня одновременно поразило то, насколько он хорошо формулирует требования. Они многогранны, ими можно пользоваться за пределами агентской разработки, просто в команду вгружать задачами. Реально напоминает артефакты бизнес- и системных аналитиков, как у меня на проекте.

И в то же время выполнение всего воркфлоу, которое у speckit описано в гите — духота. Для первого запуска ок, но для повторных — много лишних приседаний и сожраных токенов. Покопавшись в том, что ставит в проект команда по установке и инициализации, становится понятно, что это просто комплексный набор хороших практик промт-инжиниринга, собранный в структуру из md-шаблонов. Сбоку это приправлено bash-скриптами для более детерминистической работой с файлами и ветками а ля кустарный MCP.

В целом, для нейронок сейчас альтернативы к управлению имплементации и нет. Но вот что мы можем делать, так это пользоваться лучшим и тюнить то, что не подходит. В итоге у меня сформировался гибридный способ пользоваться частью навыков этой библиотеки и предсказуемым по результатам и эффективности воркфлоу, которым и хочу поделиться.

Флоу

1. Конституция

Этот этап требует вызова команды /specit.constitution, в которую вы передаете текст. В этом тексте вы пишете железобетонные, незыблемые правила вашего проекта, от которых отклоняться нельзя. Команда генерирует файл constitution.md, написанный агентом с ваших слов, в чуть более причесанной форме. Далее все этапы агент будет смотреть в вашу конституцию и стараться не фривольничать относительно её постулатов.

Лайфхак: за несколько циклов я собрал довольно полный, структурированный файл constitution.md, и команду я больше не вызываю, чтобы не тратить время и деньги. Файл содержит ограничения, которые я хочу соблюдать в принципе во всех своих проектах, поэтому команда мне больше не нужна. Ну и чуть допилить могу этот файл для конкретного проекта.

У меня там такие вещи, как:

  • Используй такой-то фреймворк + такие-то инструменты.

  • Не усложняй задачи, которые тебе ставят.

  • Делай новые фичи в отдельных ветках.

  • Пиши асинхронный код.

  • Пиши на все тесты.

  • Запускай их после изменений в коде.

  • Прогоняй линтеры.

  • Пиши документацию по-русски в стиле Google Docstring.

  • Используй именованные аргументы в функциях вместо позиционных.

  • Сохраняй архитектуру Controller > Service > CRUD.

  • У проекта такая-то структура. Соблюдай её и т.д.

2. Юзер-стори

Чтобы начать генерировать требования с speckit, нужно вызвать команду /speckit.specify <ваша бизнес-фича>. О ней будет в шаге дальше. Мне концептуально для этой команды не нравится интерфейс CLI. Он как будто подталкивает писать в одну строку, нескладно структурировать мысли.

Лайфхак: создаём md-файл (я свой назвал specify_prompt.md), пишем в нём нормальный, отформатированный, структурированный текст и передаем файл аргументом в команду. Мысли для требований я пишу как юзерстори (+ навык в копилку вашего скилла бизнес-аналитика).

# 005-authenticate-user

## User Story 1: Аутентификация

**Как пользователь системы**, я хочу аутентифицироваться с помощью моего email и пароля, чтобы пользоваться системой.

### Обоснование:
- Аутентификация - это фундаментальное требование для доступа к системе. Без неё невозможно реализовать авторизацию, и система не сможет различать разных пользователей или защищать конфиденциальные операции.

### Acceptance Criteria:
1. **Запрос на аутентификацию** авторизует пользователя по совпадению `email` и `password` с теми, что хранятся в БД.
2. **Ответ API** должен подтверждать успешную аутентификацию и выдавать JWT-токен.
3. **В случае ошибки**: если `email` не найден, пароль некорректен или пользователь неактивен, API должен вернуть соответствующий статус-код и ошибку.

### Независимая проверка:
- Может быть полностью протестирована путём попытки аутентификации с валидными учетными данными и получения токена, затем попытки с неверными учетными данными и получения соответствующей ошибки. Доставляет безопасный контроль доступа как автономную ценность.

### UI:
- Не делаем. Задача только для API

Еще лайфхак: для юзерсторей можно и нужно использовать в отдельном окне ChatGPT для предварительного обсуждения и формулировки текста. Вообще к подходу: агент + чат нативно сам прих��дишь со временем. Много где фича помогает.

Декомпозиция

Добавлю, что задачи в промте лучше декомпозировать и не ставить сразу все ТЗ, нарезанное на юзер-стори одно портянкой. Лучше несколько мелких фич, чем одна большая. Чем меньше контекста, тем меньше пространства запутаться нейронке .

Порядок юзер-сторей

Порядок имеет значение. На моем опыте если в файле specify_prompt.md в user-story-1 описать, что пользователь с ролью managerможет изменять ассортимент, и только в user-story-Nописать, как можно задавать роли пользователям, агент уйдет в бестолковый луп на первой сторе. Он начнет менять архитектуру ранее реализованных фич, чтобы куда-то вкрячить еще не реализованный механизм для смены ролей, хотя мог бы взять в работу user-story-N и проблемы бы не было.

В общем, лучше заранее составить план внедрения фич. Не накидывать по наитию типо «а вспомнил, давай еще вот это». И стори лучше поставлять связанными логическими блоками. Вы бы и разработчику так задачи не ставили и мр задолбаетесь потом ревьюить.

3. Бизнес-требования

Запускаю /speckit.specify @мой_файлик. И иду читать, как агент делает из моего текста полноценную бизнес-фичу. Он добавляет corner-кейсы, способы самопроверки, что требования соблюдены, какие-то corner-кейсы и негативные сценарии. Этот пункт я обязательно вычитываю. Всё, что он мне написал, потом пойдет в формирование фактических задач. Тут важно вычистить все лишнее, не дать агенту усложнить задачу или придумать лишние требования.

Язык

Учтите, агент всегда этот этап старается писать по-английски. Я все��да его принудительно отправляю переписывать по-русски, и вам советую. Чем вам проще читать требования, тем вдумчивее вы будете это делать. А агент дальше в артефакты не будет тянуть английский и тратить ваше время еще больше. Unless technical English practice is your goal. Then leave as is and break a leg.

Модификация: помимо прочего, команда всегда создает checklists.md в директории с вашей спекой. Это артефакт из коробки вызова скриптов в директории .specify/scripts/bash/. Я убрал его генерацию у себя из скриптов check-prerequisites.sh и common.sh, а также из логики вызова в командах .claude/commands/. Вокруг файла накручено много приседаний самопроверки нейронкой. По ощущениям, он нужен только если вы сами вручную все предыдущие этапы серьезно переписывали, а не просили это делать агента (зачем?). Поэтому создание этого файла жрет токены и не добавляет ценности. Нейронка, в моей пратике, там просто галочки ставит и все. Плюс, мешает в одно касание вычитать бизнес-требования и отправить на планирование. Работа на фоне просто так может встать и ждать подтверждения.

Есть еще плавающий баг со скриптом create-new-feature.sh, который агент дергает под капотом во время команды. В нем есть утилитные функции: get_highest_from_specs() и get_highest_from_branches(). Их суть: обеспечить сквозную номерацию формата `001, 002 ... N` у фичей, которые генерит команда. На моем опыте работает авто-инкрементация не очень. Вероятно проблема в ведущих нулях и том, что в какой-то момент именно за текстовую часть названия отвечает нейронка. В итоге, довольно часто можно получить новую фичу снова под номером 001. Об��чно сразу стопаю и прошу переделать, но вам это может быть вкусовщинрй, просто подмечаю.

ChatOps Telegram

Апдейт от 08.02. Чтобы не тратить время на простои агента в ожидании моей реакции, я настроил вебхуки в телеге:

  • Когда агенту нужно разрешение на действие

  • Когда агент выполнил задачу

Подробнее в моем коротком туториале.

4. Git-ветка

Критически важный пункт. Вызов команды выше создаёт ветку вида 001-feature-name и ведет дальше работу в ней. Даже если вы разрабатываете без speckit и используете чистый агент, этот подход вам очень поможет. Ветка — по сути изоляция вашего проекта от вреда, который может нанести агент, если его унесет не туда.

Плюс с определённого этапа мы отпустим агента в автопилот. И выполнение им работы в собственной ветке — это очень удобный способ отсмотреть историю изменений. Если нам не понравилось, что делает агент и он в моменте не может это переписать так, чтобы нравилось, мы можем:

  • Откатиться до предыдущего коммита

  • Вообще отменить все изменения

  • Глобально начать имплементацию с нуля. Спеки то остаются.

Также Git помогает ревьюить финальный MR. Об этом чуть позже.

5. План внедрения

Команда /speckit.plan <техническая реализация фичи>. Этот этап для генерации технических спецификаций: схем БД, API, слоев архитектуры.

Лайфхак: обычно я тут срезаю углы, запускаю в агенте /speckit.plan @constitution.md, потому что там у меня и так стек и глобальные технические детали для любых задач всегда описаны. В редких случаях докидываю пару слов по контексту: например, такую-то библиотеку для этой задачи используй (которой нет в конституции явно).

Спеки БД и API

Команда генерит среди прочего два немаловажных артефакта: data-model.md и openapi.yaml. Как следует из названия, это модели БД и спека API в формате OpenAPI. В первые запуски я не придавал этим файлам значения, но со временем понял, какую высокую ценность они несут.

В отличие от юзер-сторей, интерпертировать модели БД и схему API двояко нельзя. Эти требования либо есть, либо нет. И то, как они написаны, так и будут реализованы схемы и модели в коде. Именно эти документы делают имплементацию базовой инфраструктуры для ваших слоев наиболее детерминированной частью работы агента.

Как следствие, весь инференс при написании бизнесового кода имеет строгий фундамент из спек и четкой реализации взаимодействия с БД и интерфейса контроллеров. Это существенно повышает качество и предсказуемость выдаваемого кода вашей фичи в целом.

Research

Кроме того, шаг сгенерирует файл research.md, в котором будут перечислены выбранные технологии и отметённые альтернативы с обоснованием. Довольно прикольно узнать из него ход мысли агента.

Лайфхак: несите файл в ChatGPT, можете узнать второе мнение или просто расширить кругозор.

Модификация: команда всегда создает quickstart.mdв директории с вашей спекой. Я также убрал его генерацию у себя из скриптов check-prerequisites.sh и common.sh и команд Claude Code. Непонятно, для кого он нужен. У нейронки и так есть наш проект, спека фичи и constitution.md, чтобы все знать, что нужно. Тратит время, жрет токены, мусорит контекст, выпилил.

6. Нарезка задач

Вызов команды /speckit.tasks преобразует план в нумерованные фазы в файле tasks.md. А фазы — в нумерованные задачи вида T001, T002 и т.д. Очень наглядный пошаговый алгоритм того, что будет далее делать ваш агент, когда вы сядете за реализацию. Хорошо помогает прикинуть фактический объём работ. Какие секции кода будут затронуты, как поменяется БД. Вычитать тоже желательно.

Лайфхак: лишние задачи лучше попросить агента выкинуть, если всё-таки туда просочится. Также важно, чтобы итеративно агент проверял свою работу, и среди задач были пункты про запуск авто-тестов, расширение покрытия, проверку код-стиля линтерами и т.д. Всё-таки эти штуки галлюцинациями не обманешь.

Модификация: вырезал у себя из файла tasks-template.md упоминания `Parallel tasks`. Их идея в том, что агент при проектировании помечает некоторые не созависимые фазы и задачи меткой [P] . Выполнять такие задачи якобы можно параллельно. Я не знаю, кто и зачем будет следовать этой рекомендации и как вообще этим воспользоваться с агентом, кроме использования субагентов. Наша задача сделать фичу максимально автономно и детерминестически. Полагаться на такой уровень проектирования от ИИ я лично не готов и просто убрал этот лишний контекст из скрипта, а заодно сократил время генерации артефактов.

?. Самопроверка

Спорный пункт, обычно скипаю: /speckit.analyze , /speckit.checklists /speckit.clarify. Онизаставляют агента перечитывать множество артефактов и бомбить нас вопросами чаще всего за скоупом фичи. По ним агент составляет мини-отчёт или чек-лист по ответам на ваши вопросы с несостыковками и серыми зонами, их уровнями критичности и предложенными шагами по устранению. Можете их принять к сведению или забить. Я редко пользуюсь и экономлю время на более вдумчивое прочтение фичей на других этапах.

7. Реализация

Вызывается командой /speckit.implement. Агент пойдёт делать задачи, и вы получите свою фичу. Будет жрать много токенов. Тут много лайфхаков. Просто перечислю.

  • Перед запуском лучше чистить контекст. Я либо закрываю текущую сессию агента, либо принудительно у Claude Code вызываю /compact. Это позволит модели разгрузиться от тяжёлых прошлых шагов и выполнять задачу только с той информацией, что содержится в тасках из шага. Компактинг лучше вызвать руками и не допускать авто-компактинга посередине какого-нибудь критического процесса размышлений модели.

  • Команду лучше запускать фазами: /speckit.implement Phase 1-2, например. Сможете двигаться итерациями, время от времени коммитить. Между итерациями чистить или компактовать контекст модели.

  • Реализацию, в отличие от предыдущих шагов, я запускаю на авто-исполнении (git-ветка помогает не беспокоиться за последствия). Правок кода будет много, нет смысла тратить время на каждую мелкую деталь. Гораздо важнее и точнее будет посмотреть на получившийся МР, когда фазы будут завершены.

  • Делайте `git commit` после завершения фаз. Это своеобразный чекпоинт, как и у обычного разработчика. Сможете продолжить работу над тасками позже. А также откатиться д�� коммита, если нейронку унесет не туда. Да даже если не стали вычитывать все правки, сможете поэтапно откатываться назад во времени для повторных итераций.

  • Сделайте несколько фаз и пробегитесь по получившимся файлам. Сопоставьте прогресс с задачами в tasks.md, чтобы прикинуть, сколько ещё работы предстоит. Не понравившиеся места попросите агента поправить.

Финальное код-ревью

Когда все фазы завершены, отсмотрите написанное. IDE вам удобно подсветит все диффы из-за VCS. Посмотрите, не нарушены ли кор-принципы вашей архитектуры. Не появились ли лишние зависимости. Хорошее ли тестовое покрытие? Запустите тесты сами и проверьте, что они проходят.

Тут бы еще обновить и constitution.md по следам ревью. Это живой документ. Его формулировки должны со временем становиться точнее, чтобы вы меньше тратили времени на ручной контроль исполнения ваших задач агентом. Этот пункт как раз отсылает нас к итеративности, чтобы, выйдя на шаг 1, вы смогли справиться со следующей фичей ещё быстрее и качественнее.

Наконец, делаем пуш ветки в GitHub и мержим куда надо.

Задача готова. Берём следующую задачу и возвращаемся в пункт 1.

Вместо послесловия

Повторять tldr из начала особо смысла нет. Задачу я выполнил, CRUD собрал. По пути также собрал набор артефактов и шаблонов, которые в принципе могут работать и за рамками speckit. Такой челлендж позволил придумать подход с готовыми файлами вместо живого промтинга в CLI, научил паре вещей в домене авторизации и позволил поделиться опытом с вами. Может кому-то как и мне speckit местами показался громоздким, но хотелось из него вытащить какие-то удобные решения и моя статья позвоит посмотреть на либу по новому.

Еще добавлю, что хотя флоу почти не подразумевает кодинг вручную, осмысленный подход к требованиям и код-ревью, мне лично, в паре вопросов помогли расширить кругозор. Структура проекта оставалась на протяжении всей сессии мне понятой. А реализованный функционал был мной согласован в точности до метода. То есть spec-driven vibe-coding все таки помимо фоновой активности что-то в голове да откладывает. Какую-то связь между мной-наблюдателем и результатом-синтетикой все же создает. А это на живом проекте с живыми людьми и зонами ответственности за свою работу было бы немаловажно.

Удачных экспериментов!