Как подружить ИИ-агентов и реальный код: уровни разработки и рабочие практики — VogueTech

Что нового

Разработчики перестали воспринимать нейросети как «магический чатик» и начали строить вокруг них полноценный процесс разработки. В материале разобраны конкретные уровни работы с ИИ в коде:

Ручное программирование (уровень 0) — классический подход, когда всё пишем сами.
Промптинг (уровень 1) — общение с агентом через чат без дополнительного контекста.
Контекстинг (уровень 2) — подсказки агенту: какие директории, файлы и сущности использовать.
Планирование (уровень 3) — режимы ask / plan / agent в Cursor, когда сначала согласуем план, а уже потом запускаем автогенерацию кода.
Спецификации для агентов (AGENTS.md / CLAUDE.md) — постоянные инструкции, которые автоматически подхватывает IDE-харнесс и добавляет в каждую сессию.

Главное изменение: разработчик перестаёт каждый раз объяснять одно и то же, а строит вокруг ИИ-агентов предсказуемый процесс — с планами, правилами и архитектурными ограничениями.

Как это работает

Уровень 0: полностью ручное программирование

Базовая точка отсчёта. Разработчик сам пишет код, сам продумывает архитектуру, сам ищет файлы и точки интеграции. Никаких агентов, максимум — автодополнение в IDE.

Плюсы:

полный контроль над результатом;
понятная ответственность за архитектуру и качество.

Минусы:

медленно;
тяжело масштабировать команду и скорость поставки фич.

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

Это самый распространённый сценарий: разработчик открывает чат с агентом (например, в веб-интерфейсе или IDE), описывает задачу и ждёт ответ:

Открыл чат.
Сформулировал задачу.
Получил код или объяснение.

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

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

Разработчик тратит время на уточнения, агент — на «угадайку» по проекту.

Уровень 2: контекстинг

Чтобы агент не пытался «прочитать мысли», разработчик начинает подсовывать ему контекст:

указывает директорию модуля, например catalog/;
даёт конкретный файл сущности, например product.php;
ограничивает область поиска и изменений.

Что это даёт:

агент быстрее находит нужный код;
меньше тратит токены на сканирование всего репозитория;
реже предлагает решения «в вакууме», не подходящие под текущую архитектуру.

Но контекста не хватает, когда задача:

затрагивает несколько модулей;
требует изменений на уровне архитектуры;
допускает несколько стратегий реализации.

В итоге после автогенерации всё равно приходится:

исправлять архитектурные решения;
переименовывать сущности под принятый нейминг;
возвращать совместимость с остальным кодом.

Разработчику нужен способ влиять на ход работы агента до того, как тот начнёт переписывать проект.

Уровень 3: планирование через режимы Cursor

Здесь в игру вступают IDE-харнессы — оболочки вокруг LLM. Пример из текста — Cursor, который работает с тремя ключевыми режимами:

agent — полноценный агент: читает и пишет файлы, вносит изменения в проект;
ask — режим вопросов и ответов, модель только читает код и даёт советы, но не меняет файлы;
plan — режим планирования: агент не пишет код, а формирует markdown‑план с шагами реализации.

Рабочий цикл выглядит так:

ask — обсуждаем проблему, уточняем вводные, выбираем подход.
plan — агент пишет детальный план: какие файлы трогать, какие методы добавить, как тестировать.
agent (build) — после утверждения плана агент реализует его в коде.

Плюсы такого подхода:

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

Cursor к этому добавляет и другие режимы и фичи, которые описаны в его документации: https://cursor.com/ru/docs

Что это значит для вас

Когда хватит простого промптинга

Если вы:

пилите небольшой сервис или MVP;
работаете один или в маленькой команде;
не держите жёсткую архитектуру,

то общение с агентом «по-человечески» через чат может закрыть большинство задач. Достаточно давать краткий контекст по файлам и ожидать черновики решений.

Когда нужен контекстинг и планирование

Если у вас:

монорепозиторий или крупный продукт;
несколько модулей и слоёв (frontend/backend, сервисы, репозитории);
строгие требования к архитектуре и совместимости API,

то без контекстинга и планов агент начнёт ломать существующие договорённости:

писать новую бизнес-логику в контроллерах;
обходить слои абстракции;
нарушать нейминг и форматирование.

Режимы ask → plan → agent помогают превратить ИИ в участника процесса, а не в хаотичного генератора патчей.

Где можно обойтись без планирования

Планирование даёт выигрыш, но не всегда оправдано по времени. Его можно пропустить, если:

задача локальная (один файл, одна функция);
нет рисков затронуть публичные API;
вы готовы быстро откатить изменения.

Во всех остальных случаях план как минимум сэкономит время на ревью и исправления.

Спецификации для агентов: AGENTS.md / CLAUDE.md

Даже при планировании есть две повторяющиеся проблемы:

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

Решение — завести в репозитории файл инструкций для агентов, например AGENTS.md или CLAUDE.md. Харнесс (Cursor и аналоги) подключает его автоматически к каждой сессии.

Файл можно класть:

в корень репозитория — общие правила для всего проекта;
в поддиректории — локальные правила для конкретных модулей.

Файлы читаются по иерархии: чем глубже директорія, тем более специфичными могут быть инструкции.

Пример содержимого:

# 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`) без явного запроса.
- Не меняй форматирование всего проекта ради локальной правки.

Что это даёт на практике:

агент перестаёт предлагать решения, которые ломают публичные API;
не трогает инфраструктуру без прямого запроса;
не сканирует весь репозиторий при каждой мелкой задаче;
понимает, где frontend, где backend, где тесты.

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

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

Поэтому важно держать инструкции:

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

Место на рынке

Подход с уровнями агентской разработки и файлами спецификаций не привязан к одной экосистеме. Его можно реализовать с любыми LLM — GPT-4, GPT-4o, Claude 3, Claude 3.5 и другими — при условии, что IDE или оболочка поддерживает:

работу с проектом как с файловой системой;
разные режимы доступа (только чтение, план, запись);
автоматическое подключение инструкций из репозитория.

Cursor здесь выступает как показательный пример харнесса с режимами ask / plan / agent и поддержкой AGENTS.md. Другие инструменты могут давать похожий функционал с другими названиями режимов.

Если вы уже используете LLM в разработке, но ограничиваетесь чатом, переход на связку:

контекстинг по директориям и файлам;
планирование перед изменениями;
AGENTS.md с архитектурными правилами

даст ощутимый прирост предсказуемости и снизит количество правок после работы агента.

Кому это особенно полезно:

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

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