Где в Cursor хранить контекст проекта

Cursor agent в документации собирается из трёх частей: Instructions, Tools и Model (overview). Instructions - это не только ваш промпт, но и Project Rules, AGENTS.md, User Rules и то, что вы явно прикрепили через @. Когда brief пустой, модель опирается на общие знания о «типичном React-проекте» и начинает угадывать: другой тест-раннер, чужие папки, лишние зависимости.

Симптом, который я ловлю на первом созвоне: агент уверенно пишет код, но не тот стек. В репо Vitest, а в ответе Jest. Monorepo с apps/crm и apps/web, а правки уходят в корневой src/. Это не «глупая модель», это пустой cursor context. Cursor agent mode без карты репо превращает автономный режим в лотерею: инструменты search и edit работают, но цель выбирается вслепую.

Я разделяю два слоя. Долгая память - rules и AGENTS.md в git, подключаются по правилам проекта (rules). Тактика на задачу - чат, @ на файлы, diff ветки, узкий scope в промпте (prompting). Без первого слоя второй каждый раз начинается с нуля: вы снова объясняете, где backend, какие команды verify, что трогать нельзя.

На новостных разборах всплывает отдельный риск: публичные логи агента, куда случайно попали пароли из промпта. Угол простой - не кормить секретами ни чат, ни rules, ни вложения. Cloud Agent умеет redact runtime secrets (security), но это не отменяет здравый смысл: ключ в промпте уже ушёл в историю.

Чеклист «готов ли репо к Agent» из пяти пунктов:

1. 01

   Есть AGENTS.md или один project rule с картой папок и стеком.

2. 02

   Verify-команды скопированы дословно из package.json или Makefile.

3. 03

   .cursorignore закрывает .env*, ключи и тяжёлые артефакты.

4. 04

   В git отдельная ветка под задачу, commit «до агента».

5. 05

   В промпт добавлены 1-3 @ на entrypoint, а не весь src/.

Подробнее про режимы и когда включать Agent - в cursor agent mode. Здесь фокус на том, что положить в контекст до клика Build.

Project brief - это не копипаст всего дерева файлов и не dump README на три экрана. Я укладываю карту в 5-10 строк: где frontend и backend, entrypoints, «священные» папки, monorepo-пакеты. Остальное агент находит через search, если вы указали якоря.

Пример карты для вымышленного CRM-бота (без реальных ключей):

bot/          - Telegraf, entry bot/index.ts
web/          - Vite + React, entry web/src/main.tsx
shared/       - типы заявок, не трогать без задачи
deploy/       - только по явному запросу
prisma/       - migrations только с моего OK

Стек пишу конкретными именами: «Node 20, Telegraf 4, Prisma, Vitest», а не «веб на React». Пакетный менеджер, ORM, линтер - одной строкой. Если в monorepo три приложения, я перечисляю, какое из них в scope сегодняшней задачи, и какие соседние модули закрыты.

Про env без секретов: в brief указываю названия переменных (DATABASE_URL, TELEGRAM_BOT_TOKEN), но не значения. Файлы .env* лежат в .gitignore и .cursorignore. Если агенту нужен формат - даю пример .env.example без боевых строк. В чат не вставляю production-токен «чтобы заработало» - после публикации логов это уже не откатить.

Cursor context used в интерфейсе - счётчик того, что попало в окно: rules, @-файлы, сжатая история, tool output (prompting). Отсюда правило: не грузите полные дампы логов, весь node_modules через @, скриншоты с PII. Лучше ссылка @src/handlers/lead.ts и две строки симптома.

Как создать проект cursor в смысле «готов к агенту»: File → Open Folder на репозиторий, затем brief. Отдельного мастера «New Cursor Project» нет - проект это папка с кодом плюс контекстный пакет. Первый вечер с веткой и diff я разбирал в первом проекте в Cursor.

Минимальный .cursorignore для того же CRM-бота:

.env
.env.*
secrets/
deploy/production.*
node_modules/
dist/
coverage/
*.pem
*.key

Помните оговорку из доки: .cursorignore блокирует read и @ для Agent, Tab и Inline Edit, но не блокирует terminal и MCP (ignore-file). Если агент запускает shell, он теоретически может прочитать то, что вы закрыли от индекса. Нужны approvals на команды и права на файлы в ОС.

Verify-команды в brief - дословно из вашего package.json, не из головы модели. Документация советует не дублировать очевидные git status в rules (rules), но ваши скрипты - да: npm run lint, npm test, npm run build, pnpm exec vitest run, что реально есть в репо.

Я добавляю критерий «готово» в двух формулировках - для агента и для себя:

Типичный блок в brief:

## Verify
npm run lint && npm test && npm run build

## Готово когда
- lint/test/build - exit 0
- изменены только файлы из scope задачи
- нет новых зависимостей в package.json
- .env* не в diff

После Agent я не верю словам «тесты прошли». Открываю терминал и гоняю те же команды. Скрипт, который копирую ученикам:

#!/usr/bin/env bash
set -euo pipefail
npm run lint
npm test
npm run build
git diff --stat
git diff | grep -E '\.env|SECRET|TOKEN|password' && echo "STOP: secrets in diff" && exit 1 || true

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

Порядок verify, который я держу на разборах:

1. 01

   Agent закончил - не принимать всё сразу.

2. 02

   npm run lint и npm test вручную в терминале.

3. 03

   git diff по файлам из scope.

4. 04

   Ручной клик по изменённому UI или один API-запрос.

5. 05

   Commit только после зелёного verify.

Если verify падает, в следующий промпт иду с логом ошибки и @ на failing test, а не с «ну попробуй ещё раз».

Cursor git для меня - не отдельная магия редактора, а обычный Git плюс дисциплина scope. Checkpoints в Agent откатывают файлы внутри сессии, но не заменяют историю между вечерами (overview). Я всегда завожу ветку под задачу и commit до первого промпта агента.

Что пишу в brief про git:

## Git
- Ветка: feat/lead-form-validation (от main)
- Scope diff: web/src/components/LeadForm/*, shared/validators/lead.ts
- Не коммитить: .env*, *.pem, credentials.json
- Checkpoints - undo в сессии; постоянная история - только git

Cursor git в промпт иногда дополняю @Branch (Diff with Main) - агент видит, что уже изменено, и не дублирует правки (prompting). Маленькие коммиты после каждого зелёного verify проще ревьюить, чем один ком «агент сделал всё».

Секреты в истории - отдельная боль. Если .env попал в commit, git rm не стирает его из прошлых коммитов. Я учу не paste содержимое .env в чат «для контекста» и держать шаблон в .env.example. Для облачного агента - Secrets tab и Runtime Secret, который redacted в transcript (security).

На разборе видел типичный сценарий: ученик скинул токен бота в промпт, потом запушил ветку на GitHub. Откат - ротация ключа и чистка истории, не «удали строку в Cursor». Профилактика дешевле: brief с запретом, ignore-файлы, никаких секретов в rules.

Пять шагов git-страховки перед Agent:

1. 01

   git checkout -b task/короткое-имя

2. 02

   Commit чистого состояния.

3. 03

   Brief с путями scope и запретом .env*.

4. 04

   Agent + пофайловый просмотр diff.

5. 05

   Merge только после verify и проверки, что в diff нет ключей.

Подробный вечерний сценарий - в первом проекте в Cursor.

Cursor rules - постоянная память репозитория: .cursor/rules/*.mdc, приоритет Team → Project → User (rules). AGENTS.md в корне или подпапке подхватывается автоматически по пути файла. Brief сессии - то, что вы добавляете в конкретный чат: формулировка задачи, @ на файлы, diff, ссылка на тикет.

Я не дублирую в чат то, что уже в rules. Если verify-команды лежат в project rule, в промпт пишу задачу и scope, а не третий раз npm test. Rules держу короче 500 строк - рекомендация из доки. Длинный brief разбиваю: архитектура в AGENTS.md, стилевые мелочи в User Rules, политики команды - в Team Rules на dashboard.

Cursor rules и skills - смежные, но разные механизмы. Skills scoped по paths (skills) - отдельные инструкции под glob. Rules задают базовый контекст на каждую сессию. Разовый промпт из промптов для Cursor не заменяет rule «не трогать deploy/».

Таблица, которую я даю на созвоне:

User Rules не работают в Inline Edit (Cmd/Ctrl+K) - только в Agent Chat (rules). Если привыкли править строку через K, туда контекст не подтянется из User Rules.

Когда @ уместен: вы знаете entrypoint. Когда нет - агент ищет сам (search), но с brief поиск уже не блуждает по monorepo. Синтаксис rules и типы .mdc - в cursor rules.

Ошибки ниже - с разборов, не абстрактный список «будьте внимательны». У каждой пары симптом и конкретный фикс.

Отдельно про cursor context used: если счётчик улетает в красную зону, режьте историю, убирайте лишние @, выносите повторяющееся в rules. Не лечите переполнение новым простынным промптом.

Три истории с поля, без выдуманных цифр. Разбор А: CRM-бот, агент добавил axios, хотя в проекте уже fetch wrapper - в brief не было «не добавлять зависимости». Фикс - одна строка в AGENTS.md и откат package.json. Разбор Б: лендинг на Vite, агент положил API-ключ в src/config.ts «временно» - не было .cursorignore на .env и запрета в rule. Фикс - ключ в env, example в репо, ключ ротирован. Разбор В: monorepo, правки ушли в соседнее app - brief не указал apps/crm как scope. Фикс - globs в rule и @apps/crm/src/... в промпт.

Ниже шаблон, который я даю на наставничестве для вымышленного CRM-бота. Скопируйте в AGENTS.md или в .cursor/rules/project-context.mdc с alwaysApply: true. Подставьте свой стек, не копируйте чужие пути вслепую.

# AGENTS.md - CRM-бот (учебный шаблон, без секретов)

## Проект
- Node 20, Telegraf 4, Prisma, Vitest
- bot/index.ts - entry бота; web/src/main.tsx - entry фронта
- Monorepo: bot/, web/, shared/, deploy/, prisma/
- Не трогать без явного запроса: deploy/, prisma/migrations/, .env*

## Verify
npm run lint && npm test && npm run build

## Scope Agent
- Разрешено: src/handlers/*.ts, web/src/components/LeadForm/*
- Запрещено: новые npm-пакеты, рефактор «заодно», секреты в коде
- Max файлов в одной задаче: 5

## Git
- Работаем в feature-ветке от main
- Commit после зелёного verify
- .env* не в diff и не в чат

## Секреты
- Токены только в .env (в .gitignore и .cursorignore)
- В промпт - имена переменных, не значения
- Terminal/MCP могут читать файлы вне ignore - не просить cat .env

Процесс на 15 минут до первой задачи:

1. 01

   Open Folder на репозиторий.

2. 02

   Создать или обновить AGENTS.md по шаблону выше.

3. 03

   Добавить .cursorignore на секреты и мусор.

4. 04

   Проверить, что verify-команды из brief реально существуют (npm run).

5. 05

   Ветка + commit «до агента».

6. 06

   Промпт: задача + 1-3 @ на файлы + ссылка на scope из brief.

7. 07

   Agent → diff → verify → commit.

Если brief уже есть, а агент всё равно плутает - смотрю три места: конфликт Team Rules с project rule, дубли противоречивых инструкций, слишком широкий auto-search без @. Часто помогает один alwaysApply rule на 30 строк вместо пяти разрозненных .mdc.

По теме в блоге: cursor rules - оформление после brief; cursor agent mode - когда жать Build; как проверять код от ИИ - после diff.