Перевод статьи Best practices for coding with agents от команды Cursor

Агенты для написания кода меняют то, как создаётся программное обеспечение.

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

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

Понимание системы управления агентом

Система управления агентом (agent harness) строится на трёх компонентах:

Инструкции: Системный промпт и правила, которые направляют поведение агента
Инструменты: Редактирование файлов, поиск по кодовой базе, выполнение команд в терминале и многое другое
Сообщения пользователя: Ваши промпты и уточняющие вопросы, которые направляют работу

Система управления агентом Cursor оркестрирует эти компоненты для каждой поддерживаемой модели. Мы настраиваем инструкции и инструменты специально для каждой передовой модели на основе внутренних оценок и внешних бенчмарков.

Система управления важна, потому что разные модели по-разному реагируют на одни и те же промпты. Модель, обученная на shell-ориентированных рабочих процессах, может предпочитать grep вместо специализированного инструмента поиска. Другой модели могут потребоваться явные инструкции для вызова инструментов линтера после редактирования. Агент Cursor обрабатывает это за вас, поэтому с выходом новых моделей вы можете сосредоточиться на создании программного обеспечения.

Начните с планов

Самое важное изменение, которое вы можете внести — это планирование перед написанием кода.

Исследование Университета Чикаго показало, что опытные разработчики чаще планируют перед генерацией кода. Планирование заставляет чётко думать о том, что вы строите, и даёт агенту конкретные цели для работы.

Использование режима планирования

Нажмите Shift+Tab во вводе агента, чтобы переключить режим планирования. Вместо немедленного написания кода агент будет:

Исследовать вашу кодовую базу для поиска релевантных файлов
Задавать уточняющие вопросы о ваших требованиях
Создавать детальный план реализации с путями к файлам и ссылками на код
Ждать вашего одобрения перед началом работы

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

Совет: Нажмите "Save to workspace", чтобы сохранить планы в .cursor/plans/. Это создаёт документацию для вашей команды, упрощает возобновление прерванной работы и предоставляет контекст для будущих агентов, работающих над той же функциональностью.

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

Начать заново с плана

Иногда агент создаёт что-то, что не соответствует тому, что вы хотели. Вместо попыток исправить это через уточняющие промпты, вернитесь к плану.

Откатите изменения, уточните план, чтобы он был более конкретным о том, что вам нужно, и запустите его снова. Это часто быстрее, чем исправление работающего агента, и даёт более чистые результаты.

Управление контекстом

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

Позвольте агенту найти контекст

Вам не нужно вручную помечать каждый файл в промпте.

Агент Cursor имеет мощные инструменты поиска и получает контекст по требованию. Когда вы спрашиваете о "потоке аутентификации", агент находит релевантные файлы через grep и семантический поиск, даже если ваш промпт не содержит этих точных слов.

Мгновенный grep позволяет агенту искать в вашей кодовой базе за миллисекунды.

Следуйте простому правилу: если вы знаете точный файл, пометьте его. Если нет, агент найдёт его. Включение нерелевантных файлов может запутать агента относительно того, что важно.

Агент Cursor также имеет полезные инструменты, такие как @Branch, которые позволяют дать агенту контекст о том, над чем вы работаете. "Проверь изменения на этой ветке" или "Над чем я работаю?" становятся естественными способами ориентировать агента на вашу текущую задачу.

Когда начинать новый разговор

Один из самых частых вопросов: продолжать этот разговор или начать заново?

Начните новый разговор, когда:

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

Продолжайте разговор, когда:

Вы итерируетесь над той же функциональностью
Агенту нужен контекст из более ранней части обсуждения
Вы отлаживаете что-то, что он только что создал

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

Ссылайтесь на прошлую работу

Когда вы начинаете новый разговор, используйте @Past Chats для ссылки на предыдущую работу, а не копируйте весь разговор целиком. Агент может выборочно читать историю чата, чтобы получить только необходимый контекст.

Это более эффективно, чем дублирование целых разговоров.

Расширение агента

Cursor предоставляет два основных способа наст��ойки поведения агента: Rules для статического контекста, который применяется к каждому разговору, и Skills для динамических возможностей, которые агент может использовать, когда это уместно.

Rules: Статический контекст для вашего проекта

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

Создавайте правила как файлы markdown в .cursor/rules/:

# Команды

-   `npm run build`: Собрать проект
-   `npm run typecheck`: Запустить проверку типов
-   `npm run test`: Запустить тесты (предпочитайте отдельные файлы тестов для скорости)

# Стиль кода

-   Используйте ES модули (import/export), а не CommonJS (require)
-   Деструктурируйте импорты, когда возможно: `import { foo } from 'bar'`
-   Смотрите `components/Button.tsx` для канонической структуры компонента

# Рабочий процесс

-   Всегда запускайте typecheck после серии изменений кода
-   API маршруты идут в `app/api/` следуя существующим паттернам

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

Чего избегать в правилах:

Копирование целых руководств по стилю (используйте линтер вместо этого)
Документирование каждой возможной команды (агент знает общие инструменты)
Добавление инструкций для крайних случаев, которые редко применяются

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

Сохраняйте ваши правила в git, чтобы вся ваша команда могла использовать их. Когда вы видите, что агент делает ошибку, обновите правило. Вы даже можете пометить @cursor в issue или PR на GitHub, чтобы агент обновил правило за вас.

Skills: Динамические возможности и рабочие процессы

Agent Skills расширяют то, что могут делать агенты. Skills упаковывают знания предметной области, рабочие процессы и скрипты, которые агенты могут вызывать, когда это уместно.

Skills определяются в файлах SKILL.md и могут включать:

Пользовательские команды: Переиспользуемые рабочие процессы, запускаемые с помощью / во вводе агента
Хуки: Скрипты, которые выполняются до или после действий агента
Знания предметной области: Инструкции для конкретных задач, которые агент может получить по требованию

В отличие от Rules, которые всегда включены, Skills загружаются динамически, когда агент решает, что они релевантны. Это держит ваше окно контекста чистым, давая агенту доступ к специализированным возможностям.

Пример: Долго работающий цикл агента

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

Сначала настройте хук в .cursor/hooks.json:

{
    "version": 1,
    "hooks": {
        "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
    }
}

Скрипт хука (.cursor/hooks/grind.ts) получает контекст из stdin и возвращает followup_message для продолжения цикла:

import { readFileSync, existsSync } from 'fs';

interface StopHookInput {
    conversation_id: string;
    status: 'completed' | 'aborted' | 'error';
    loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== 'completed' || input.loop_count >= MAX_ITERATIONS) {
    console.log(JSON.stringify({}));
    process.exit(0);
}

const scratchpad = existsSync('.cursor/scratchpad.md') ? readFileSync('.cursor/scratchpad.md', 'utf-8') : '';

if (scratchpad.includes('DONE')) {
    console.log(JSON.stringify({}));
} else {
    console.log(
        JSON.stringify({
            followup_message: `[Итерация ${input.loop_count + 1}/${MAX_ITERATIONS}] Продолжай работать. Обнови .cursor/scratchpad.md с DONE когда закончишь.`,
        })
    );
}

Этот паттерн полезен для:

Запуска (и исправления) до тех пор, пока все тесты не пройдут
Итерации над UI до тех пор, пока он не совпадёт с дизайн-макетом
Любой целеориентированной задачи, где успех можно проверить

Совет: Skills с хуками могут интегрироваться с инструментами безопасности, менеджерами секретов и платформами наблюдаемости. Смотрите документацию по хукам для интеграций партнёров.

Agent Skills в настоящее время доступны только в канале nightly. Откройте настройки Cursor, выберите Beta, затем установите канал обновлений на Nightly и перезапустите.

Помимо кодирования, вы можете подключить агента к другим инструментам, которые используете ежедневно. MCP (Model Context Protocol) позволяет агенту читать сообщения Slack, исследовать логи Datadog, отлаживать ошибки из Sentry, запрашивать базы данных и многое другое.

Включение изображ��ний

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

От дизайна к коду

Вставьте дизайн-макет и попросите агента реализовать его. Агент видит изображение и может соответствовать макетам, цветам и отступам. Вы также можете использовать MCP сервер Figma.

Визуальная отладка

Сделайте скриншот состояния ошибки или неожиданного UI и попросите агента исследовать это. Это часто быстрее, чем описывать проблему словами.

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

Общие рабочие процессы

Вот паттерны агентов, которые хорошо работают для разных типов задач.

Разработка через тестирование (TDD)

Агент может писать код, запускать тесты и итерироваться автоматически:

Попросите агента написать тесты на основе ожидаемых пар вход/выход. Чётко укажите, что вы делаете TDD, чтобы он избегал создания мок-реализаций для функциональности, которая ещё не существует.
Скажите агенту запустить тесты и подтвердить, что они падают. Чётко скажите не писать код реализации на этом этапе.
Закоммитьте тесты, когда вы будете удовлетворены ими.
Попросите агента написать код, который проходит тесты, инструктируя его не изменять тесты. Скажите ему продолжать итерироваться до тех пор, пока все тесты не пройдут.
Закоммитьте реализацию, когда будете удовлетворены изменениями.

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

Понимание кодовой базы

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

"Как работает логирование в этом проекте?"
"Как добавить новый API endpoint?"
"Какие крайние случаи обрабатывает CustomerOnboardingFlow?"
"Почему мы вызываем setUser() вместо createUser() на строке 1738?"

Агент использует как grep, так и семантический поиск для просмотра кодовой базы и поиска ответов. Это один из самых быстрых способов освоиться с незнакомым кодом.

Git рабочие процессы

Агенты могут искать историю git, разрешать конфликты слияния и автоматизировать ваш git рабочий процесс.

Например, команда /pr, которая коммитит, пушит и открывает pull request:

Создай pull request для текущих изменений.

1. Посмотри на staged и unstaged изменения с помощью `git diff`
2. Напиши понятное сообщение коммита на основе того, что изменилось
3. Закоммить и запушить в текущую ветку
4. Используй `gh pr create` для открытия pull request с заголовком/описанием
5. Верни URL PR когда закончишь

Команды идеальны для рабочих процессов, которые вы запускаете много раз в день. Храните их как файлы Markdown в .cursor/commands/ и сохраняйте в git, чтобы вся ваша команда могла их использовать.

Другие примеры команд, которые мы используем:

/fix-issue [номер]: Получить детали issue с gh issue view, найти релевантный код, реализовать исправление и открыть PR
/review: Запустить линтеры, проверить на общие проблемы и суммировать, что может потребовать внимания
/update-deps: Проверить устаревшие зависимости и обновить их по одной, запуская тесты после каждой

Агент может использовать эти команды автономно, поэтому вы можете делегировать многошаговые рабочие процессы одним вызовом /.

Проверка кода

Код, сгенерированный AI, нуждается в проверке, и Cursor предоставляет несколько вариантов.

Во время генерации

Следите за работой агента. Представление diff показывает изменения по мере их появления. Если вы видите, что агент идёт в неправильном направлении, нажмите Escape, чтобы прервать и перенаправить.

Проверка агентом

После того, как агент закончит, нажмите Review → Find Issues, чтобы запустить специальную проверку. Агент анализирует предлагаемые правки построчно и помечает потенциальные проблемы.

Для всех локальных изменений откройте вкладку Source Control и запустите Agent Review для сравнения с вашей основной веткой.

Bugbot для pull requests

Запушьте в систему контроля версий, чтобы получить автоматические проверки на pull requests. Bugbot применяет продвинутый анализ для раннего обнаружения проблем и предлагает улучшения на каждом PR.

Диаграммы архитектуры

Для значительных изменений попросите агента сгенерировать диаграммы архитектуры. Попробуйте промпт: "Создай диаграмму Mermaid, показывающую поток данных для нашей системы аутентификации, включая OAuth провайдеров, управление сессиями и обновление токенов." Эти диаграммы полезны для документации и могут выявить архитектурные проблемы до проверки кода.

Запуск агентов параллельно

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

Нативная поддержка worktree

Cursor автоматически создаёт и управляет git worktree для параллельных агентов. Каждый агент работает в своём собственном worktree с изолированными файлами и изменениями, поэтому агенты могут редактировать, собирать и тестировать код, не мешая друг другу.

Чтобы запустить агента в worktree, выберите опцию worktree из выпадающего списка агента. Когда агент закончит, нажмите Apply, чтобы объединить его изменения обратно в вашу рабочую ветку.

Запуск нескольких моделей одновременно

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

Это особенно полезно для:

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

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

Делегирование облачным агентам

Облачные агенты хорошо работают для задач, которые вы бы иначе добавили в todo-лист:

Исправления багов, которые возникли во время работы над чем-то другим
Рефакторинги недавних изменений кода
Генерация тестов для существующего кода
Обновления документации

Вы можете переключаться между локальными и облачными агентами в зависимости от задачи. Запускайте облачных агентов с cursor.com/agents, из редактора Cursor или с телефона. Проверяйте сессии из веб-интерфейса или мобильного приложения, пока вы вдали от рабочего места. Облачные агенты работают в удалённых песочницах, поэтому вы можете закрыть ноутбук и проверить результаты позже.

Вот как работают облачные агенты под капотом:

Опишите задачу и любой релевантный контекст
Агент клонирует ваш репозиторий и создаёт ветку
Он работает автономно, открывая pull request, когда закончит
Вы получаете уведомление, когда это сделано (через Slack, email или веб-интерфейс)
Проверьте изменения и слейте, когда будете готовы

Совет: Вы можете запускать агентов из Slack с "@Cursor". Узнайте больше.

Режим отладки для сложных багов

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

Вместо угадывания исправлений, режим отладки:

Генерирует множественные гипотезы о том, что может быть не так
Инструментирует ваш код с помощью операторов логирования
Просит вас воспроизвести баг, собирая данные времени выполнения
Анализирует фактическое поведение для точного определения корневой причины
Делает целевые исправления на основе доказательств

Это лучше всего работает для:

Багов, которые вы можете воспроизвести, но не можете понять
Гонок условий и проблем с таймингом
Проблем производительности и утечек памяти
Регрессий, где что-то раньше работало

Ключ в предоставлении детального контекста о том, как воспроизвести проблему. Чем более конкретны вы, тем более полезную инструментацию добавляет агент.

Развитие вашего рабочего процесса

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

Они пишут конкретные промпты. Успешность агента значительно улучшается с конкретными инструкциями. Сравните "добавь тесты для auth.ts" с "Напиши тест-кейс для auth.ts, покрывающий крайний случай выхода, используя паттерны в __tests__/ и избегая моков."

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

Они тщательно проверяют. Код, сгенерированный AI, может выглядеть правильно, будучи тонко неправильным. Читайте diff'ы и тщательно проверяйте. Чем быстрее работает агент, тем важнее становится ваш процесс проверки.

Они предоставляют проверяемые цели. Агенты не могут исправить то, о чём они не знают. Используйте типизированные языки, настройте линтеры и пишите тесты. Дайте агенту чёткие сигналы о том, правильны ли изменения.

Они работают с агентами как с полноценными коллегами. Просите планы. Запрашивайте объяснения. Отклоняйте подходы, которые вам не нравятся.

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

Оригинальная статья: Best practices for coding with agents

Лучшие практики работы с агентами для написания кода