Как превратить Cursor-агента в полноценного участника команды: hooks, safe-list и Telegram-бот
Небольшая команда из шести человек, мобильное приложение и технический лидер, который работает part-time, - не самый очевидный сценарий для масштабного внедрения ИИ. Однако именно в таких условиях особенно заметно, насколько сильно агент может ускорить разработку и сколько проблем создаёт без понятных ограничений.
Речь идёт о спортивном мобильном приложении с профилями игроков, поиском партнёров, бронированием, платежами, чатами, лигами и турнирами. Клиентская часть написана на React Native с Expo и TypeScript, состояние управляется через Redux Toolkit, а отдельный сервер работает на Node.js. В команде - технический лидер на мобильной части, два backend-разработчика, два QA-инженера и дизайнер.
Cursor и Claude появились в проекте почти сразу. Сначала казалось, что всё работает идеально: агент пишет React Native-код, приложение собирается, задача закрывается. Но уже через несколько дней на ревью обнаруживались системные ошибки. Агент использовал hex-значения вместо `useTheme()`, складывал компоненты не в принятые папки, применял стандартный `Image` вместо внутреннего `AppImage`, а иногда пытался редактировать каталоги `android/` и `ios/`, которых в managed Expo-проекте вообще нет.
Проблема заключалась не в качестве генерации кода. Агент писал технически корректные решения, но не учитывал внутренние правила команды. Мы добавляли инструкции в промпт, однако это помогало лишь временно. После нескольких вызовов инструментов и просмотра новых файлов контекст терялся, а аналитики и разработчики не всегда формулировали задачу с одинаковыми вводными.
Так появились две ключевые задачи: обеспечить каждой сессии единый набор знаний о проекте и превратить важные правила из рекомендаций в автоматически проверяемые ограничения.
Документация для разных пользователей
Первоначально команда попыталась собрать все сведения в одном большом README. Такой подход быстро провалился: люди не читали длинный документ целиком, агент получал слишком много второстепенной информации, а аналитики тратили время на поиск нужного раздела.
Документацию разделили по аудиториям:
- `README.md` предназначен для людей: в нём описаны онбординг, переменные окружения, сборки и ограничения Expo Go;
- `CLAUDE.md` содержит сведения для разработчиков и аналитиков, работающих с ИИ-чатами: технологический стек, основные сущности, правила постановки задач и команды проверки;
- `AGENTS.md` описывает операционный процесс для автономных агентов, SDK и Telegram-бота;
- `.cursor/rules/*.mdc` фиксируют правила Cursor: структуру компонентов, импорт, работу с темой и обязательные соглашения;
- `docs/*.md` содержат инструкции для сложных доменных областей.
Главный принцип - отсутствие дублирования. Если правило цветов находится в `theme-colors.mdc`, его не копируют в README. Процесс создания pull request описан в `AGENTS.md`, а остальные документы лишь ссылаются на него.
Для уязвимых частей приложения создали отдельные доменные документы. Среди них - лиги и турниры, очередь промптов на главном экране, создание матча с предзаполненными данными, гостевой режим, офлайн-кэш и сокеты. Каждый файл содержит карту кода, список критических ограничений, актуальное состояние и текущий бэклог. История изменений туда не попадает: агенту важнее знать, как система устроена сейчас.
Hooks вместо повторяющихся просьб
Даже хорошо организованная документация не гарантирует соблюдение правил. Поэтому следующим уровнем стала настройка Cursor AI агента через lifecycle hooks. Hook работает на уровне рантайма и не зависит от того, сохранил ли агент нужную инструкцию в контексте.
В проекте используются события вроде `sessionStart`, `beforeToolCall`, `afterFileEdit` и `stop`. При запуске сессии агент получает напоминания о необходимости выполнить lint и type-check, не изменять `android/`, `ios/`, `.env` и соседний backend, а также обновлять документацию после крупных интеграционных изменений.
Перед вызовом инструмента проверяется, разрешено ли действие. Попытка удалить файл, выполнить опасную команду или изменить защищённую область блокируется. После редактирования можно автоматически запускать форматирование и локальные проверки. Перед завершением работы hook убеждается, что агент сформировал описание изменений и добавил инструкцию по тестированию.
Именно Cursor hooks настройка позволила перевести часть командных соглашений из категории "желательно" в категорию "обязательно". Подробнее о подобной архитектуре и распределении ролей между агентом, документацией и автоматическими проверками можно прочитать в материале о Cursor-агенте как участнике команды.
Safe-list и границы самостоятельности
Следующим шагом стала safe-list - перечень действий, которые агент может выполнять самостоятельно. В него попали безопасные операции: чтение файлов, поиск по репозиторию, запуск форматтера, type-check, lint, unit-тесты и создание локальной ветки по заданному шаблону.
Отдельного подтверждения требуют удаление файлов, изменение конфигурации Expo, редактирование переменных окружения, действия с миграциями базы, публикация сборок и операции с платежной логикой. Такой Cursor safe-list для кода снижает риск случайного разрушения проекта и одновременно не превращает агента в бесполезного помощника, которому нужно подтверждать каждый `grep`.
Важно разделять технические и бизнес-ограничения. Запрет на изменение `app.config.js` можно проверить автоматически, а вот изменение логики начисления рейтинга требует доменного документа и обязательного ревью. Поэтому safe-list не заменяет человека, а определяет безопасную область автономной работы.
Telegram как единая точка входа
Чтобы агентом могли пользоваться не только разработчики, команда сделала Telegram-бота. Через него можно передать задачу, выбрать репозиторий и ветку, получить статус выполнения, посмотреть краткое описание изменений и запросить создание PR.
Команда `/pr` запускает стандартный сценарий: агент создаёт рабочую ветку вида `bot/pr-*`, изучает необходимые документы, вносит изменения, запускает проверки и готовит pull request. В финальном сообщении бот показывает изменённые файлы, результаты тестов и список действий для ручной проверки.
Для накопившихся дефектов используется `/pr_qa`. QA отправляет описание проблемы, бот формирует очередь исправлений, а агент последовательно обрабатывает задачи. Это особенно удобно для небольших багов, которые в противном случае конкурировали бы с основной разработкой и терялись в чатах.
Так появился практичный Telegram-бот для Cursor агента: разработчик или тестировщик взаимодействует не с IDE и не с длинным промптом, а с единым командным интерфейсом.
Что не сработало
Команда отказалась от универсального README, чрезмерно длинных системных промптов и полной автономности. Не оправдала себя и идея разрешить агенту свободно менять backend: даже при наличии типов и тестов он не всегда понимал бизнес-последствия изменений.
Не стоит автоматизировать всё подряд. Если hook запускает тяжёлые проверки после каждого небольшого изменения, разработчики начинают его отключать. Если safe-list слишком узкая, агент перестаёт экономить время. А если документация не обновляется вместе с кодом, через несколько недель она превращается в источник ложных подсказок.
Итог
В результате Cursor стал не просто генератором фрагментов кода, а участником формализованного процесса. Документация задаёт контекст, правила `.mdc` фиксируют стиль и архитектуру, hooks контролируют жизненный цикл, safe-list определяет границы самостоятельности, а Telegram-бот делает взаимодействие доступным всей команде.
Такой подход особенно полезен небольшим коллективам, где один технический лидер не может вручную проверять каждую строку. Агент всё ещё нуждается в человеческом ревью, но теперь он чаще работает в рамках проекта, реже повторяет типовые ошибки и способен доводить небольшие задачи до готового PR без постоянного сопровождения.
