The post has been translated automatically. Original language: Russian
In many companies, development departments have already switched to neural networks. We were also swallowed up by this wave. We write large chunks of code with our hands less often now. Basically, we design, conduct reviews, fix bugs, and, if necessary, add functions to the points.
The same neural network patterns began to surface all the time on the review. They really annoyed me.
You ask me to fix one thing, and the neural network improves five more at the same time. Or he fixes the right part, but breaks another one. She wrote the code quickly, but the task returns to work again.
I went to look for ready-made skills and agent kits. I wanted to record repeated comments with a review once and connect them to the project, so as not to explain the same thing to the models in each task. I did not find a suitable set. As a result, I built the WebDev Agent Kit.
Why was I looking for a ready-made agent kit?
I was looking for rules of behavior for the agent, for example, for the task of fixing bugs. The prompt sounded like this: "Find such and such a bug, fix it, but apart from that, do not refactor anything. If you need to change related modules, first explain why and ask the user. Do not install additional libraries without the user's permission. After work, write down which checks you actually ran."
I'm tired of repeating the comments in every prompt. I wanted to describe the task and architecture more during my work, rather than cleaning up the mess behind the agent.
There is too much garbage in the finished kits
During my search, I came across repositories where they dragged library documentation, several frameworks, dependencies, and ready-made instructions for all occasions. Most of this had nothing to do with our projects.
We have a fairly lightweight frontend. We usually use React or Next.js, a library, or a framework for storage and CSS Modules. We connect the remaining dependencies to each project as needed.
One project needs a payment system. The other one has a Markdown editor. Somewhere we connect ready-made plugins or frameworks for working with agents. That's why I didn't want to drag it all into the general set.
Ready-made kits brought someone else's stack with them. I wanted the agent to look at the current project first. Which libraries are already in place, how the files are laid out, and how the checks are triggered. And only after that I worked with what I found.
At some point, it became easier to assemble such a set yourself than to keep looking.
I've compiled the rules from the review issues
First, I made the repetitive remarks into general rules. Then I divided them by type of work. Bug fixing, refactoring, review, screenshot layout, and visual verification require different behaviors from the agent.
There are currently 19 skills in the WebDev Agent Kit. I've divided them by task type so that, for example, if there's a local bug, the agent doesn't read the instructions for developing a feature or a major redesign.
I also divided the tasks by weight. You can find a place in the code and not change anything without a plan. The local edit remains local. But for architecture, features, or a major redesign, you already need a plan, because it's easy to lose some of the requirements or spread the changes throughout the project.
I also added a project adaptation skill. Before working, the agent analyzes the repository, determines the stack, and creates an updatable cache with commands, structure, and available tools. The rest of the skills rely on this cache and adapt to a specific project. This way, the agent hallucinates less and writes less neuroslope.
I have banned the most annoying behavior with a separate rule. The skill restricts the agent to the user's task. He does exactly what he's asked to do. If I ask to modify a button on one page, the agent changes the button only on that page. By doing this, I saved myself from neuroslope, unnecessary garbage in the project, endless rewriting of the README and edits where the agent was not asked to change anything.
Then I had to check the rules.
At first, the WebDev Agent Kit was a set of instructions. As one rule grew, another began to catch on, and packages for different clients could disperse. The kit is currently being built for Codex, Claude Code, and Cursor, but they share the same logic.
I've added schemas, validators, and eval scripts. Schemas define the structure of files with rules and tests. Validators check required fields, references, and the consistency of skills with packages for Codex, Claude Code, and Cursor. In the eval scripts, I recorded specific requests, the chosen route, and mandatory and prohibited actions.
For example, a small edit does not suddenly turn into a big plan with a check of the entire repository. Or if the browser is unavailable, the agent does not write that it has viewed the page. If the user has asked for a review, the agent does not refactor the found jambs, but conducts a review and writes a report.
There are currently 86 such scenarios in the repository. They catch and correct situations when a new rule breaks an old one or the instructions for Codex, Claude Code and Cursor begin to diverge.
What happened
The WebDev Agent Kit grew out of our stack and our review issues. I do not declare support for all frontend frameworks.
As a result, I have put together a set of rules that helps agents adapt to different projects. There is a separate skill inside for creating new skills and customizing the set for a specific project.
Pick it up, test it, and write feedback. I hope this will be useful to someone.
Во многих компаниях отделы разработки уже перешли на нейронки. Нас тоже поглотила эта волна. Большие куски кода руками мы теперь пишем реже. В основном проектируем, проводим ревью, исправляем баги, а если надо, точечно дописываем функции.
На ревью стали постоянно всплывать одни и те же нейросетевые паттерны. Они меня супер раздражали.
Просишь исправить одну вещь, а нейронка заодно улучшает ещё пять. Или чинит нужную часть, но ломает другую. Код она написала быстро, только задача снова возвращается в работу.
Я пошёл искать готовые skills и agent kits. Хотел один раз записать повторяющиеся замечания с ревью и подключать их к проекту, чтобы не объяснять модели в каждой задаче одно и то же. Подходящего набора не нашёл. В итоге собрал WebDev Agent Kit.
Зачем я искал готовый agent kit
Я искал правила поведения для агента, например для задачи по фиксу багов. Промпт звучал так: «Найди такой-то баг, исправь его, но кроме этого ничего не рефактори. Если нужно изменить связанные модули, сначала объясни зачем и спроси у пользователя. Дополнительные библиотеки не устанавливай без разрешения пользователя. После работы напиши, какие проверки действительно запускал».
Повторять замечания в каждом промпте мне надоело. Хотелось во время работы больше описывать саму задачу и архитектуру, а не убирать помойку за агентом.
В готовых наборах слишком много мусора
Во время поиска мне попадались репозитории, куда натащили документацию по библиотекам, несколько фреймворков, зависимости и готовые инструкции на все случаи жизни. Большая часть этого к нашим проектам отношения не имела.
У нас довольно легковесный фронтенд. Обычно используем React или Next.js, библиотеку либо фреймворк для хранилища и CSS Modules. Остальные зависимости подключаем по мере необходимости к каждому проекту.
В одном проекте нужна платёжная система. В другом есть Markdown-редактор. Где-то подключаем готовые плагины или фреймворки для работы с агентами. Поэтому я не хотел тащить всё это в общий набор.
Готовые наборы приносили с собой чужой стек. Мне же хотелось, чтобы агент сначала посмотрел на текущий проект. Какие библиотеки уже стоят, как разложены файлы, чем запускаются проверки. И только после этого работал с тем, что нашёл.
В какой-то момент стало проще собрать такой набор самому, чем продолжать искать.
Собрал правила из проблем на ревью
Сначала я вынес повторяющиеся замечания в общие правила. Потом разделил их по типам работы. Исправление бага, рефакторинг, ревью, вёрстка по скриншоту и визуальная проверка требуют от агента разного поведения.
Сейчас в WebDev Agent Kit 19 навыков. Я разделил их по типам задач, чтобы, например, при локальном баге агент не читал инструкции для разработки фичи или большого редизайна.
Задачи я тоже разделил по весу. Найти место в коде и ничего не менять можно без плана. Локальная правка остаётся локальной. А вот для архитектуры, фич или большого редизайна уже нужен план, потому что там легко потерять часть требований или разнести изменения по всему проекту.
Ещё я добавил навык адаптации к проекту. Перед работой агент анализирует репозиторий, определяет стек и создаёт обновляемый кэш с командами, структурой и доступными инструментами. Остальные навыки опираются на этот кэш и адаптируются под конкретный проект. Так агент меньше галлюцинирует и пишет меньше нейрослопа.
Самое раздражающее поведение я запретил отдельным правилом. Навык ограничивает агента задачей пользователя. Он делает строго то, о чём его попросили. Если я прошу доработать кнопку на одной странице, агент меняет кнопку только на этой странице. Этим я избавил себя от нейрослопа, лишнего мусора в проекте, бесконечного переписывания README и правок там, где агента ничего менять не просили.
Потом правила пришлось проверять
Сначала WebDev Agent Kit был набором инструкций. По мере роста одно правило начинало цеплять другое, а пакеты для разных клиентов могли разъехаться. Сейчас kit собирается для Codex, Claude Code и Cursor, но общая логика у них одна.
Я добавил схемы, валидаторы и eval-сценарии. Схемы задают структуру файлов с правилами и тестами. Валидаторы проверяют обязательные поля, ссылки и согласованность навыков с пакетами для Codex, Claude Code и Cursor. В eval-сценариях я записал конкретные запросы, выбранный маршрут, обязательные и запрещённые действия.
Например, маленькая правка не превращается внезапно в большой план с проверкой всего репозитория. Или если браузер недоступен, агент не пишет, что посмотрел страницу. Если пользователь попросил провести ревью, агент не рефакторит найденные косяки, а проводит ревью и пишет отчёт.
Сейчас в репозитории 86 таких сценариев. Они ловят и исправляют ситуации, когда новое правило ломает старое или инструкции для Codex, Claude Code и Cursor начинают расходиться.
Что получилось
WebDev Agent Kit вырос из нашего стека и наших проблем на ревью. Поддержку всех фронтенд-фреймворков я не заявляю.
В итоге я собрал набор правил, который помогает агентам адаптироваться к разным проектам. Внутри есть отдельный навык для создания новых навыков и кастомизации набора под конкретный проект.
Забирайте, тестируйте, пишите фидбэк. Надеюсь, это кому-нибудь будет полезно.
Share
