|
Professor Seleznov
|
Сегодня уже наверняка никто не станет спорить с тем, что писать код полностью руками — неэффективно. Но даже при разработке с помощью агентов есть оптимальные и не оптимальные пути работы с ними. В статье поговорим на тему того, какие вообще есть варианты агентской разработки и как можно повысить их эффективность.
Уровень 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  -Источник
|
