Смысл настройки: AI пишет код в ваших границах
Cursor и Claude Code ускоряют разработку только тогда, когда у проекта есть явный контракт для агента: как устроен репозиторий, какие стандарты кода, что нельзя трогать, как запускать тесты. Без этого модель импровизирует — и вы получаете красивый, но чужой стиль.
Ниже — практическая схема «как программисту пользоваться связкой правильно»: структура папок, файлы правил, примеры и рабочий цикл.
Рекомендуемая структура в репозитории
project-root/
├── .cursor/
│ ├── rules/ # постоянные правила проекта (.mdc)
│ │ ├── project.mdc # alwaysApply: общее
│ │ ├── typescript.mdc # globs: **/*.{ts,tsx}
│ │ ├── java-spring.mdc # globs: **/*.{java,kt}
│ │ └── line-endings.mdc
│ └── skills/ # опционально: project skills
│ └── add-endpoint/
│ └── SKILL.md
├── .claude/ # опционально для Claude Code
│ └── settings / commands # локальные команды/настройки CLI
├── AGENTS.md # краткий «брифинг» для любого агента
├── CLAUDE.md # то же / дополнение под Claude Code
├── README.md # для людей; агенту — вторично
├── docs/
│ ├── architecture.md # границы модулей, ADR-ссылки
│ └── runbook.md # как собрать, тесты, деплой
└── src/ ...
Cursor сильнее опирается на .cursor/rules/*.mdc и контекст открытых файлов. Claude Code хорошо ест AGENTS.md / CLAUDE.md и умеет длинные агентные сессии в терминале. Имеет смысл держать одни и те же правила в обоих местах без противоречий.
Что писать в AGENTS.md (коротко и жёстко)
# AGENTS.md
## Project
- Stack: Java 21, Spring Boot 3, PostgreSQL, Docker Compose
- Package layout: domain / application / adapter (hexagonal)
## Do
- Prefer small PRs; one feature = one change set
- Run: ./mvnw -q test before claiming done
- Match existing naming and folder conventions
## Don't
- Do not commit secrets (.env, keys)
- Do not rewrite unrelated modules
- Do not add new frameworks without asking
## Commands
- Dev: ./mvnw spring-boot:run
- Test: ./mvnw test
- Format: ./mvnw spotless:apply
Это «входной билет» агента. Чем короче и конкретнее — тем меньше галлюцинаций.
Rules в Cursor: формат .mdc
Файлы в .cursor/rules/ с YAML frontmatter:
---
description: Общие правила репозитория
alwaysApply: true
---
# Project defaults
- LF line endings only (never CRLF)
- English identifiers; RU only in user-facing copy / i18n JSON
- Prefer editing existing files over creating parallel ones
- After substantive edits: run the smallest relevant test/build
---
description: TypeScript / Angular conventions
globs: "**/*.{ts,html,scss}"
alwaysApply: false
---
# Angular / TS
- Standalone components; prefer signals over heavy RxJS nesting
- No `any`; use `unknown` + narrowing
- Keep components thin; move logic to services
- Do not introduce NgModules for new code
---
description: Java / Spring Boot service layer
globs: "**/*.{java}"
alwaysApply: false
---
# Java
- Constructor injection only (no field @Autowired)
- Package by feature/domain, not by technical layer alone
- JPA entities: no Lombok @Data; exclude associations from equals/toString
- Validate API input at boundary (Bean Validation)
Правило: alwaysApply — только для коротких глобальных норм (LF, секреты, запрет широких рефакторингов). Всё фреймворк-специфичное — через globs, иначе агент тащит Angular-советы в Java и наоборот.
Skills: повторяемые сценарии разработки
Skill — это инструкция «как сделать типовую задачу», а не энциклопедия. Кладите в .cursor/skills/<name>/SKILL.md (проект) или в user skills.
---
name: add-rest-endpoint
description: Add a Spring REST endpoint with DTO, validation, service method, and test.
---
# Add REST endpoint
1. Confirm resource name and HTTP verb with existing controllers style.
2. Add request/response DTO with Bean Validation.
3. Wire service method; no business logic in controller.
4. Add @WebMvcTest or slice test mirroring neighbors.
5. Run ./mvnw -Dtest=...Test test and report results.
Хорошие skills: «добавить endpoint», «новый Flyway-скрипт», «починить flaky test», «сгенерировать OpenAPI-compatible DTO». Плохие: «как писать весь Java» на 40 экранов.
Как ставить задачи агенту (разработка)
Формула промпта:
- Цель — что должно появиться в поведении/API.
- Границы — какие файлы/модули можно трогать.
- Критерий готовности — тесты, команда проверки.
- Антицели — что не делать.
Добавь GET /api/orders/{id} в модуле orders.
Стек и стиль — как в OrderController.
Не трогай auth и billing.
DTO + сервисный метод + тест.
Готово = ./mvnw -Dtest=OrderControllerTest test зелёный.
В Cursor удобно править дифф в IDE; в Claude Code — длинные серии «исследуй → правь → прогони maven/npm». Часто оптимально: Claude Code на исследование и массовые правки, Cursor — на точечный рефакторинг и ревью.
docs/architecture.md — чтобы агент не ломал границы
# Architecture
## Modules
- orders: order lifecycle, no direct payment calls
- payments: talks to PSP; publishes domain events
- identity: JWT validation only
## Invariants
- No shared DB tables across modules
- Cross-module calls only via application services / events
Без этого AI с радостью «упростит» и сделает прямую зависимость payments → orders через entity.
Антипаттерны
- Правила на 2000 строк «про всё» — агент теряет фокус.
- Противоречие README vs AGENTS.md vs rules.
- Промпт «перепиши проект красиво» без scope.
- Accept всего диффа без прогона тестов.
- Секреты в чате / в правилах / в skills.
Минимальный чеклист перед стартом фичи
- Есть
AGENTS.mdс командами test/build. - Есть 1–3 коротких
.cursor/rulesпод стек. - Задача сформулирована с границами и DoD.
- После агента — diff review + тесты.
- Если ошибка повторилась дважды — дописать rule/skill, а не только ругаться в чате.
Вывод
Правильно пользоваться Cursor и Claude Code в разработке — значит превратить репозиторий в среду с явными правилами: структура .cursor/rules, краткий AGENTS.md, точечные skills, архитектурные инварианты в docs/. Тогда AI ускоряет кодогенерацию внутри вашего стандарта, а вы остаётесь архитектором: ставите задачу, режете scope, принимаете дифф. Без файлов правил вы не «используете AI», вы играете в лотерею стиля.