Transcription
Вайб-кодинг на основе спецификаций превращает твоё расплывчатое описание проекта в чётко определённые, структурированные документы с задачами для твоих иагентов и значительно сокращает количество багов и ошибок в твоём проекте. GitHub Spec Kit - это инструмент, который делает этот процесс очень простым и автоматизированным, и он сводит всю работу к нескольким простым шагам. И сейчас я всё тебе об этом расскажу по порядку.
Данный ролик построен на основе видеоряда от самого разработчика GitHub Spec Kit, Дна Делемарски, а также собственного опыта тестирования этого инструмента на протяжении двух недель. Я расскажу не только о том, как его установить и пользоваться в новом проекте, но ещё и о том, как внедрить его в уже существующий проект. Также я расскажу о его проблемах, подводных камнях, с которыми ты обязательно столкнёшься. В общем, чтобы ты имел полное представление о том, что такое GitHub Spec Kit. Спойлер: всё не так уж и радужно.
Итак, чтобы установить GitHub Spec Kit, тебе сперва необходимо перейти по ссылке в описании на страницу проекта. Вот здесь ты увидишь команду для установки, но перед этим тебе необходимо будет сначала установить UV. Ссылку я тоже оставлю в описании. В принципе, вариант очень удобный, но если ты не хочешь заморачиваться, файлы Spec Kit можно скачать напрямую из раздела релизов. Кликаем вот сюда, нажимаем вот здесь "показать все ассеты" и ищем свой инструмент для вайб-кодинга. Spec Kit подходит для курсора, клодкода, кодекса и других популярных решений. Я использую курсор как свой основной инструмент.
И можно заметить, что здесь целых два архива, которые я могу скачать: Agent PS и Agent SH. А если ты используешь устройство на базе Windows, то тебе необходимо скачать вариант с PS, то есть PowerShell. Если ты используешь MacOS, как использую его сейчас я, необходимо скачать вот этот вариант с SH. После того, как всё скачается, распаковывай архив и закидывай все файлы прямо в корневую директорию твоего проекта. Я же, давай, воспользуюсь вот этой командой, нажму, чтобы скопировать, и вставлю в свой терминал. Мне необходимо вместо Project name указать название своего проекта, а пускай будет Spec Kit.
После того, как установка завершилась, у меня автоматически открылся Specify, и мне здесь предлагается выбрать своего иагента, то есть инструмент, с помощью которого я занимаюсь вайб-кодингом. И поскольку я сейчас тебе буду показывать с помощью курсора, я выбираю именно его. Choose Script Type. А, опять же, как я говорил, PS PowerShell для Windows, SH - это наш вариант для MacOS. Жму Enter.
Теперь давай пройдёмся по командам. Spec Kit Constitution. Здесь ты должен описать незыблемые правила и принципы, которым должна следовать нейросеть и от которых ни в коем случае не должна отходить. Это принципы разработки, архитектурный стиль и так далее.
Проект, который я сегодня буду разрабатывать, - интерактивная карта мемов, где пользователи могут ставить точки на карте, где происходили события из мемов, ну или из анекдотов, если ты постарше, с возможностью загружать видео и картинки этих самых мемов. Для написания файла Constitution и всех будущих этапов, идущих до разработки, Дн Дельмарский советует использовать GPT-5. По его мнению, GPT справляется с этими задачами лучше, чем модели Clot. Но твой опыт может отличаться, поэтому протестируй разные варианты.
Давай введём Spec Kit Constitution. И я подготовил следующий промт: "Я хочу иметь Typescript без any, Prettier, архитектуру хочу Sliced design. Тесты мне не нужны, потому что это такой наш демонстрационный учебный проект", и так далее и тому подобное. Если у тебя нет представления, каким незыблемым правилам должна следовать нейросеть, можешь, в принципе, попросить её написать тебе эти правила под твой проект или, в принципе, можешь спокойно пропустить данный этап.
Следующим шагом тебе необходимо ввести команду Spec Kit Specify. На этом этапе от тебя требуется простым человеческим языком описать, что именно ты хочешь реализовать, не вдаваясь в технические подробности, как будто ты продуктовый менеджер или системный аналитик, который пишет функциональные требования, но не техническим языком. Основная идея, о которой говорит разработчик GitHub Spec Kit, в том, чтобы получившийся файл спецификации ты мог сам прочитать и понять, о чём там вообще идёт речь, а, и во-вторых, мог отдать его своему коллеге, чтобы он продолжил работу над фичой.
Так, Specify, вот она, наша команда. Требуется разработать сайт под названием "Карта мемов", где люди могут отмечать на мировой карте места, связанные со смешными мемами. Каждая точка на карте показывает мем с коротким превью, картинкой или видео. Пользователи могут загружать свои мемы, выбирать точку на карте. Посетители могут исследовать карту, кликать по местам, чтобы посмотреть мемы и чтобы ставить лайки.
У нас появилась папка SPECs. И вот она, наша первая спецификация. Давай посмотрим, что здесь находится. Пользовательские сценарии: исследование карты, возможность зума, панорамирование, клика. Так, пользовательская история номер два: добавление нового мема, описание этой истории, почему она важна и так далее. Возможность эти мемы лайкать. Отлично.
Дальше у нас идут функциональные требования. Если ты вдруг системный аналитик или продуктовый/проектный менеджер, скорее всего, ты знаешь, что такое функциональные требования. Возможно, даже ты их писал. Ну вот здесь написано, что система должна отображать мировую карту, которую пользователь может зумить, может кликать на маркеры, чтобы посмотреть превьюшки, картинка или видео. Так, может файлы загружать, в каком формате. В принципе, можешь поставить на паузу, если интересно, и всё это дело изучить.
Когда ты закончил с простым человеческим описанием, приступай к команде Spec Kit Clarify. Она, в принципе, не обязательная, но она позволит уточнить твои требования. Если ты где-то ошибся, что-то не продумал, нейронка это заметит и спросит у тебя, что же ты всё-таки имел в виду. И выглядит это следующим образом. Нейросеть нам задаёт какие-то уточняющие вопросы, допустим, по поводу того, должна ли быть у нас какая-то авторизация, аутентификация, потому что я об этом не сказал изначально. Вот. И предлагает нам выбрать либо готовые варианты ответа, либо написать свои. Вот, допустим, вопрос номер два: размер файлов и лимиты для загрузки. Рекомендуемый вариант - опция C: лимит для изображения 10 Мб и для видео 50 Мб. Так, давай, наверное, его и выберем. И, как можешь заметить, нейронка после нашего ответа сразу обновляет функциональные требования. Идём дальше.
Я знаю, какая это проблема: пытаться описать проект, как он должен работать, не обладая техническими знаниями. Происходит ситуация, в которой ты просто не знаешь, что ты не знаешь. Для этого существует опциональная команда Spec Kit Checklist, которая создаёт список из пунктов для самопроверки качества, полноты и ясности требований. И как это работает? После ввода команды в качестве аргумента мы должны указать тот модуль или свой вопрос, по которому мы хотим составить чек-лист. Допустим, UX. UX, или User Experience, - это опыт пользователя, то есть то, насколько наш проект будет удобен конечному потребителю. И вот он наш чек-лист по UX. Давай посмотрим, что нейронка нам здесь написала. Валидация качества UX-требований для интерактивной карты мемов: "Определены ли требования для состояния пустой карты, когда нет мемов в указанной области?" То есть, да, ты действительно можешь пройтись по всем этим пунктам чек-листа и у себя в голове, ну, составить мнение о том, полные твои требования, полная ли твоя спецификация или нет, и в случае чего дополнить. При необходимости ты можешь попросить нейросеть сравнить твою текущую спецификацию с чек-листами, которые ты только что создал. Идём дальше.
Команда Spec Kit Plan. Она возьмёт твоё описание и разделит его на множество мелких и легко выполнимых задач. Ты можешь запустить её просто так, но разработчики рекомендуют здесь указывать именно технические детали реализации: на каком языке программирования ты хочешь это разработать, на каком фреймворке, указать дополнительные модули, интеграции и так далее. Опять же, если не разбираешься, можешь попросить это написать нейросеть или просто запустить команду без аргументов.
Давай введём Spec Kit Plan, и я укажу свои технические требования. Я хочу frontend на React TypeScript. А карту буду отображать с помощью библиотеки React Map GL. Backend у нас будет на Node.js и Express. Для базы данных буду использовать SQLite, опять же, потому что это у нас учебный проект. Отлично.
Помимо плана, нейронка нам создала файл с README, файл с описанием для быстрого старта нашего проекта, а продумала модель в базе данных и даже написала документацию, которую можно подгрузить в Swagger. Вот. Ну и непосредственно сам план. Давай посмотрим, а что он из себя представляет. Так, ну, здесь полностью, как можешь заметить, описывается стек технологий, который должен применяться. А где всё это будет храниться, наши изображения и видеоролики? Что тестирование не требуется, он также написал, платформа и так далее. Обрати внимание, полностью прописана структура проекта, ну, и какие-то дополнительные особенности. Отлично.
А нам осталось совсем немного, во-первых, разбить нашу огромную задачу на мелкие отдельные таски, которые друг за другом будет выполнять нейросеть. Для этого нам с тобой необходимо будет ввести команду Spec Kit Tasks без аргументов, просто жму на кнопочку Enter. Так, по всей видимости, задачи у нас тоже готовы. Давай посмотрим, а какие задачки нам расписала нейронка. Так, она разбила нам всё по фазам, то есть по этапам. И всего у нас будет пять фаз, как я понимаю. Разработчики GitHub Spec Kit говорили о том, что они немного переработали генерацию тасок, и теперь нейросеть, по идее, должна создавать такую последовательность задач, чтобы у нас как можно быстрее сформировался MVP, который мы можем запустить и протестировать.
После того, как таски написаны, вводим команду Spec Kit Analyze. Как и Clarify, она тоже является опциональной, и, в принципе, её можно пропустить. Но я бы тебе советовал всё-таки ей пользоваться. Она анализирует файлы, ищет всякие недочёты, конфликты, логические и технические дыры. И после того, как она отработает, ты можешь прямо в чате попросить нейросеть либо исправить ошибки, либо пропустить и приступить к реализации. В моём случае команда оказалась очень полезная, потому что, как можешь заметить, она обнаружила критическую и несколько серьёзных несоответствий со спецификациями, нашими задачами и так далее. Давай слишком сильно закапываться не будем. Я напишу: "Исправь critical и high".
И для реализации тебе понадобится последняя команда, которая называется Spec Kit Implement. Она берёт все файлы, которые были тобой созданы, и, следуя правилам и рамкам, которые ты установил, начинает выполнять задачи по порядку. Ты можешь написать её и без аргументов отправить в чат. И тогда нейросеть попытается выполнить все задачи, ну, в рамках оставшегося у неё, условно, контекста. В какой-то момент она может остановиться. Либо ты можешь указать, допустим, какие фазы, то есть этапы, или какие конкретные задачи ты хочешь, чтобы она выполнила. Допустим: "Выполни только первые две фазы", и жмём Enter.
Я сейчас разрабатываю достаточно простой проект с фронтендом и бэкендом. Проект у нас учебный, и чтобы не растягивать хронометраж, я не показываю детали проектирования API, работы с базой данных. Мы всё это дали на откуп нейросети. Но если ты хочешь правильно разрабатывать как обычные сайты, так и полноценные сервисы, продукты, которые можно выпускать и продавать, записывайся на мой самый полный курс по вайб-кодингу. Он подойдёт даже новичку, потому что мы идём от простого к сложному. Мы сначала изучаем базу вайб-кодинга и верстаем простой лендинг. Затем я даю и разжёвываю прямо самую необходимую теорию по бэкенду, проектированию API и фронтенду. В итоге мы с тобой шаг за шагом разработаем аналог веб-приложения, собравшего в этом году более 35 млн долларов инвестиций. Трекер питания с интеграцией нейросетей для распознавания калорий блюд по фото, с админкой, рекуррентными платежами и всем функционалом, который может понадобиться в современном веб-приложении. Ты изучишь всё, начиная с того, как генерировать красивый дизайн, заканчивая безопасностью и деплоем на сервер. При желании ты можешь под руководством куратора создать собственный проект вместо курсовой работы. Переходи на лендинг по ссылке в описании, изучай программу. Там же висят отзывы учеников из приватного чата студентов.
Я знаю, что ты любишь выгодные предложения, поэтому в качестве благодарности за то, что ты досмотрел до этого момента, я прямо сейчас сгенерирую специальный промокод GitHub. Переходи по ссылке в описании, вводи его при оплате и получай скидку в целых 40%. Это почти половина.
Так, у нас при запуске, в принципе, возникла всего лишь одна ошибка с CORS, но она была очень быстренько исправлена. И, в принципе, я зашёл на нашу карту мемов, уже протестировал. Ну вот, при обновлении страницы у нас запрашивается с бэкенда информация о точках. Они здесь имеют название, описание, ещё какие-то параметры: ширина, долгота, то есть местонахождение маркера. Ну и непосредственно путь, локальный путь к данному медиафайлу картинки. Я уже добавил парочку маркеров. Вроде как бы всё работает. Давай покажу и тебе.
Так, хочу добавить где-нибудь в Санкт-Петербург мем про котлетки с пюрешкой. Легендарная песня от Enjoykin. Не особо известно, где была снята конкретно вот эта сцена с котлетками и пюрешкой. Ну, допустим, где-нибудь в пределах Санкт-Петербурга. Ну вот, я нажимаю на любое место. Мне предлагается ввести название. Так, и в качестве файла давай загружу только что скачанную песню из Ютуба. Добавить мем.
Так, я вижу, что ушёл запрос на сервер. И после этого мы получили обновление всех наших точек. Давай посмотрим. Вот он наш маркер. Он добавился у нас на какую-то улицу Петербурга. И действительно, я могу теперь запустить видеоролик, который я загрузил. У нас отображается название, отображается описание, и я могу даже поставить сюда лайк. При этом у нас улетает запрос на сервер.
Хорошо, я показал тебе, как с нуля стартовать проект с GitHub Spec Kit. Но как поступить, если ты хочешь внедрить его в уже существующий проект? Всё на самом деле очень просто. Во-первых, тебе необходимо инициировать твой проект непосредственно в его директории. Я скопирую ту же самую ссылку, которую использовал в самый первый раз в этом видеоролике. Ну, только вместо "project name" впишу либо флаг "here", либо точку. И это даст понять Spec Kit'у, что ему необходимо инициализироваться в текущей директории. Также, если вдруг опять же у тебя что-то не работает, ты можешь скачать файлы из раздела релизов и просто закинуть их в корень твоего проекта.
Итак, я ввёл команду. В принципе, с этим интерфейсом ты уже знаком. У нас снова спрашивают, каким иагентом мы пользуемся. Я выбираю курсор, выбираю SH. В общем, всё, как я тебе показывал в начале видео. После этого мы снова идём по порядку. Сперва команда Spec Kit Constitution. Мы с тобой создаём файл с правилами и рамками, которые не подлежат обсуждению. А тебе или нейросети необходимо проанализировать проект и указать все важные детали, которые имеют значение, которым должна следовать модель. У себя в Telegram-канале я ранее поделился промптом, который заставляет модель проанализировать проект и максимально подробно и детально описать его нюансы. Я буду использовать именно его. Я уже подгрузил его в свой чат, и ссылку на данный файлик я оставлю в описании. Изначально он фронтендовый, но ты можешь попросить нейросеть сгенерировать похожий промпт для анализа кодовой базы.
Так, нейронка создала нам файлик Project.md со всей информацией о проекте, максимально подробно, начиная со стека, заканчивая прямо самыми мелкими деталями, с информацией о том, как у нас происходит работа с всякими запросами. В принципе, я и этот файл мог бы использовать в качестве такого основного файлика, который рассказывает о всём проекте, который содержит всю его информацию, какие-то незыблемые правила, но GitHub Spec Kit хочет, чтобы файл constitution был у него в определённом формате, с определённым шаблоном. Поэтому кто я такой, чтобы это всё игнорировать? Поэтому я просто скормлю сгенерированный файлик со всей информацией о проекте команде Spec Kit Constitution.
После того, как файл constitution был создан, мы можем переходить к обычной работе с GitHub Spec Kit, который я тебе показывал ранее, а именно: создание спецификации для новой фичи, уточнение информации, планирование, разбиение на отдельные задачи, анализ на конфликты, анализ на недоработки всякие и, наконец, реализация задач.
Казалось бы, а что здесь сложного? Просто нужно запомнить порядок вызова команд и вперёд. Но, к сожалению, у GitHub Spec Kit всё ещё очень много проблем, о которых ты просто обязан знать. Я в этом видео просто быстро обозначу сухие факты, а более подробно с моим мнением, что я об этом думаю, ты можешь почитать в нашем Telegram-канале по ссылке в описании. Помимо этого, ты там найдёшь анонсы видео. Периодически я сливаю классные промпты и делюсь своим опытом разработки. Также заходи в наш чат сообщества, там уже более 500 человек. Общение идёт очень активно, есть комнаты по разным инструментам. А если тебе необходимо разработать какой-либо проект и ты ищешь исполнителя, там же ты можешь оставить свой заказ.
Итак, перейдём к проблемам, о которых ты должен знать. Я выделю три основные. И первая проблема, и самая главная: GitHub Spec Kit создаёт достаточно большое количество файлов, и все они очень объёмные. Мы переходим от ситуации, когда мы вручную детализировали свои промпты и затем исправляли ошибки, к ситуации, когда продумана каждая мелочь, но постоянное использование Spec Kit'а приводит к съеданию огромного количества токенов. Хотя тот факт, что GitHub Spec Kit создаёт подробнейший контекст для модели, сам по себе очень крут. И в будущем, когда LLM-ки прокачаются, возможно, это станет одним из стандартов вайб-кодинга. Но сейчас мы живём в мире, когда чем больше мы общаемся с нейросетью, тем больше она забывает. И забывать она начинает достаточно быстро, порой даже не доходя до своего лимита контекстного окна.
И это вторая проблема. И по идее она должна решаться тем, что модель записывает все важные моменты, все изменения в Markdown-файлы и якобы имеет к ним доступ. Но в реальности проблема заполнения контекстного окна и галлюцинаций всё ещё существует. А сохранение важной информации в текстовые файлы работает, к сожалению, не так эффективно. Поэтому я бы советовал каждую команду Spec Kit Implement запускать в новой сессии и явно указывать, какие задачи нейросети требуется разработать. Ну и всё-таки непонятно, как при всём этом использовать Spec Kit в больших проектах с тысячами файлов.
Опустим проблему с токенами. Разработчик GitHub Spec Kit, Дн Делимарский, говорит о том, что спецификации должны быть, цитата, "единственным источником правды для нейросети". Если мы сначала разрабатывали модуль авторизации для нашего приложения по одной спецификации, а затем в процессе решения других задач мы этот модуль затронули, как-то изменили его работу, по-хорошему, нам необходимо обновить его спецификацию и описать внесённые изменения. Если следовать этому принципу, то, интегрируя GitHub Spec Kit в большой Legacy-проект, тебе для комфортной работы сперва требуется создать спецификации для каждого уже существующего модуля. Может, это не так, может, я что-то неправильно понял, но в любом случае я буду продолжать разбираться. Напиши в комментарии, что думаешь по этому поводу.
Я считаю, что, несмотря на озвученные ранее проблемы, GitHub Spec Kit всё ещё является отличным инструментом. И, по крайней мере, проекты небольшого уровня он помогает делать, создавать очень качественными и продуманными. Если нравится мой контент, ставь лайк и подписывайся на канал. Видео выходит дважды в неделю, и у меня есть ещё много, о чём тебе рассказать. Бери и делай.