Мой фреймворк для агентной разработки с Claude Code

Год назад я проникся идеей вайбкодинга и начал разбираться, как бы организовать процесс так, чтобы на выходе получалось что-то полезное.

Сначала работал в Cursor и пытался ваншотом сделать какие-то сервисы для своих нужд. Получалось ужасно, не работало ровным счетом ничего.

Тогда я решил, что надо максимально подробно описать, как должен работать сервис, как он должен выглядеть, что должно происходить на нажатии на каждую кнопку. Написал док на 3 страницы, нарисовал простенький интерфейс в Фигме, отдал агенту — вроде что-то сделал, но с невероятным количеством багов.

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

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

Так я сделал свой первый проект — расширение для браузера, которое ищет битые ссылки на сайтах. Спустя 9 месяцев у него уже 2500 пользователей (половина из Индии), 16 хороших отзывов. Прикольно, но мало, надо что-то еще.

За полгода я сделал десяток небольших проектов. Некоторые для себя (например, автоматический репост из Телеграма в блог на сайте и агент-ассистент, который управляет моим календарем), некоторые для команды (агент с RAG, который отвечает на вопросы по базе знаний), парочку даже смог монетизировать (у одного бота сейчас 33к пользователей и около $1000 ежемесячной выручки).

Все это делал в Claude Code. И с каждым следующим проектом я чуть лучше понимал, как вообще устроена агентная разработка, как надо общаться с агентом, чтобы он поменьше тупил и галлюцинировал. Делал новые скиллы, докручивал старые, добавлял агентов-ревьюверов, которые ищут баги и уязвимости.

В итоге собрал свой фреймворк агентной разработки и выложил его на Гитхаб. Это набор скиллов и команд для Claude Code, которые учат его уму-разуму.

За 2 месяца у него набралось 100 звезд, я получил в личку несколько хороших отзывов, что с ним действительно проще и быстрее создавать небольшие продукты. Хочу поделиться фреймворком и с вами тоже.

В чем суть фреймворка

Я не разработчик. Я учился кодить в школе и универе, но ни разу не писал код в настоящих проектах. Жизнь завела меня сначала в маркетинг, а потом в менеджмент.

Фреймворк заточен под таких же людей, как я. С техническим складом ума, но без реального опыта в настоящем программировании. Наш разработчик — это Claude Code. Он же devops, он же специалист по безопасности, он же технический писатель.

Человеку отводится роль продакта — придумывать, что делать, говорить, как оно должно себя вести в разных сценариях и edge cases, ставить задачи, понимать потребности пользователей. Ну и тестировать все это в конце, чтобы убедиться, что все работает так, как задумано.

Я подробно расписал схему работы на Гитхабе, но продублирую и здесь.

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

User spec

Работа начинается с user-spec — это документ, где понятным человеческим языком расписано, что мы делаем, зачем, как оно должно работать. Таким языком, который могу понять я, со своим очень поверхностным знанием о разработке.

Я описываю агенту, что хочу сделать, он запускает режим интервью и задает мне несколько десятков вопросов:

— А если юзер сделает это, что должно произойти?

— А если API не будет отвечать, что тогда?

— Вот есть 2 варианта это сделать, этот проще, этот надежнее, какой хочешь?

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

Tech spec

Когда user-spec готов, я прошу агента написать на его основе tech-spec — в нем мы пишем, что конкретно будем делать, какие функции писать, какие файлы менять, как все это тестировать.

Агент читает user-spec, изучает документацию проекта и код, все это расписывает, проходит несколько этапов ревью и правок. Чем больше фича, тем больше получается документ. Но в среднем это 300-400 строк.

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

Например, если в задаче надо написать промпт для LLM, вызываемой по API, то задачу будет делать агент со скиллом prompt-master. Если надо кодить — будет делать code-writer и так далее.

Сами задачи тоже проверяются ревьюверами — на адекватность решения, уязвимости, соответствие user-spec и tech-spec.

На этом этапе я уже ничего не проверяю сам. Я согласовал user-spec, дальше вся ответственность ложится на плечи агентов.

Сама разработка

Когда задачи готовы, можно запускать агента кодить.

Вся работа идет по TDD — сначала пишем тесты, только потом код. Если делать наоборот, агент начинает подгонять тесты под уже сделанную работу, в том числе под ошибки.

Есть два режима — do-task и do-feature.

В do-task агент берет одну задачу, загружает указанные в ней скиллы, делает, проверяет сам себя по критериям приемки, прогоняет тесты, потом вызывает проверяльщиков. Обычно это ревьювер кода и секьюрити аудит. Когда все готово, я закрываю чат, открываю новый и пускаю нового агента делать следующую задачу.

do-feature — это ваншот режим. В феврале в Claude Code появились Agent Team — агент-тимлид создает кучу агентов-тиммейтов и координирует их работу. Вот это оно.

Тимлид смотрит, какие задачи из спека еще не выполнены, запускает на каждую отдельного агента-разработчика. Когда они отчитались, что все сделали, запускает агентов-ревьюверов. В конце запускает QA всей фичи.

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

Документация проекта

Чтобы агенты не тупили после создания нового чата, я веду (ну вернее они ведут) project knowledge по каждому проекту. Там написано, что мы делаем, зачем, какой у нас техстек, какая архитектура проекта, как его деплоить и так далее.

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

Если надо сделать что-то быстрое, без спеков и интервью, я просто открываю новый чат, прошу агента изучить документацию — и после этого можно с ним нормально общаться.

Скиллы по созданию скиллов

Все эти скиллы и агентов я делаю с помощью двух скиллов — skill-master и skill-tester.

Первый — это инструкция, как писать нормальные рабочие скиллы и субагентов-ревьюверов к ним.

Второй берет готовый скилл, придумывает для него тестовые задачи, прогоняет по ним агента и фиксирует, как он справляется. Фидбек я отдаю skill-master — и он правит инструкции.

А потом уже и сам руками тестирую на настоящих задачах.

Как установить

Самый простой способ — дать ссылку на Гитхаб своему Claude Code и попросить установить. Обычно все так и делают.

Но если хотите руками — просто скопируйте все в папку ~/.claude. Если у вас нет скиллов и субагентов с такими же названиями, как у меня, все нормально скопируется. Если есть, то придется что-то переименовать.

Спасибо, что прочитали статью, надеюсь, мои наработки вам пригодятся. Мне будет приятно, если этими выстраданными за полгода скиллами будут пользоваться другие люди.