Как я прошёл путь от «сам быстрее напишу» до своего фреймворка для агентной разработки

Около полугода назад я перешёл с ChatGPT на Claude Code с моделями от Anthropic, и моя жизнь изменилась. Вообще, это была не первая моя попытка решиться на такие серьёзные перемены. Раньше я пробовал пользоваться Qwen Code с китайскими LLM, но довольно быстро заканчивал со словами: «Я сам быстрее сделаю, чем ему объясню». Спойлер: проблема во многом была не в инструменте, а во мне.

Меня зовут Матвей Коноплёв. И до начала использования кодинговых агентов, и сейчас я остаюсь обычным работягой: пишу код, девопшу, немного ИИ-инженерю. На данный момент работаю Senior Python-разработчиком в одном из крупнейших банков РФ, делаю поиск и ИИ-ассистентов. Люблю разбираться в чём-то новом, а потом с умным видом кивать головой, когда речь заходит об этом самом «чём-то».

Именно поэтому полгода назад, когда уже из каждого утюга рассказывали про Claude Code, я не мог пройти мимо. Относился я к нему скептически, но пойти потыкать был обязан. Тогда в одном из гайдов на YouTube я услышал про Superpowers — сам подход показался мне как минимум необычным. До этого моё взаимодействие с кодинговыми агентами ничем не отличалось от обычной переписки с LLM в чате. Пишу задачу — получаю код. Что-то не так — прошу переделать. Снова не то — прошу ещё раз. В итоге закрываю агента и делаю задачу руками.

Superpowers же открывал совершенно другой подход — через написание неких спек и планов. Звучало многообещающе. На деле же, когда я первый раз попытался сделать задачу с Superpowers, я ещё даже ничего не понял, а он уже пошёл создавать какие-то ветки и коммитить. «Ну всё, следующим шагом, видимо, в прод покатит», — подумал я. «Классная» штука. Но сама концепция действительно казалась свежей и интригующей. Когда я немного разобрался, стало понятно, что подобных инструментов масса, но все они строятся на одних и тех же принципах.

И, как уважающий себя программист, я решил навелосипедить свой фреймворк: взял Superpowers, перевёл на русский, выкинул всё ненужное и — вуаля — получил довольно простой набор скиллов, который развиваю уже несколько месяцев, параллельно решая с его помощью свои рабочие задачи.

Ниже разберём, почему Superpowers, всякие spec-что-то-там и другие подобные инструменты могут быть полезны работягам вроде меня — и как они, включая мой самописный инструмент, решают главные боли при работе с ИИ. Моя цель — не продать вам уникальную таблетку, а показать, как и почему всё это работает. А уж какой фреймворк вы для этого выберете или напишете сами — дело десятое.

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

В чем проблемы разработки с кодинговыми агентами (и как это чинить)

Context Rot: почему наш агент тихо тупеет

Ни для кого не секрет, что у LLM нет встроенной памяти, а в контекст каждого запроса от кодингового агента летит вообще всё: ваши прошлые вопросы, предыдущие ответы модели, системные инструкции, прочитанные файлы и так далее.

Как и у человека, у языковой модели есть то, что инженеры Anthropic называют бюджетом внимания — attention budget. Чтобы дописать строчку кода, нам с вами нужно понимать контекст: функцию, класс или модуль, куда мы её добавляем. Точно так же и нейросети: для генерации каждого нового токена ей необходимо оценить его связь со всем массивом переданных данных. Несложно понять, что с разрастанием контекста объём такой работы увеличивается лавинообразно. В результате фокус модели просто «размазывается» по тексту, что приводит к Context Rot — нелинейной деградации качества ответов.

LLM не выдаст нам ошибку о превышении лимита — она просто начнёт тихо «глупеть»: забывать факты, путаться в логике и галлюцинировать. Практика и исследования показывают, что оптимальная работа, например у Claude Opus, сохраняется только тогда, когда контекстное окно заполнено менее чем на 50% для версий на 200K токенов или менее чем на 15% для версий на 1M токенов.

Поэтому при написании кода с кодинговыми агентами главный вопрос звучит не «вместится ли весь код в окно», а «что туда положить, чтобы внимание ИИ не размазалось».

На этот вопрос отвечает новая область — Context Engineering. Это стратегии отбора и поддержания оптимального набора токенов при работе с LLM. Если Prompt Engineering был про подбор слов в отдельной инструкции, то Context Engineering — про управление всем потоком данных: системными промптами, историей, файлами, результатами скриптов. В контекст нужно отправлять не всё, что потенциально может пригодиться, а только минимально достаточный набор информации — то, без чего агент точно не справится. Именно строгий контроль бюджета внимания позволяет агенту писать качественный код и не тонуть в галлюцинациях.

День сурка: каждая новая сессия как чистый лист

Если Context Rot — это проблема деградации внутри одной сессии, то между диалогами возникает другая: LLM не помнит нас совсем. Без фиксации знаний нам придётся каждый раз заново объяснять агенту архитектуру, конвенции и подводные камни проекта. Разработка превращается в бесконечное повторение одного и того же — и борьбу с одними и теми же ошибками.

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

• Файл CLAUDE.md — отвечает за глобальный контекст — «ДНК проекта». Сюда выносится базовый каркас, который нужен агенту при каждом запросе: стек, команды запуска, общие линтеры и верхнеуровневая архитектура, например:

Search - сервис полнотекстового и гибридного поиска для виртуального ассистента.- Python 3.13 - основной язык программирования- Поисковые запросы приходят через REST API- Под капотом выполняется гибридный поиск в OpenSearch, объединяющий BM25 и векторный поиск

• Правила / Rules — изолируют точечные инструкции — например, требования к тест-кейсам. Агент активирует эти файлы только тогда, когда реально работает с тестами. Это задаёт нужные рамки, но не раздувает контекст лишней информацией, например:

---paths:  - "tests/**/*.py"---- Паттерн AAA: Arrange (подготовка) → Act (действие) → Assert (проверка)- Для написания тестов используется pytest- Использовать faker для генерации тестовых данных

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

• Артефакты: спеки и планы — служат «сохранениями» между сессиями. Передав такой файл через @ в новый чат, мы мгновенно погружаем агента в контекст: он понимает текущий статус задачи и следующие шаги без ручного пересказа с нашей стороны.

Инициатива наказуема: почему агента нужно держать на поводке

Даже если мы знаем про Context Rot и научили агента помнить проект между сессиями, остаётся третья проблема: агент по умолчанию хочет делать.

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

Эту проблему частично закрывает Plan Mode — режим планирования в Claude Code (уверен, что в других кодинговых агентах он тоже есть). Штука хорошая, всем рекомендую попробовать. По сути, в этом режиме агент анализирует кодовую базу и пишет пошаговый план прямо в чате, а не сразу бросается решать задачу. Мы корректируем этот план и только потом разрешаем агенту писать код.

Это отлично работает для задач средней сложности, но план живёт только в текущей сессии. Для крупных задач и длительной работы нужен фреймворк с поэтапным процессом и сохранением состояния. Таких фреймворков много, но все они так или иначе вдохновлены spec-driven-подходом. В отличие от быстрого плана в чате, это строгий процесс, основанный на трёх этапах: «Спецификация → План → Реализация».

1. Спецификация / Spec. Документ спецификации фиксирует, что нужно сделать, выявляет зависимости и декомпозирует фичу на истории. Это задаёт жёсткие рамки и защищает от галлюцинаций ИИ.

2. Планирование / Plan. На основе спеки формируется отдельный документ-план — детальное описание того, как именно всё реализовать. Истории разбиваются на атомарные задачи с жёстко ограниченной ответственностью.

3. Реализация / Execution. Только после утверждения плана агент начинает писать код небольшими кусками.

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

Иллюзия скорости: почему LLM нельзя доверять без покрытия тестами

Агент пишет код очень уверенно: не сомневается, не оговаривается и не предупреждает о рисках. Но эта уверенность обманчива. Сгенерированный код часто содержит неочевидные баги.

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

Одно из решений этой проблемы — TDD, или Test-Driven Development. В связке со spec-driven-подходом он работает очень хорошо.

1. Сначала пишутся тесты по спеке. Поскольку требования и граничные случаи уже зафиксированы в спецификации, агент пишет осмысленные и точные тесты, а не формальные заглушки для галочки.

2. Затем пишется реализация. Агент генерирует код, который должен пройти эти проверки. Классический «красно-зелёный» цикл не даёт ИИ уйти в сторону: если тест падает, ошибка видна сразу, а не через неделю.

3. Ведётся строгий контроль. Агенту категорически нельзя разрешать говорить «готово» без реального запуска тестов и демонстрации успешного вывода.

Всё зелёное, но код — каша: почему LLM всё равно нужно ревьюить

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

LLM имеет свойство усложнять: плодить слои, переусердствовать с архитектурой, решать задачу не самым прямым путём. Мы считаем обязательным ревью для кода, написанного человеком. Для нейросети, которая тоже умеет уверенно ошибаться, этот этап нужен не меньше.

Я слышал мнение, что теперь код пишут кодинговые агенты, поэтому code style и чистая архитектура больше не нужны. Мол, LLM всё равно, насколько ловко я следую SOLID. Но правда в том, что даже LLM будет намного проще понимать и дописывать мой код, если он сделан расширяемым, понятным и тестируемым.

Каждая строка, написанная агентом, должна быть отсмотрена человеком. Так мы остаёмся в курсе каждого изменения и не теряем контроль над тем, что попадает в репозиторий. Периодически стоит отдельно проходить по коду и упрощать его: убирать лишние абстракции, выпрямлять логику. Это, кстати, тоже можно делать при помощи LLM.

Собрал свой велосипед, чтобы не летать на чужих космолётах

Инструментов, решающих описанные проблемы, как я уже сказал, довольно много: Superpowers, gtd, Spec Kit и другие. Я попользовался многими из них, и, на мой взгляд, все они постепенно превращаются в перегруженные «космолёты». Они пытаются делать за нас слишком многое, из-за чего теряется контроль над процессом.

У меня же не было цели заставить агента работать, пока я сплю. Моя задача была прагматичнее: решать ежедневные рабочие таски быстро, без багов и техдолга, желательно не переплачивая и используя обычную Pro-подписку Anthropic с Claude Sonnet. Кстати, недавно Anthropic увеличила пятичасовые и недельные лимиты на токены, так что при грамотном использовании именно Pro-подписки мне вполне хватает.

К тому же индустриальных стандартов работы с ИИ пока нет, поэтому мы вольны не следовать чужим best practices и не заставлять себя изучать готовые инструменты. Тот же Superpowers оказался для меня слишком абстрактным, а Spec Kit — слишком сложным.

Поэтому я сделал то, что делает любой уважающий себя программист, когда ему не нравится существующий инструмент: собрал свой. Я взял за основу здравые идеи Superpowers — spec-driven подход и TDD, — выкинул весь лишний автопилот и получил простую структуру:

• CLAUDE.md — для глобального контекста;

• Rules — для локальных правил;

• Skills — для рутины.

Мой фреймворк Vibe-skills был написан на русском, чтобы мне было проще его докручивать. Когда активная фаза доработки закончится, будет иметь смысл перевести его на английский: при работе с языковыми моделями один и тот же текст на русском обычно «стоит» примерно в 2–3 раза дороже, чем на английском, то есть занимает больше токенов.

Я также не использую продвинутые техники сжигания токенов вроде Agent Teams в Claude Code, но мой минимум работает неплохо. И вас я тоже не призываю брать какой-то конкретный фреймворк. Главное — понять принципы и собрать инструмент под свои нужды. Хотя, конечно, вы можете попробовать и мой Vibe-skills: в README.md проекта есть подробное описание настройки.

А теперь давайте посмотрим, как моя машина промптов на практике борется с проблемами, о которых мы говорили выше.

Vibe-skills

Context Rot: режем контекст на части

Первое, что делает Vibe-skills, — не даёт задаче распухнуть до состояния «всё лежит в одном бесконечном чате». Вместо этого работа режется на этапы, а между этапами контекст очищается через /clear.

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

• Спеки — файлы вида docs/specs/YYYY-MM-DD-<тема>-design.md, которые появляются после этапа брейнсторминга;

• Планы — файлы вида docs/plans/YYYY-MM-DD-<тема>.md, которые получаются после этапа планирования.

Чтобы каждый раз не писать вручную промпт для новой сессии о том, что мы теперь будем делать, у меня есть скилл — next-stage-prompt. Он сам находит последнюю спеку или план и собирает готовый промпт со ссылкой через @. Я просто копирую его, вставляю в чистый чат и еду дальше.

Постоянный контекст я тоже стараюсь не раздувать. Файл CLAUDE.md содержит только стек, структуру проекта и подводные камни — всё, что должно быть всегда под рукой. А вот частные штуки — например, стиль тестов — я вынес в .claude/rules/example-test-style.md: он подгружается только тогда, когда агент реально пишет тесты, а не висит в контексте мёртвым грузом.

День сурка: внешняя память и спасение агента от амнезии

Тут нам снова приходят на помощь CLAUDE.md, .claude/rules/, спеки и планы. Чтобы агент не начинал жизнь с чистого листа, весь контекст проекта разнесён по правильным полочкам.

• Файл CLAUDE.md. Здесь лежит самое необходимое: на чём пишем, какая архитектура, как запускать проект, какие есть команды и на какие грабли я уже наступал. В моём фреймворке есть готовый шаблон CLAUDE.md: заполняешь его один раз под свой проект (можно попросить вашего агента), и дальше стандартные скиллы уже работают с твоей спецификой — переписывать ничего не нужно.

• Папка .claude/rules/. Это правила, на которые ссылаются скиллы. У меня там лежат три примера: example-code-style.md, example-test-style.md и example-commit-style.md. По сути, сюда можно добавлять любые правила: по API, конкретным архитектурным решениям — вообще по чему угодно. Главное — прописать ссылку в нужном скилле. Я специально не зашивал правила в сами скиллы, поэтому они остаются заменяемыми для разных проектов и гибко подстраиваются под их специфику.

• Артефакты в docs/specs/ и docs/plans/. Это уже память не про проект в целом, а про конкретную задачу. Описал задачу сегодня — спека никуда не делась. Через неделю открыл чат, продолжил работу — и не надо вспоминать: «А что мы там вообще решили?»

Конечно, стоит понимать, что любая подобная документация со временем начинает тухнуть. Поменял я стек, переименовал директорию — а в CLAUDE.md всё по-старому. Поэтому у меня есть отдельный скилл — update-claude-md. Я запускаю его в конце выполнения задачи: он сам проходит по коду, сравнивает его с CLAUDE.md и точечно правит то, что разъехалось. Без этого скилла файл с контекстом очень быстро превращается в красивую сказку про проект, которого уже нет.

Инициатива наказуема: руль для агента

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

• Шаг 1: brainstorming. Это первое, что запускается, когда я хочу что-то создать или поменять. Агент идёт по коду, смотрит, что у меня там есть, и начинает задавать вопросы. Потом он предлагает 2–3 подхода с компромиссами, показывает дизайн, и я его утверждаю. В конце получается спека в docs/specs/. Агент, конечно, очень хочет сорваться и сразу писать код, но скилл строго ему это запрещает.

• Шаг 2: writing-plans. Этот скилл берёт спеку и превращает её в подробный чеклист. Главный фокус тут вот в чём: план пишется так, будто исполнитель вообще ничего про проект не знает. Никаких «ну, ты понял, добавь тут обработку ошибок». Только: «в файле X, в методе Y, добавь try/except для такого-то Exception». Каждый шаг — это реальная работа. План пишется по принципам TDD: фича разбивается на маленькие кусочки, под которые сначала пишутся тесты, а уже потом — код реализации. На выходе получаем файл docs/plans/<...>.md.

• Шаг 3: executing-plans. Финальный этап. Агент сначала ещё раз критически смотрит на план: если ему что-то непонятно, он останавливается и спрашивает у нас, а не пытается угадать. Только после этого создаёт задачи и идёт по ним. Каждую отмечает как in_progress, выполняет, проверяет и ставит completed. Упёрся в блокер — останавливается и просит помощи. Кстати, план как правило настолько подробно описан, что этот шаг можно делать при помощи более дешевых или бесплатных моделей.

Сверху над всем этим красуется skill-orchestrator.

Он вызывается в начале каждого чата — это прописано в CLAUDE.md — и устанавливает одно бронебойное правило: если есть хотя бы 1% шанс, что какой-то скилл из фреймворка применим, агент обязан его вызвать. Без этого правила модель стабильно «забывает» посмотреть в карту скиллов и сваливается в привычное: «ща я быстро всё сам сделаю». Оркестратор — это страховка ровно от этого.

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

Иллюзия скорости: дрессируем ИИ через покрытие тестами

Для написания тестов в Vibe-skills используется TDD — Test-Driven Development. Каждая задача в плане раскладывается по строгой схеме:

• Пишем падающий тест при помощи скилла unit-test-writer;

• Запускаем его и убеждаемся, что он действительно падает;

• Пишем минимальный код, чтобы тест прошёл;

• Запускаем снова и убеждаемся, что тест прошёл.

Пока тест не зелёный, задача не считается сделанной.

Само написание тестов (вызов скилла unit-test-writer) можно вынести в отдельного субагента, тогда контекст основной сессии не будет перегружаться написанием тестов. Но в Vibe-skills я не стал это добавлять — ради сохранения простоты.

Большой плюс ещё и в том, что тесты пишутся не на пустом месте, а уже после спеки и плана. То есть агент знает требования и граничные случаи — и пишет осмысленные тесты, а не бесполезные заглушки формата «функция должна вернуть не null».

Дополняет этот процесс отдельный скилл — verification-before-completion. Он включается каждый раз, когда агент собирается сказать: «готово», «работает» или «исправлено».

Правило простое: если агент не запустил тесты, он не может говорить, что они проходят. Не «должно работать», не «выглядит ок», а только конкретный запуск с конкретным выводом консоли. LLM держат эту дисциплину не очень хорошо: их всё время тянет сказать «ну там всё нормально вроде». Поэтому этот этап вынесен в отдельный скилл: там лежит длинная таблица с типичными отмазками нейросети и строгими инструкциями, как агент должен реагировать на собственные попытки схалтурить. По сути, verification-before-completion нужен не для проверки кода, а для проверки честности агента: он заставляет модель доказать, что всё работает, а не просто красиво об этом рассказать.

Всё зелёное, но код — каша: почему LLM всё равно нужно ревьюить

Как я уже писал выше, тесты ловят ошибки, но не ловят плохой код. Может быть всё зелёное, а код при этом — каша с кучей слоёв ненужных абстракций. Поэтому во фреймворк добавлен отдельный скилл — code-review. Он не ревьюит всю кодовую базу целиком, а смотрит только последние изменения. Скилл идёт по нескольким конкретным темам:

• Безопасность;

• Качество кода и архитектура: строго опирается на файл .claude/rules/example-code-style.md;

• Качество тестов: проверяет по .claude/rules/example-test-style.md.

На выходе получается отчёт с приоритетами: красное — критично, жёлтое — стоит поправить, зелёное — мелочи. Отдельно есть блок «что сделано хорошо». Я пробегаюсь по отчёту и решаю, что нужно чинить, а что не критично. Тем не менее ревьюить написанный код своими глазами тоже можно нужно.

Ещё один важный скилл в арсенале — systematic-debugging. Он срабатывает на любую ошибку, упавший тест или странное поведение агента. Скилл не даёт ИИ с разбегу влезть в код с фиксом, а заставляет пройти четыре фазы: корневая причина → анализ паттернов → гипотеза → реализация.

Только после прохождения текущей фазы мы идём в следующую. Если три фикса подряд не помогли, агент говорит: «Стоп, мы идём не туда, садимся обсуждать архитектуру». Без этого скилла агент любит лечить симптомы: тест упал — обернул в try/except, ещё что-то упало — повесил ещё один try/except.

И последнее, о чём тут стоит сказать, — работа с Git. Я принципиально не пускаю агента в Git. У меня есть скилл commit-writer — он только генерирует текст коммита по правилам из файла .claude/rules/example-commit-style.md. И есть commit-and-changes-writer — он выдаёт тот же текст коммита плюс описание изменений для MR и план приёмочного тестирования.

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

Вместо итогов

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

Пробуйте внедрять ИИ в свои рабочие процессы, изучайте разные подходы и не бойтесь собирать свои «велосипеды». Темпы развития ИИ-инструментов сейчас очень высоки, но начать погружаться в них никогда не поздно.