Сегодня уже наверняка никто не станет спорить с тем, что писать код полностью руками — неэффективно. Но даже при разработке с помощью агентов есть оптимальные и не оптимальные пути работы с ними. В статье поговорим на тему того, какие вообще есть варианты агентской разработки и как можно повысить их эффективность.
Уровень 0: пишем ручками
Настоящий олдскул! Когда-то наши предки, своими собственными руками писали буквы, которые затем превращались в исходный код важной программы. Ой, а это было всего несколько лет назад…
Уровень 1: промптинг
Все уже привыкли общаться с агентами через окно чатика. Это касается и жизненной рутины, и разработки:
открыли чат
описали задачу
отправили агента в добрый путь
Для адептов черно-белого консольного месива приложу другой скрин, чтобы вы не терялись, о чем речь:
В небольших проектах или стартапах проблем с таким подходом обычно нет. Но если мы говорим про работу над большим продуктом с разными модулями, слоями и архитектурными особенностями, такие простые промпты начинают давать сбой. Например, у агента могут возникать вопросы:
где находится логика работы с товарами?
где лежат нужные контроллеры?
через какой слой здесь вообще принято работать: напрямую через сервисы, через репозитории или через какие-нибудь хелперы?
Уровень 2: контекстинг
Пока инструменты не умеют читать мысли — с нетерпением жду прорыв от Саши Панова и его Neiry. Поэтому чтобы агент лучше понимал, что именно нужно сделать, ему стоит добавлять немного контекста:
В этом примере выше мы указали директорию с нужным модулем (catalog) и сущность товара (product.php), что на порядок улучшит понимание нашего агента.
С помощью контекста мы:
Направляем агента в нужную нам сторону.
Экономим время агента на поиски.
Экономим токены агента на работу.
Но если задача затрагивает несколько модулей, требует изменений в архитектуре или имеет несколько возможных вариантов реализации, одних подсказок с контекстом недостаточно. ПОСЛЕ реализации мы всё равно неизбежно начинаем что-то исправлять, переделывать или уточнять. Логично было бы найти способ, когда мы можем узнать действия агента ещё ДО реализации.
Уровень 3: планирование
Чтобы не исправлять ошибки агента ПОСЛЕ реализации, можно переключиться в режим планирования (“plan mode” you know), в ходе обсуждения с агентом составить план и внести необходимые корректировки ДО реализации. Тогда после итогового утверждения агент получит план со всеми нужными инструкциями, ссылками и контекстом.
Тут нужно сделать небольшое лирическое отступление и объяснить что такое «режим планирования» и какие ещё режимы бывают. Если мы говорим про модель (Claude, GPT), то это непосредственно нейронка (LLM) со входом и выходом. А вот оболочка aka harness (Сursor, Codex) даёт нам различный инструментарий для удобного и эффективного взаимодействия с моделью.
Пример — основные режимы в Cursor:
agent — обычный агентский режим, в котором модель может писать, читать и вообще активно взаимодействовать с проектом;
ask — просто общаемся, модель работает в режиме readonly и не имеет прав на изменение файлов проекта;
plan — тот самый режим планирования. Очень похож на режим ask, в котором модель не может ничего писать, кроме плана — markdown файла с инструкциями агенту для реализации необходимой задачи.
Благодаря режимам ask -> plan -> build мы можем организовать очень эффективный процесс AI-разработки:
В режиме ask: обсудили проблему/задачу и в диалоге с агентом нашли решение.
В режиме plan: составили детальный план реализации и проверили его перед реализацией.
В режиме agent (этап build): реализовали поставленный план.
Это не всё, что умеет Cursor. У него есть другие фичи и режимы, которые с момента выхода статьи наверняка дополнились. Актуальная информация лежит в официальной документации: https://cursor.com/ru/docs
Буст 1: спецификации
Разработка с планированием выглядит как идеальный процесс разработки, и по моему опыту он действительно достаточно эффективен и хорошо себя показывает каждый день. Но порой возникают проблемы и в этом подходе:
Нужно регулярно поправлять план в одних и тех же местах: архитектура, паттерны, нейминг.
В ходе обсуждения проблемы модель задаёт одни и те же уточняющие вопросы.
Решением этой проблемы является файл AGENTS.md (или CLAUDE.md), который содержит в себе инструкции для агентов. Подключается этот файл в каждой сессии автоматически — делают это сами harness. Располагаться может не только в корне, но и внутри поддиректорий репозитория, тогда читаться они будут по иерархии вложенности. Выглядеть этот файл может примерно так:
# AGENTS.md ## Общие принципы 1. Сначала изучай документацию, затем код. 2. Не сканируй весь репозиторий без необходимости — работай от целевой директории. 3. Сохраняй обратную совместимость публичных API. 4. Любые изменения должны сопровождаться проверкой линтеров и тестов. 5. Не вноси изменения в инфраструктуру/конфиги без явной необходимости задачи. ## Технологический контур - Язык: PHP `8.4+` - Архитектура: модульная (`src/`, `tests/`, `config/`) - Frontend: отдельный слой в `frontend/` - Backend: бизнес-логика и API в `backend/` ## Ограничения и безопасность - Не коммить секреты (`.env`, токены, ключи). - Не используй destructive-операции (`force push`, `reset --hard`) без явного запроса. - Не меняй форматирование всего проекта ради локальной правки.
Если в этот файл записывать все инструкции, то скоро он станет довольно большим. Тогда он начнёт крайне неэффективно расходовать токены, а иногда может и путать агента, если правила слишком многословные, разнообразные и включают все аспекты продукта. Например, если мы делаем контроллер для бэка, нам не нужны инструкции для архитектуры фронтенда. Поэтому по-хорошему файл AGENTS.md должен содержать общие инструкции и правила, которые нужны в каждой сессии работы с агентом, и при этом быть справочником со ссылками на отдельные файлы с информацией. Например, можно сделать отдельные файлы для архитектур, а в корневом файле AGETNS.md только сослаться на них:
# AGENTS.md ... ## Читай по необходимости - [Frontend Guide](./specs/frontend.md) — правила для JS/TS, UI-компонентов, сборки и клиентских тестов. - [Backend Guide](./specs/backend.md) — правила для PHP-кода, слоев приложения, API-контрактов и серверных тестов.
Такой формат очень напоминает подход SDD и фреймворки OpenSpec и specs.md, при работе с которыми процесс разработки строится только через спецификации. Это гарантирует, что информация в спецификациях является единственным источником истины. «Спецификации» — это простой набор markdown-файлов.
Если в рамках спецификаций мы начинаем описывать стандарты, процессы, “workflows” you know, мы можем величественно назвать это “memory bank” - долгосрочная память нашего АИ агента, которая не теряется между сессиями работы.
Буст 2: скиллы
Вот ещё несколько проблем, которые могут возникнуть при работе с процессом ask -> plan -> build:
Aгент задаёт 10 вопросов одновременно вместо того чтобы спрашивать их по одному.
Планы всегда имеют разную структуру. Иногда одну из секций нужно дополнить. А иногда какая-то секция забывается, и из-за этого страдает реализация.
Чтобы добиться от агента предсказуемого ожидаемого поведения, мы можем использовать скиллы, в которых будут заложены необходимые инструкции:
Задавать вопросы строго по одному.
Зафиксировать шаблон плана с нужными секциями.
Базово скиллы подхватываются автоматически на основе текущей задачи и описания самого скилла. В рамках Cursor мы можем прямо в чате указать нужный нам скил через “/”, что гарантирует его использование. Раньше это называлось командами и жило отдельно от скиллов. Но теперь все эти вещи называются скиллы, просто с разным форматом запуска (команды отмечаются недоступными для автоматического использования моделью через “disable-model-invocation: true”). На скриншоте выше мы указали скилл “/ideal-plan”, который представляет собой обычный markdown .cursor/skills/ideal-plan/SKILL.md:
--- name: ideal-plan description: Placeholder skill. Use when extending ideal plan workflows after requirements are defined. disable-model-invocation: true --- # Ideal plan ## Инструкции 1. План ОБЯЗАТЕЛЬНО должен быть готовым к реализации без дополнительных уточнений. 2. План НЕ ДОЛЖЕН содержать варианты реализации; он должен быть конкретным и однозначным. 3. План ДОЛЖЕН содержать секции: - Зачем делаем - В чем ценность - Что трогаем - Что НЕ трогаем - Критерии приемки
В итоге мы получаем план с указанными нами секциями:
В качестве примера можно привести поделку Superpowers, у которой в скилле /brainstorming довольно хороший UX: этапы обсуждения, один вопрос за сессию, сформулированные варианты ответов и т.д. На этом преимущества данной поделки заканчиваются ;-)
Буст 3: субагенты
Как говорится: «нет предела совершенству», и останавливаться нам рано. Третий этап улучшения нашего процесса.
Обсуждение с агентом может довольно сильно затянуться в рамках сессии. А ещё в ходе диалога может понадобиться рассмотреть разные варианты реализации. Тут есть проблема: всё наше обсуждение будет находиться в контексте агента. Агенту нельзя сказать: «Забудь вариант А, будем делать вариант Б». Вместо этого агент запомнит всё: и оба варианта, и то, что его попросили сделать вариант Б. Если контекст большой, а вариант А был расписан подробно, агент легко забудет, что вы просили его сделать только вариант Б, потому что это может занимать меньшее место в контексте.
Решение проблемы — субагенты. Это агенты, которые вызывает сам агент. Для простоты можно привести такую аналогию:
Сначала мы общаемся с агентом и говорим ему инструкции.
Агент общается с субагентами и говорит инструкции им. Главная особенность субагентов — изолированный контекст, который формируется агентом отдельно от основной сессии.
Пример: мы составили план и отдали его в реализацию агенту. Когда результат готов, необходимо провести ревью этого кода. Как показывает практика, если выполнять ревью в том же контексте, где выполнялась реализация, и той же моделью, которая выполняла реализацию, то очень маловероятно найти какие-то проблемы. Вместо этого для качественного проведения ревью можно запустить субагента и сформировать ему новый корректный и сфокусированный исключительно на ревью контекст. По классике субагенты - это обычный markdown файл .cursor/agents/cool-reviewer.md:
--- name: cool-reviewer model: gpt-5.4 description: Экспертный ревьюер кода. Проактивно проверяет изменения на безопасность по OWASP Top 10, производительность и общую поддерживаемость. --- Ты опытный code reviewer с фокусом на безопасность и производительность. Цель: - Выявлять реальные риски и регрессии в измененном коде. - Давать конкретные правки, а не общие советы. - Отделять критичные проблемы от рекомендаций по улучшению. Рабочий процесс: 1. Определи, какие файлы и участки кода были изменены (используй hg/git diff в зависимости от репозитория). 2. Сначала проверь корректность логики и потенциальные регрессии. 3. Затем выполни обязательную проверку безопасности по OWASP Top 10: - A01 Broken Access Control - A02 Cryptographic Failures - A03 Injection - A04 Insecure Design - A05 Security Misconfiguration - A06 Vulnerable and Outdated Components - A07 Identification and Authentication Failures - A08 Software and Data Integrity Failures - A09 Security Logging and Monitoring Failures - A10 Server-Side Request Forgery 4. После этого проверь производительность: - есть ли кэширование там, где оно нужно; - нет ли тяжелых запросов без пагинации/лимитов; - нет ли N+1, лишних циклов, повторных вычислений и лишних I/O операций; - корректно ли выбраны структуры данных и точки инвалидации кэша. 5. Проверь поддерживаемость: читаемость, именование, обработка ошибок, тестируемость. Формат ответа: - Critical: проблемы, которые нужно исправить до мержа. - Major: важные проблемы, которые стоит исправить в этой задаче. - Minor: улучшения, которые можно сделать следом. - Questions: неочевидные места и уточнения. Требования к замечаниям: - Приводи ссылку на конкретный файл/фрагмент. - Объясняй риск и вероятное последствие. - Предлагай минимальный и практичный вариант исправления. - Если проблем нет, явно напиши, что по OWASP Top 10 и производительности критичных рисков не найдено.
Обратите внимание на верхнюю часть файла, так называемый frontmatter. Здесь можно указать дополнительную информацию об агенте. Доступные поля зависят от оболочки, в данном случае субагенту Cursor мы указали конкретную модель, которая будет выполнять ревью, что позволит нам выбрать достаточно умную модель для качественной проверки кода.
Делать отдельный файл с субагентом необязательно, это лишь системный промпт для субагента. Вполне успешно можно требовать вызывать субагента в самом скилле и там же подготовить для него промпт.
Напрямую субагенты вызывать нельзя. Мы можем либо сослаться на них в промпте, либо внутри скилла как в примере далее:
Cursor также позволяет провалиться внутрь контекста субагента и посмотреть, какой ему передали контекст и какие шаги он выполняет:
Изолированный контекст работает очень эффективно и фокусирует субагента на конкретной задачи, не отвлекая его раздутым контекстом обсуждения и реализации ;-)
Заключение
Не хочется сваливаться в снобизм, но всё, описанное в статье — это база! Все режимы, спецификации, субагенты — это всё итог решения повседневных реальных проблем, с которыми сталкиваются разработчики. Поделитесь в комментариях, какие инструменты и подходы вы уже используете, свои мысли на этот счёт и как скоро из операторов ЭВМ мы превратимся в операторов AI :)
