Промпты для coding-агентов: как перестать спорить с кодом

За последний год coding-агенты перестали быть автодополнением строки. Cursor с режимом Agent, Claude Code от Anthropic, GitHub Copilot с Agent Mode и OpenAI Codex умеют читать репозиторий, запускать тесты, править несколько файлов подряд и открывать pull request. Проблема сместилась: раньше спорили, как заставить модель написать функцию, теперь — как заставить агента не сломать половину проекта, пока он чинит вторую. И ответ почти всегда в том, как вы формулируете задачу и что кладёте в контекст, а не в секретных словах-заклинаниях.

Почему промпт для агента — это не промпт для чата

В обычном чате вы получаете текст и сами решаете, что с ним делать. Агент действует: читает файлы, редактирует их, вызывает инструменты, запускает команды. Ошибка в формулировке здесь стоит не абзаца бесполезного текста, а десяти изменённых файлов, которые придётся откатывать через git reset.

Отсюда первое правило: агенту нужен не красивый запрос, а проверяемая цель и границы. Формулировка «улучши производительность» превращает сессию в лотерею. Формулировка «функция parseOrders в src/orders.ts обрабатывает список из 50 000 записей за 4 секунды, цель — уложиться в 500 мс, не меняя её сигнатуру, тесты в orders.test.ts должны проходить» даёт агенту критерий, по которому он сам поймёт, закончил он или нет.

Хороший промпт для агента — это не описание того, что вы хотите увидеть, а описание того, как агент поймёт, что справился.

Три вещи, которые агент должен знать до старта

• Цель и критерий готовности. Что считается результатом: проходят тесты, собирается проект, линтер молчит.
• Границы. Какие файлы трогать можно, какие нельзя, что нельзя ломать (публичный API, схему БД, форматы ответов).
• Контекст проекта. Стек, соглашения по коду, где лежит что. Это то, что человек знает по умолчанию, а модель — нет, пока вы не покажете.

Файл с инструкциями важнее любого одиночного запроса

Большинство современных агентов читают проектный файл с постоянными инструкциями. У Claude Code это CLAUDE.md, у Cursor — правила проекта (Rules), у Copilot — .github/copilot-instructions.md. Этот файл подмешивается в контекст каждой сессии, и именно он снимает 80% повторяющихся правок.

Что туда стоит положить:

1. Команды: как запустить тесты, линтер, сборку, дев-сервер. Агент будет использовать их вместо того, чтобы гадать.
2. Соглашения: менеджер пакетов (npm/pnpm/yarn), стиль импортов, где хранить типы, как называть файлы.
3. Запреты: «не редактируй сгенерированные файлы в dist/», «не коммить .env», «не меняй версии зависимостей без запроса».
4. Архитектурные факты, которые не видны из одного файла: где точка входа, как устроены слои, где бизнес-логика.

Файл не должен превращаться в роман. Модель работает в пределах контекстного окна¹, и раздутые инструкции конкурируют за место с самим кодом. Держите его в пределах пары экранов и обновляйте, когда ловите агента на одной и той же ошибке дважды.

Контекст решает больше, чем формулировка

Практика показывает простую закономерность: агент ошибается не потому, что вы неудачно сформулировали, а потому, что не видел нужный кусок кода. Он не знает, что похожая функция уже есть в соседнем модуле, и пишет дубль. Он не видел тип ответа API и придумал структуру.

Поэтому перед сложной задачей полезно самому указать релевантные файлы — по имени или через механизм упоминания (@file в Cursor, явное перечисление путей в запросе). Некоторые агенты подтягивают контекст через поиск по репозиторию, в том числе на основе RAG², но полагаться на автоматический поиск на 100% рано: он находит похожее по тексту, а не всегда нужное по смыслу.

Разбивайте задачу, а не полагайтесь на одну мега-инструкцию

Длинная задача «отрефактори модуль авторизации, добавь двухфакторку и покрой тестами» в одном промпте — верный способ получить кашу. Агент дрейфует: к середине сессии он забывает, что было в начале, и начинает противоречить собственным ранним правкам. Надёжнее вести его шагами: сначала план, потом реализация по пунктам с проверкой после каждого.

Многие агенты умеют сначала выдавать план и ждать подтверждения. Пользуйтесь этим: дешевле поправить план из пяти строк, чем откатывать двадцать файлов.

Как ведут себя основные инструменты

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

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

Кому это пригодится, а кому нет

Пригодится, если:

• Вы ведёте проект с внятной структурой, тестами и линтером — агенту есть на что опереться и чем себя проверить.
• Задачи повторяются: миграции, обновление зависимостей, однотипный рефакторинг, генерация обвязки вокруг API.
• Вы готовы тратить пять минут на формулировку задачи с критериями, чтобы сэкономить полчаса на правках.

Скорее помешает, если:

• Кодовая база без тестов и с хаотичной структурой — агенту нечем себя проверить, и он уверенно ломает то, что работало.
• Задача требует понимания бизнес-контекста, которого нет в репозитории (почему тут именно такая логика скидок).
• Вы принимаете правки не глядя. Агент ошибается уверенно и правдоподобно, а ответственность за merge остаётся на вас.

¹ Контекстное окно — объём текста (кода, инструкций, истории диалога), который модель удерживает одновременно. Измеряется в токенах. Всё, что не влезло, модель не учитывает.

² RAG (retrieval-augmented generation) — подход, при котором система сначала находит релевантные фрагменты (например, куски репозитория) и подмешивает их в запрос к модели, вместо того чтобы держать весь проект в контексте сразу.