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

Уровень 0: пишем ручками

Настоящий олдскул! Когда-то наши предки, своими собственными руками писали буквы, которые затем превращались в исходный код важной программы. Ой, а это было всего несколько лет назад…

Уровень 1: промптинг

Все уже привыкли общаться с агентами через окно чатика. Это касается и жизненной рутины, и разработки:

1. открыли чат

2. описали задачу

3. отправили агента в добрый путь

Для адептов черно-белого консольного месива приложу другой скрин, чтобы вы не терялись, о чем речь:

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

• где находится логика работы с товарами?

• где лежат нужные контроллеры?

• через какой слой здесь вообще принято работать: напрямую через сервисы, через репозитории или через какие-нибудь хелперы?

Уровень 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-разработки:

1. В режиме ask: обсудили проблему/задачу и в диалоге с агентом нашли решение.

2. В режиме plan: составили детальный план реализации и проверили его перед реализацией.

3. В режиме 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 :)