- Регистрация
- 23 Авг 2023
- Сообщения
- 3,969
- Реакции
- 0
- Баллы
- 36
Ofline
tl dr:
На эксперимент меня сподвигла статья, часть лайфхаков из которой я использую ниже. Автору спасибо — он куда подробнее пишет про суть исполняемых команд. Однако, в моем пайплайне в паре мест я срезаю углы или использую иной формат промтов.
Контекст
Последние дни я плотно работаю над небольшим проектом с Claude Code и speckit. Это библиотека bash-скриптов и контекста для ИИ-агентов, предназначенных для поэтапной генерации требований с помощью ИИ, а затем для поэтапной реализации этих требований. Ставится командами:
uv tool install specify-cli --from git+GitHub - github/spec-kit: Toolkit to help you get started with Spec-Driven Development https://github.com/github/spec-kit.git
cd <your_project>
specify init .
Проблематика
Многие задачи в разработке можно делать на автопилоте с pure-LLM и без speckit. Сейчас агенты достаточно умны, чтобы планировать и внедрять довольно сложные фичи в качестве MVP. Но мне всегда хотелось немного заземлить «звездолет». Сэмулировать проект со зрелыми процессами, где в разработке появляются декомпозированные, расписанные требования, и нет пространства для фантазий: есть спека, кодстайл, покрытие, архитектура. И разработчик с помощью ИИ должен мочь из коробки запустить внедрение таких строгих фич и быть спокойным за результат. Условно «агент попал на галеру».
Задача
Сделать CRUD-модель аутентификации и авторизации, не используя коробочные решения. Исключения: алгоритмы хеширования паролей и работы с JWT-токенами. Из специальных ограничений.
Нюансы
Пока пользовался в процессе speckit, меня одновременно поразило и то, насколько он хорошо формулирует требования. Они многогранны, ими можно пользоваться за пределами агентской разработки, просто в команду вгружать задачами. Реально напоминает артефакты бизнес- и системных аналитиков, как у меня на проекте.
И в то же время выполнение всего воркфлоу, которое у speckit в гите — это душно. Для первого запуска ок, но для повторных — много лишних приседаний и сожраных токенов. В итоге у меня сформировался гибридный способ пользоваться частью навыков этой библиотеки и предсказуемым по результатам и эффективности воркфлоу, которым и хочу поделиться.
Флоу
Конституция
Этот этап требует вызова команды /specit.constitution, в которую вы передаете текст. В этом тексте вы пишете железобетонные, незыблимые правила вашего проекта, от которых отклоняться нельзя. Команда генерирует файл constitution.md, написанный агентом с ваших слов, в чуть более причесанной форме. Далее все этапы агент будет смотреть в вашу конституцию и стараться не фривольничать относительно её постулатов.
Лайфхак: за несколько циклов я собрал довольно полный, структурированный файл constitution.md, и команду я больше не вызываю, чтобы не тратить время и деньги. Файл содержит ограничения, которые я хочу соблюдать в принципе во всех своих проектах, поэтому команда мне больше не нужна. Ну и чуть допилить могу этот файл для конкретного проекта.
У меня там такие вещи, как:
Чтобы начать генерировать требования с speckit, нужно вызвать команду /speckit.specify <ваша бизнес-фича>. О ней будет в шаге дальше. Мне концептуально для этой команды не нравится интерфейс CLI. Он как будто подталкивает писать в одну строку, нескладно структурировать мысли.
Лайфхак: создаём md-файл, пишем в нём нормальный, отформатированный, структурированный текст и передаем файл аргументом в команду. Мысли для требований я пишу как юзерстори (+ навык в копилку вашего скилла бизнес-аналитика).
# 005-authenticate-user
## User Story 1: Аутентификация
**Как пользователь системы**, я хочу аутентифицироваться с помощью моего email и пароля, чтобы пользоваться системой.
### Обоснование:
- Аутентификация - это фундаментальное требование для доступа к системе. Без неё невозможно реализовать авторизацию, и система не сможет различать разных пользователей или защищать конфиденциальные операции.
### Acceptance Criteria:
1. **Запрос на аутентификацию** авторизует пользователя по совпадению `email` и `password` с теми, что хранятся в БД.
2. **Ответ API** должен подтверждать успешную аутентификацию и выдавать JWT-токен.
3. **В случае ошибки**: если `email` не найден, пароль некорректен или пользователь неактивен, API должен вернуть соответствующий статус-код и ошибку.
### Независимая проверка:
- Может быть полностью протестирована путём попытки аутентификации с валидными учетными данными и получения токена, затем попытки с неверными учетными данными и получения соответствующей ошибки. Доставляет безопасный контроль доступа как автономную ценность.
### UI:
- Не делаем. Задача только для API
Еще лайфхак: для юзерсторей можно и нужно использовать в отдельном окне ChatGPT для предварительного обсуждения и формулировки текста. Вообще к подходу: агент + чат нативно сам приходишь со временем. Много где фича помогает.
UPD из треда: агент всегда этот этап старается писать по-английски. Я всегда его принудительно отправляю переписывать по-русски, и вам советую. Чем вам проще читать требования, тем вдумчивее вы будете это делать. А агент дальше в артефакты не будет тянуть английский и тратить ваше время еще больше Unless technical English practice is your goal. Then leave as is and break a leg.
Бизнес-требования
Запускаю /speckit.specify @мой_файлик. И иду читать, как агент делает из моего текста полноценную бизнес-фичу. Он добавляет corner-кейсы, способы самопроверки, что требования соблюдены, какие-то corner-кейсы и негативные сценарии. Этот пункт я обязательно вычитываю. Всё, что он мне написал, потом пойдет в формирование фактических задач. Тут важно вычистить все лишнее, не дать агенту усложнить задачу или придумать лишние требования.
Git-ветка
Критически важный пункт. Вызов команды выше создаёт ветку вида 001-feature-name и ведет дальше работу в ней. Даже если вы разрабатываете без speckit и используете чистый агент, этот подход вам очень поможет. Ветка — по сути изоляция вашего проекта от вреда, который может нанести агент, если его унесет не туда. Плюс с определённого этапа мы отпустим агента в автопилот. И выполнение им работы в собственной ветке — это очень удобный способ отсмотреть историю изменений. Об этом пункте чуть позже.
План внедрения
Команда /speckit.plan <техническая реализация фичи>. Этот этап для генерации технических спецификаций: схем БД, API, слоев архитектуры.
Лайфхак: обычно я тут срезаю углы, запускаю в агенте /speckit.plan @constitution.md, потому что там у меня и так стек и глобальные технические детали для любых задач всегда описаны. В редких случаях докидываю пару слов по контексту: например, такую-то библиотеку для этой задачи используй (которой нет в конституции явно).
Кроме того, шаг сгенерирует файл research.md, в котором будут перечислены выбранные технологии и отметённые альтернативы с обоснованием. Довольно прикольно узнать из него ход мысли агента.
Лайфхак: несите файл в ChatGPT, можете узнать второе мнение или просто расширить кругозор.
Нарезка задач
Вызов команды /speckit.tasks преобразует план в нумерованные фазы в файле tasks.md. А фазы — в нумерованные задачи вида T001, T002 и т.д. Очень наглядный пошаговый алгоритм того, что будет далее делать ваш агент, когда вы сядете за реализацию. Хорошо помогает прикинуть фактический объём работ. Какие секции кода будут затронуты, как поменяется БД. Вычитать тоже желательно.
Лайфхак: лишние задачи лучше попросить агента выкинуть, если всё-таки туда просочится. Также важно, чтобы итеративно агент проверял свою работу, и среди задач были пункты про запуск авто-тестов, расширение покрытия, проверку код-стиля линтерами и т.д. Всё-таки эти штуки галлюцинациями не обманешь.
Самопроверка
Спорный пункт, иногда скипаю. /speckit.analyze заставляет агента перечитать все артефакты в рамках новой фичи. Он составит мини-отчёт с несостыковками, их уровнями критичности и предложенными шагами по устранению. Можете их принять к сведению и забить, но иногда стоит поправить.
Реализация
Вызывается командой /speckit.implement. Агент пойдёт делать задачи, и вы получите свою фичу. Будет жрать много токенов. Тут много лайфхаков. Просто перечислю.
Когда все фазы завершены, отсмотрите написанное. IDE вам удобно подсветит все диффы из-за VCS. Посмотрите, не нарушены ли кор-принципы вашей архитектуры. Не появились ли лишние зависимости. Хорошее ли тестовое покрытие? Запустите тесты сами и проверьте, что они проходят.
Тут бы еще обновить и constitution.md по следам ревью. Это живой документ. Его формулировки должны со временем становиться точнее, чтобы вы меньше тратили времени на ручной контроль исполнения ваших задач агентом. Этот пункт как раз отсылает нас к итеративности, чтобы, выйдя на шаг 1, вы смогли справиться со следующей фичей ещё быстрее и качественнее.
Наконец, делаем пуш ветки в GitHub и мержим куда надо.
Задача готова. Берём следующую задачу и возвращаемся в пункт 1.
Вместо послесловия
Повторять tldr из начала особо смысла нет. Задачу я выполнил, CRUD собрал. По пути также собрал набор артефактов и шаблонов, которые в принципе могут работать и за рамками speckit. Такой челлендж позволил придумать подход с готовыми файлами вместо живого промтинга в CLI, научил паре вещей в домене авторизации и позволил поделиться опытом с вами. Может кому-то как и мне speckit местами показался громоздким, но хотелось из него вытащить какие-то удобные решения и моя статья позвоит посмотреть на либу по новому.
Еще добавлю, что хотя флоу почти не подразумевает кодинг вручную, осмысленный подход к требованиям и код-ревью, мне лично, в паре вопросов помогли расширить кругозор. Структура проекта оставалась на протяжении всей сессии мне понятой. А реализованный функционал был мной согласован в точности до метода. То есть spec-driven vibe-coding все таки помимо фоновой активности что-то в голове да откладывает. Какую-то связь между мной-наблюдателем и результатом-синтетикой все же создает. А это на живом проекте с живыми людьми и зонами ответственности за свою работу было бы немаловажно.
Удачных экспериментов!
итеративный constitution.md
промтинг фич с помощью md-файлов
git-ветки для контроля урона
вычитка документации вручную
авто-кодинг с код-ревью финального mr.
На эксперимент меня сподвигла статья, часть лайфхаков из которой я использую ниже. Автору спасибо — он куда подробнее пишет про суть исполняемых команд. Однако, в моем пайплайне в паре мест я срезаю углы или использую иной формат промтов.
Контекст
Последние дни я плотно работаю над небольшим проектом с Claude Code и speckit. Это библиотека bash-скриптов и контекста для ИИ-агентов, предназначенных для поэтапной генерации требований с помощью ИИ, а затем для поэтапной реализации этих требований. Ставится командами:
uv tool install specify-cli --from git+GitHub - github/spec-kit: Toolkit to help you get started with Spec-Driven Development https://github.com/github/spec-kit.git
cd <your_project>
specify init .
Проблематика
Многие задачи в разработке можно делать на автопилоте с pure-LLM и без speckit. Сейчас агенты достаточно умны, чтобы планировать и внедрять довольно сложные фичи в качестве MVP. Но мне всегда хотелось немного заземлить «звездолет». Сэмулировать проект со зрелыми процессами, где в разработке появляются декомпозированные, расписанные требования, и нет пространства для фантазий: есть спека, кодстайл, покрытие, архитектура. И разработчик с помощью ИИ должен мочь из коробки запустить внедрение таких строгих фич и быть спокойным за результат. Условно «агент попал на галеру».
Задача
Сделать CRUD-модель аутентификации и авторизации, не используя коробочные решения. Исключения: алгоритмы хеширования паролей и работы с JWT-токенами. Из специальных ограничений.
Нюансы
Домен авторизации – это не рокет-сайенс. Это скорее задача с довольно понятными рамками того, как делать хорошо, а как плохо. Поэтому обрабатывать пайплайн работы с агентом удобно.
Примеров кода не будет. Суть статьи не в коде, а в подходе к сбору и реализации требований.
Кстати, напомню: аутентификация и авторизация – разные вещи. Аутентификация — это подтверждение вашей личности, например, с логином и паролем, а авторизация — это проверка полномочий, когда вы уже залогинены.
Пока пользовался в процессе speckit, меня одновременно поразило и то, насколько он хорошо формулирует требования. Они многогранны, ими можно пользоваться за пределами агентской разработки, просто в команду вгружать задачами. Реально напоминает артефакты бизнес- и системных аналитиков, как у меня на проекте.
И в то же время выполнение всего воркфлоу, которое у speckit в гите — это душно. Для первого запуска ок, но для повторных — много лишних приседаний и сожраных токенов. В итоге у меня сформировался гибридный способ пользоваться частью навыков этой библиотеки и предсказуемым по результатам и эффективности воркфлоу, которым и хочу поделиться.
Флоу
Конституция
Этот этап требует вызова команды /specit.constitution, в которую вы передаете текст. В этом тексте вы пишете железобетонные, незыблимые правила вашего проекта, от которых отклоняться нельзя. Команда генерирует файл constitution.md, написанный агентом с ваших слов, в чуть более причесанной форме. Далее все этапы агент будет смотреть в вашу конституцию и стараться не фривольничать относительно её постулатов.
Лайфхак: за несколько циклов я собрал довольно полный, структурированный файл constitution.md, и команду я больше не вызываю, чтобы не тратить время и деньги. Файл содержит ограничения, которые я хочу соблюдать в принципе во всех своих проектах, поэтому команда мне больше не нужна. Ну и чуть допилить могу этот файл для конкретного проекта.
У меня там такие вещи, как:
Используй такой-то фреймворк + такие-то инструменты.
Не усложняй задачи, которые тебе ставят.
Делай новые фичи в отдельных ветках.
Пиши асинхронный код.
Пиши на все тесты.
Запускай их после изменений в коде.
Прогоняй линтеры.
Пиши документацию по-русски в стиле Google Docstring.
Используй именованные аргументы в функциях вместо позиционных.
Сохраняй архитектуру Controller > Service > CRUD.
У проекта такая-то структура. Соблюдай её и т.д.
Чтобы начать генерировать требования с speckit, нужно вызвать команду /speckit.specify <ваша бизнес-фича>. О ней будет в шаге дальше. Мне концептуально для этой команды не нравится интерфейс CLI. Он как будто подталкивает писать в одну строку, нескладно структурировать мысли.
Лайфхак: создаём md-файл, пишем в нём нормальный, отформатированный, структурированный текст и передаем файл аргументом в команду. Мысли для требований я пишу как юзерстори (+ навык в копилку вашего скилла бизнес-аналитика).
# 005-authenticate-user
## User Story 1: Аутентификация
**Как пользователь системы**, я хочу аутентифицироваться с помощью моего email и пароля, чтобы пользоваться системой.
### Обоснование:
- Аутентификация - это фундаментальное требование для доступа к системе. Без неё невозможно реализовать авторизацию, и система не сможет различать разных пользователей или защищать конфиденциальные операции.
### Acceptance Criteria:
1. **Запрос на аутентификацию** авторизует пользователя по совпадению `email` и `password` с теми, что хранятся в БД.
2. **Ответ API** должен подтверждать успешную аутентификацию и выдавать JWT-токен.
3. **В случае ошибки**: если `email` не найден, пароль некорректен или пользователь неактивен, API должен вернуть соответствующий статус-код и ошибку.
### Независимая проверка:
- Может быть полностью протестирована путём попытки аутентификации с валидными учетными данными и получения токена, затем попытки с неверными учетными данными и получения соответствующей ошибки. Доставляет безопасный контроль доступа как автономную ценность.
### UI:
- Не делаем. Задача только для API
Еще лайфхак: для юзерсторей можно и нужно использовать в отдельном окне ChatGPT для предварительного обсуждения и формулировки текста. Вообще к подходу: агент + чат нативно сам приходишь со временем. Много где фича помогает.
UPD из треда: агент всегда этот этап старается писать по-английски. Я всегда его принудительно отправляю переписывать по-русски, и вам советую. Чем вам проще читать требования, тем вдумчивее вы будете это делать. А агент дальше в артефакты не будет тянуть английский и тратить ваше время еще больше Unless technical English practice is your goal. Then leave as is and break a leg.
Бизнес-требования
Запускаю /speckit.specify @мой_файлик. И иду читать, как агент делает из моего текста полноценную бизнес-фичу. Он добавляет corner-кейсы, способы самопроверки, что требования соблюдены, какие-то corner-кейсы и негативные сценарии. Этот пункт я обязательно вычитываю. Всё, что он мне написал, потом пойдет в формирование фактических задач. Тут важно вычистить все лишнее, не дать агенту усложнить задачу или придумать лишние требования.
Git-ветка
Критически важный пункт. Вызов команды выше создаёт ветку вида 001-feature-name и ведет дальше работу в ней. Даже если вы разрабатываете без speckit и используете чистый агент, этот подход вам очень поможет. Ветка — по сути изоляция вашего проекта от вреда, который может нанести агент, если его унесет не туда. Плюс с определённого этапа мы отпустим агента в автопилот. И выполнение им работы в собственной ветке — это очень удобный способ отсмотреть историю изменений. Об этом пункте чуть позже.
План внедрения
Команда /speckit.plan <техническая реализация фичи>. Этот этап для генерации технических спецификаций: схем БД, API, слоев архитектуры.
Лайфхак: обычно я тут срезаю углы, запускаю в агенте /speckit.plan @constitution.md, потому что там у меня и так стек и глобальные технические детали для любых задач всегда описаны. В редких случаях докидываю пару слов по контексту: например, такую-то библиотеку для этой задачи используй (которой нет в конституции явно).
Кроме того, шаг сгенерирует файл research.md, в котором будут перечислены выбранные технологии и отметённые альтернативы с обоснованием. Довольно прикольно узнать из него ход мысли агента.
Лайфхак: несите файл в ChatGPT, можете узнать второе мнение или просто расширить кругозор.
Нарезка задач
Вызов команды /speckit.tasks преобразует план в нумерованные фазы в файле tasks.md. А фазы — в нумерованные задачи вида T001, T002 и т.д. Очень наглядный пошаговый алгоритм того, что будет далее делать ваш агент, когда вы сядете за реализацию. Хорошо помогает прикинуть фактический объём работ. Какие секции кода будут затронуты, как поменяется БД. Вычитать тоже желательно.
Лайфхак: лишние задачи лучше попросить агента выкинуть, если всё-таки туда просочится. Также важно, чтобы итеративно агент проверял свою работу, и среди задач были пункты про запуск авто-тестов, расширение покрытия, проверку код-стиля линтерами и т.д. Всё-таки эти штуки галлюцинациями не обманешь.
Самопроверка
Спорный пункт, иногда скипаю. /speckit.analyze заставляет агента перечитать все артефакты в рамках новой фичи. Он составит мини-отчёт с несостыковками, их уровнями критичности и предложенными шагами по устранению. Можете их принять к сведению и забить, но иногда стоит поправить.
Реализация
Вызывается командой /speckit.implement. Агент пойдёт делать задачи, и вы получите свою фичу. Будет жрать много токенов. Тут много лайфхаков. Просто перечислю.
Перед запуском лучше чистить контекст. Я либо закрываю текущую сессию агента, либо принудительно у Claude Code вызываю /compact. Это позволит модели разгрузиться от тяжёлых прошлых шагов и выполнять задачу только с той информацией, что содержится в тасках из шага. Компактинг лучше вызвать руками и не допускать авто-компактинга посередине какого-нибудь критического процесса размышлений модели.
Команду лучше запускать фазами: /speckit.implement Phase 1-2, например. Сможете двигаться итерациями, время от времени коммитить. Между итерациями чистить или компактовать контекст модели.
Реализацию, в отличие от предыдущих шагов, я запускаю на авто-исполнении (git-ветка помогает не беспокоиться за последствия). Правок кода будет много, нет смысла тратить время на каждую мелкую деталь. Гораздо важнее и точнее будет посмотреть на получившийся МР, когда фазы будут завершены.
Сделайте несколько фаз и пробегитесь по получившимся файлам. Сопоставьте прогресс с задачами в tasks.md, чтобы прикинуть, сколько ещё работы предстоит. Не понравившиеся места попросите агента поправить.
Когда все фазы завершены, отсмотрите написанное. IDE вам удобно подсветит все диффы из-за VCS. Посмотрите, не нарушены ли кор-принципы вашей архитектуры. Не появились ли лишние зависимости. Хорошее ли тестовое покрытие? Запустите тесты сами и проверьте, что они проходят.
Тут бы еще обновить и constitution.md по следам ревью. Это живой документ. Его формулировки должны со временем становиться точнее, чтобы вы меньше тратили времени на ручной контроль исполнения ваших задач агентом. Этот пункт как раз отсылает нас к итеративности, чтобы, выйдя на шаг 1, вы смогли справиться со следующей фичей ещё быстрее и качественнее.
Наконец, делаем пуш ветки в GitHub и мержим куда надо.
Задача готова. Берём следующую задачу и возвращаемся в пункт 1.
Вместо послесловия
Повторять tldr из начала особо смысла нет. Задачу я выполнил, CRUD собрал. По пути также собрал набор артефактов и шаблонов, которые в принципе могут работать и за рамками speckit. Такой челлендж позволил придумать подход с готовыми файлами вместо живого промтинга в CLI, научил паре вещей в домене авторизации и позволил поделиться опытом с вами. Может кому-то как и мне speckit местами показался громоздким, но хотелось из него вытащить какие-то удобные решения и моя статья позвоит посмотреть на либу по новому.
Еще добавлю, что хотя флоу почти не подразумевает кодинг вручную, осмысленный подход к требованиям и код-ревью, мне лично, в паре вопросов помогли расширить кругозор. Структура проекта оставалась на протяжении всей сессии мне понятой. А реализованный функционал был мной согласован в точности до метода. То есть spec-driven vibe-coding все таки помимо фоновой активности что-то в голове да откладывает. Какую-то связь между мной-наблюдателем и результатом-синтетикой все же создает. А это на живом проекте с живыми людьми и зонами ответственности за свою работу было бы немаловажно.
Удачных экспериментов!