Перевод статьи от команды Cursor под названием «Best practices for coding with agents«. Опубликована 9 января 2026 г.

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

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

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

Понимание обвязки агента

Обвязка агента (Agent harness — программная оболочка, управляющая взаимодействием с моделью) строится на трех компонентах:

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

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

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

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

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

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

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

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

1. Исследует вашу кодовую базу, чтобы найти релевантные файлы.
2. Задаст уточняющие вопросы о ваших требованиях.
3. Создаст детальный план реализации с путями к файлам и ссылками на код.
4. Будет ждать вашего одобрения перед сборкой.

(Видео Plan Mode в действии: агент задает уточняющие вопросы и создает план для проверки)

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

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

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

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

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

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

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

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

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

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

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

(Видео «Instant grep» (Мгновенный поиск), позволяющий агенту искать по кодовой базе за миллисекунды)

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

У агента Cursor также есть полезные инструменты, такие как @Branch (Ветка), которые позволяют дать агенту контекст о том, над чем вы работаете. Фразы «Review the changes on this branch» (Проверь изменения в этой ветке) или «What am I working on?» (Над чем я работаю?) становятся естественными способами сориентировать агента в вашей текущей задаче.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Рабочий процесс
— Всегда проверяйте типы после серии изменений в коде
— API маршруты помещайте в `app/api/`, следуя существующим паттернам

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

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

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

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

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

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

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

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

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

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

Пример: Долгоживущий цикл агента

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

Сначала настройте хук в .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 (пользовательским интерфейсом), пока он не будет соответствовать макету дизайна.
• Любой целеориентированной задачи, где успех можно верифицировать (проверить).

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

Навыки агента в настоящее время доступны только в канале релизов «nightly» (ночная сборка). Откройте настройки Cursor, выберите Beta, затем установите канал обновлений на Nightly и перезапустите.

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

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

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

Дизайн в код

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

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

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

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

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

Распространенные рабочие процессы

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

Разработка через тестирование (Test-driven development, TDD)

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

1. Попросите агента написать тесты на основе пар ожидаемых входных/выходных данных. Четко укажите, что вы используете TDD, чтобы он избегал создания мок-реализаций (фиктивных реализаций) для функционала, которого еще нет.
2. Скажите агенту запустить тесты и подтвердить, что они падают (fail). Явно скажите не писать код реализации на этом этапе.
3. Закоммитьте тесты, когда будете ими довольны.
4. Попросите агента написать код, который проходит тесты, проинструктировав его не менять сами тесты.
5. Скажите ему продолжать итерировать, пока все тесты не пройдут.
6. Закоммитьте реализацию, когда будете довольны изменениями.

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

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

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

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

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

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

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

Например, команда /pr, которая коммитит, пушит (отправляет на сервер) и открывает пулл-реквест:

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: Проверить устаревшие зависимости и обновить их по одной, запуская тесты после каждого обновления.

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

Рецензирование кода (Reviewing code)

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

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

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

Проверка агентом (Agent review)

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

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

(AI code review находит и исправляет баги прямо в Cursor)

Bugbot для пулл-реквестов

Пушьте в систему контроля версий, чтобы получать автоматические рецензии на пулл-реквесты. Bugbot (Баг-бот) применяет продвинутый анализ для раннего обнаружения проблем и предложения улучшений в каждом PR.

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

Для значительных изменений попросите агента сгенерировать архитектурные диаграммы. Попробуйте такой промпт: «Create a Mermaid diagram showing the data flow for our authentication system, including OAuth providers, session management, and token refresh» (Создай диаграмму Mermaid, показывающую поток данных для нашей системы аутентификации, включая OAuth-провайдеров, управление сессиями и обновление токенов). Эти диаграммы полезны для документации и могут выявить архитектурные проблемы до код-ревью.

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

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

Нативная поддержка рабочих деревьев (Native worktree support)

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

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

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

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

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

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

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

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

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

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

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

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

1. Опишите задачу и любой релевантный контекст.
2. Агент клонирует ваш репозиторий и создает ветку.
3. Он работает автономно, открывая пулл-реквест по завершении.
4. Вы получаете уведомление, когда он закончит (через Slack, email или веб-интерфейс).
5. Проверьте изменения и слейте (merge), когда будете готовы.

Совет: Вы можете триггерить (запускать) агентов из Slack с помощью «@Cursor».

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

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

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

1. Генерирует несколько гипотез о том, что может быть не так.
2. Инструментирует ваш код (добавляет отладочный код) логгированием.
3. Просит вас воспроизвести баг, пока собирает данные времени выполнения (runtime data).
4. Анализирует фактическое поведение, чтобы определить корневую причину (root cause).
5. Делает целевые исправления на основе доказательств.

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

• Багов, которые вы можете воспроизвести, но не можете понять.
• Состояний гонки (race conditions — ошибок, зависящих от порядка выполнения потоков) и проблем с таймингами.
• Проблем с производительностью и утечек памяти.
• Регрессий (ошибок, вернувшихся после исправления), когда что-то раньше работало.

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

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

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

• Они пишут конкретные промпты. Процент успеха агента значительно растет при наличии конкретных инструкций. Сравните «add tests for auth.ts» (добавь тесты для auth.ts) и «Write a test case for auth.ts covering the logout edge case, using the patterns in __tests__/ and avoiding mocks» (Напиши тест-кейс для auth.ts, покрывающий граничный случай логаута, используя паттерны из __tests__/ и избегая моков).
• Они итерируют над своей настройкой. Начните с простого. Добавляйте правила только тогда, когда заметите, что агент повторяет одну и ту же ошибку. Добавляйте команды только после того, как выработаете рабочий процесс, который хотите повторять. Не переоптимизируйте, пока не поймете свои паттерны.
• Они тщательно проверяют. Сгенерированный ИИ код может выглядеть правильным, но быть тонко ошибочным. Читайте диффы и тщательно рецензируйте. Чем быстрее работает агент, тем важнее становится ваш процесс проверки.
• Они предоставляют верифицируемые цели. Агенты не могут исправить то, о чем не знают. Используйте типизированные языки, настраивайте линтеры и пишите тесты. Давайте агенту четкие сигналы о том, правильны ли изменения.
• Они относятся к агентам как к способным сотрудникам. Просите планы. Запрашивайте объяснения. Отвергайте подходы, которые вам не нравятся.

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

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