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

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

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

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

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

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

Понимание «agent harness» (Обвязка агента)

Обвязка агента состоит из трёх компонентов:

  1. Инструкции: системный промпт и правила, которые направляют поведение агента

  2. Инструменты: редактирование файлов, поиск по кодовой базе, выполнение команд в терминале и многое другое

  3. Сообщения пользователя: ваши запросы и уточнения, которые задают направление работы

Обвязка агента в Cursor оркестрирует эти компоненты для каждой поддерживаемой модели. Мы настраиваем инструкции и инструменты специально под каждую frontier-модель на основе внутренних оценок (evals) и внешних бенчмарков.

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

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

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

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

Использование Plan Mode

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

  1. Исследовать вашу кодовую базу и находить релевантные файлы

  2. Задавать уточняющие вопросы по требованиям

  3. Составлять детальный план реализации с путями к файлам и ссылками на код

  4. Ждать вашего одобрения перед началом реализации

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

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

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

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

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

Откатите изменения, сделайте план более конкретным и запустите снова. Часто это быстрее, чем выправлять работу «на ходу», и результат выходит чище.

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

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

Дайте агенту самому найти контекст

Не обязательно вручную ссылаться на каждый файл в промпте.

У агента Cursor есть мощные инструменты поиска, и он подтягивает контекст по запросу. Когда вы спрашиваете про «процесс аутентификации», агент найдёт релевантные файлы через grep и семантический поиск — даже если в вашем запросе нет этих слов.

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

У агента Cursor есть и полезные инструменты вроде @Branch, которые помогают дать контекст о текущей работе. «Сделай ревью изменений в этой ветке» или «Над чем я сейчас работаю?» становятся естественными способами сориентировать агента.

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

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

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

  • Вы переходите к другой задаче или фиче

  • Агент путается или повторяет одни и те же ошибки

  • Вы закончили один логический блок работы

Продолжайте текущий диалог, когда:

  • Вы итеративно дорабатываете ту же фичу

  • Агенту нужен контекст из предыдущих сообщений

  • Вы отлаживаете то, что он только что сделал

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

Ссылайтесь на прошлые диалоги

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

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

Расширение возможностей агента

Cursor даёт два основных способа настроить поведение агента:

  • Rules — статический контекст, который применяется к каждому диалогу

  • Skills — динамические способности, которые агент может использовать, когда это уместно

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

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

Создавайте правила как папки в .cursor/rules/, содержащие файл RULE.md:

# Commands

- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)

# Code style

- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure

# Workflow

- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

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

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

  • копирования целых style guides (лучше используйте линтер)

  • документирования всех возможных команд (агент и так знает распространённые инструменты)

  • добавления инструкций для редких случаев

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

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

Skills: динамические способности и воркфлоу

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

Skills описываются в SKILL.md и могут включать:

  • Custom commands: переиспользуемые воркфлоу, запускаемые через / в чате агента

  • Hooks: скрипты, которые выполняются до или после действий агента

  • Domain knowledge: инструкции для специфических задач, которые агент подтягивает по запросу

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

Пример: длительный цикл работы агента

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

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

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

Скрипт hook’а (.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: `[Iteration ${input.loop_count + 1}/${MAX_ITERATIONS}] Continue working. Update .cursor/scratchpad.md with DONE when complete.`
    })
  );
}

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

  • Прогона (и исправлений), пока не пройдут все тесты

  • Итераций UI, пока он не совпадёт с дизайн-макетом

  • Любых задач ориентированных на результат, где успех можно проверить

Совет: skills с hooks можно интегрировать с security-инструментами, менеджерами секретов и observability-платформами. Для партнёрских интеграций см. документацию по hooks.

Примечание: Agent Skills сейчас доступны только в nightly-канале обновлений. Откройте настройки Cursor → выберите Beta → установите канал обновлений Nightly → перезапустите.

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

Работа с изображениями

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

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

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

Визуальный дебаг

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

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

Частые воркфлоу

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

Разработка через тесты (TDD)

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

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

  2. Попросите запустить тесты и подтвердить, что они падают. Явно скажите не писать реализацию на этом этапе.

  3. Закоммитьте тесты, когда вас всё устраивает.

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

  5. Закоммитьте реализацию, когда вас всё устраивает.

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

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

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

  • «Как работает логирование в этом проекте?»

  • «Как добавить новый API endpoint?»

  • «Какие крайние случаи обрабатывает CustomerOnboardingFlow?»

  • «Почему мы вызываем setUser() вместо createUser() на строке 1738?»

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

Git-воркфлоу

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

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

Create a pull request for the current changes.

1. Look at the staged and unstaged changes with `git diff`
2. Write a clear commit message based on what changed
3. Commit and push to the current branch
4. Use `gh pr create` to open a pull request with title/description
5. Return the PR URL when done

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

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

  • /fix-issue [number]: получить детали issue через gh issue view, найти релевантный код, исправить и открыть PR

  • /review: прогнать линтеры, проверить частые проблемы и кратко подытожить, где может потребоваться внимание

  • /update-deps: проверить устаревшие зависимости и обновлять их по одной, прогоняя тесты после каждого шага

Агент может выполнять эти команды автономно — вы делегируете многошаговый процесс одной командой /.

Ревью кода

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

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

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

Ревью агентом

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

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

Bugbot для PR

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

Архитектурные диаграммы

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

“Create a Mermaid diagram showing the data flow for our authentication system, including OAuth providers, session management, and token refresh.”

Такие диаграммы полезны для документации и иногда помогают заранее увидеть архитектурные проблемы — ещё до ревью.

Параллельный запуск агентов

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

Поддержка git worktree

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

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

Запуск одного промпта на нескольких моделях

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

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

  • Сложных задач, где разные модели выбирают разные подходы

  • Сравнения качества кода между семействами моделей

  • Поиска крайних случаев, которые одна модель может упустить

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

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

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

  • Исправления ошибок, всплывших при работе над другими задачами

  • Рефакторинг недавних изменений

  • Генерация тестов для уже существующего кода

  • Обновление документации

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

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

  1. Вы описываете задачу и релевантный контекст

  2. Агент клонирует ваш репозиторий и создаёт ветку

  3. Он работает автономно и открывает pull request, когда закончит

  4. Вы получаете уведомление (через Slack, email или веб-интерфейс)

  5. Вы ревьюите изменения и мёрджите, когда готовы

Совет: вы можете запускать агентов из Slack через “@Cursor”. Подробнее в документации.

Debug Mode для сложных багов

Если стандартные взаимодействия с агентом не помогают разобраться с багом, Debug Mode предлагает другой подход.

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

  1. Генерирует несколько гипотез о причине проблемы

  2. Инструментирует код логированием

  3. Просит вас воспроизвести баг, собирая runtime-данные

  4. Анализирует фактическое поведение и находит корневую причину проблемы

  5. Делает точечные исправления на основе доказательств

Лучше всего подходит для:

  • Ошибок, которые воспроизводятся, но вы не понимаете причину

  • Ошибок синхронизации и тайминга в многопоточном коде

  • Ошибок производительности и утечек памяти

  • Регрессий, когда «раньше работало»

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

Ваш собственный workflow

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

Они пишут конкретные промпты. Успех агента заметно повышается от точных инструкций. Сравните «добавь тесты для auth.ts» и «Напиши тест для auth.ts на кейс logout, используй паттерны из tests/ и избегай моков».

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

Они тщательно ревьюят. Сгенерированный код может выглядеть правильно на первый взгляд, но скрывать ошибки. Читайте изменения и проверяйте внимательно. Чем быстрее агент работает, тем важнее ваш review-процесс.

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

Они относятся к агентам как к сильным коллегам. Просите планы. Просите объяснения. Спорьтесь с подходами, которые вам не нравятся.

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

Попробуйте эти техники, начав работу с агентом Cursor.

Про AI-инструменты и практики AI-driven разработки пишу в Telegram: @aidialogs