How Developers Should Set Up Cursor and Claude Code: Rules, Skills, Repo Layout

The point of setup: AI codes inside your boundaries

Cursor and Claude Code speed up development only when the project has an explicit contract for the agent: repo layout, coding standards, untouchable areas, how to run tests. Without that the model improvises — and you get polished code in a foreign style.

Below is a practical “how a developer should use the pair”: folder structure, rule files, examples, and a working loop.

Recommended repository layout

project-root/
├── .cursor/
│   ├── rules/                 # durable project rules (.mdc)
│   │   ├── project.mdc        # alwaysApply: globals
│   │   ├── typescript.mdc     # globs: **/*.{ts,tsx}
│   │   ├── java-spring.mdc    # globs: **/*.{java,kt}
│   │   └── line-endings.mdc
│   └── skills/                # optional project skills
│       └── add-endpoint/
│           └── SKILL.md
├── .claude/                   # optional Claude Code extras
│   └── settings / commands
├── AGENTS.md                  # short briefing for any agent
├── CLAUDE.md                  # same / Claude-focused companion
├── README.md                  # for humans; secondary for agents
├── docs/
│   ├── architecture.md        # module boundaries, ADR links
│   └── runbook.md             # build, test, deploy
└── src/ ...

Cursor leans on .cursor/rules/*.mdc and open-file context. Claude Code consumes AGENTS.md / CLAUDE.md well and shines in long terminal agent sessions. Keep the same rules in both places without contradictions.

What to put in AGENTS.md (short and strict)

# 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

This is the agent’s entry ticket. Shorter and more concrete means fewer hallucinations.

Cursor rules: .mdc format

Files under .cursor/rules/ with YAML frontmatter:

---
description: Repository-wide defaults
alwaysApply: true
---

# Project defaults

- LF line endings only (never CRLF)
- English identifiers; localized copy only in i18n resources
- 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 the boundary (Bean Validation)

Rule of thumb: alwaysApply only for short global norms (LF, secrets, no drive-by refactors). Framework specifics go through globs, otherwise the agent drags Angular advice into Java and vice versa.

Skills: repeatable development scenarios

A skill teaches “how to do a typical task”, not an encyclopedia. Put it in .cursor/skills/<name>/SKILL.md (project) or in 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 against existing controllers.
2. Add request/response DTO with Bean Validation.
3. Wire a service method; no business logic in the controller.
4. Add a @WebMvcTest or slice test mirroring neighbors.
5. Run ./mvnw -Dtest=...Test test and report results.

Good skills: “add endpoint”, “new Flyway script”, “fix flaky test”, “OpenAPI-compatible DTO”. Bad skills: “how to write all of Java” in 40 screens.

How to task the agent (development)

Prompt formula:

1. Goal — what behavior/API must appear.
2. Boundaries — which files/modules may change.
3. Definition of done — tests, verification command.
4. Anti-goals — what not to do.

Add GET /api/orders/{id} in the orders module.
Match OrderController style.
Do not touch auth or billing.
DTO + service method + test.
Done = ./mvnw -Dtest=OrderControllerTest test is green.

Cursor is great for in-IDE diffs; Claude Code for long “explore → edit → run maven/npm” loops. Often optimal: Claude Code for exploration and bulk edits, Cursor for precise refactor and review.

docs/architecture.md — so the agent does not break boundaries

# 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

Without this, AI happily “simplifies” and wires payments → orders through entities.

Anti-patterns

• 2000-line “rules about everything” — the agent loses focus.
• Contradictions between README, AGENTS.md, and rules.
• “Rewrite the project nicely” with no scope.
• Accepting the full diff without running tests.
• Secrets in chat / rules / skills.

Minimal checklist before a feature

1. AGENTS.md with test/build commands exists.
2. One to three short .cursor/rules for the stack.
3. The task has boundaries and a DoD.
4. After the agent: diff review + tests.
5. If the same mistake repeats twice — add a rule/skill, do not only scold the chat.

Takeaway

Using Cursor and Claude Code well in development means turning the repository into an environment with explicit rules: .cursor/rules, a short AGENTS.md, focused skills, and architectural invariants in docs/. Then AI accelerates codegen inside your standard, and you stay the architect: set the task, cut scope, accept the diff. Without rule files you are not “using AI” — you are playing a style lottery.