[Перевод] Большой гайд от Cursor: как эффективно программировать с ИИ-агентам

Команда AI for Devs подготовила перевод большой статьи команды Cursor о том, как эффективно работать с агентами для написания кода. В материале разбираются практики планирования, управления контекстом, ревью, параллельного запуска агентов и делегирования задач в облако.

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

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

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

Понимание agent harness

Agent harness состоит из трёх компонентов:

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

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

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

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

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

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

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

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

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

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

1. Изучит кодовую базу, чтобы найти релевантные файлы;

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

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

4. Будет ждать вашего одобрения перед началом разработки.

Plan Mode в действии: агент задаёт уточняющие вопросы и формирует план, удобный для ревью.

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

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

Возврат к плану и повторный запуск

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

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

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

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

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

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

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

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

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

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

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

Один из самых частых вопросов: продолжать текущий диалог или начать новый?

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

• Вы переходите к другой задаче или возможности;

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

• Вы завершили один логически законченный этап работы.

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

• Вы итеративно дорабатываете одну и ту же возможность;

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

• Вы отлаживаете то, что он только что реализовал.

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

Ссылки на прошлую работу

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

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

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

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

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

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

Rules создаются в виде Markdown-файлов в .cursor/rules/:

# 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

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

Чего не стоит включать в rules:

• Копирование целых стайлгайдов (для этого лучше использовать линтер);

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

• Инструкции для редких пограничных случаев.

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

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

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

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

• Пользовательские команды: переиспользуемые рабочие процессы, запускаемые через / в поле ввода агента

• Хуки (hooks): скрипты, которые выполняются до или после действий агента

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

В отличие от 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: `[Iteration ${input.loop_count + 1}/${MAX_ITERATIONS}] Continue working. Update .cursor/scratchpad.md with DONE when complete.` })); }

Этот паттерн полезен для следующих сценариев:

• Запуска и исправления кода до тех пор, пока все тесты не пройдут;

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

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

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

Использование изображений

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

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

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

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

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

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

Боковая панель браузера позволяет одновременно работать с дизайном и кодом.

Типовые рабочие процессы

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

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

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

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

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

3. Закоммитьте тесты, когда будете ими довольны.

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

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

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

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

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

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

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

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

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

Агент использует и 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

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

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

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

• /review: запустить линтеры, проверить типовые проблемы и кратко описать, на что стоит обратить внимание;

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

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

Ревью кода

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

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

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

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

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

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

Ревью ИИ-кода находит и исправляет баги прямо в Cursor.

Bugbot для pull request’ов

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

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

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

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

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

Встроенная поддержка worktree

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

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

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

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

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

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

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

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

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

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

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

• Исправление багов, обнаруженных по ходу другой работы;

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

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

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

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

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

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

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

3. Он работает автономно и по завершении открывает pull request;

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

5. Вы просматриваете изменения и сливаете их, когда будете готовы.

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

Когда стандартное взаимодействие с агентом не помогает разобраться с багом, на помощь приходит Debug Mode — он предлагает иной подход.

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

1. Формулирует несколько гипотез о возможной причине проблемы;

2. Добавляет в код логирование;

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

4. Анализирует фактическое поведение, чтобы точно определить первопричину;

5. Вносит точечные правки, основанные на полученных данных.

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

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

• race condition и проблем, связанных с таймингами;

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

• регрессий, когда что-то раньше работало, а теперь нет.

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

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

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

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

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

Они внимательно делают ревью. Код, сгенерированный ИИ, может выглядеть правильным, оставаясь при этом subtly неверным. Читайте diff’ы и проверяйте изменения тщательно. Чем быстрее работает агент, тем важнее становится процесс ревью.

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

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

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

Начните работать с агентом Cursor, чтобы попробовать эти приёмы на практике.

Русскоязычное сообщество про AI в разработке

Друзья! Эту статью подготовила команда ТГК «AI for Devs» — канала, где мы рассказываем про AI-ассистентов, плагины для IDE, делимся практическими кейсами и свежими новостями из мира ИИ. Подписывайтесь, чтобы быть в курсе и ничего не упустить!