AI Rules Configuration

.cursorrules, CLAUDE.md, and Skills are three complementary, not interchangeable config formats. Sort out what each is good at — and what it isn't — before mixing them. Otherwise you end up writing the same rule three times and nobody on the team will keep them in sync.

If you've never written one, start with Cursor Rules Intro and Claude Code Skills. This page covers how to divide responsibility across the three formats and keep them aligned across a team.

What each format is actually for

The key difference:

• .cursorrules and CLAUDE.md are always-on context — write too much and you blow your token budget every session
• Skills are lazy-loaded — only read when the AI decides it needs them, so you can park lots of SOPs without polluting context
• .cursor/rules/*.mdc sits in between, matching by glob

What goes where

The most common mistake is dumping everything into CLAUDE.md until it's 2,000 lines and burns 5K tokens per session. Better split:

Team sync strategy

Rules only matter if they're committed to git. Three layers, three approaches:

# 1) Project-level — all in
git add .cursorrules .cursor/rules/ CLAUDE.md
git commit -m "chore: update AI rules for new auth pattern"

# 2) Project Skills — committed under .claude/skills/
git add .claude/skills/deploy-prod/
git commit -m "skill: add prod deploy SOP"

# 3) User-level — never committed
# ~/.claude/CLAUDE.md and ~/.claude/skills/ are personal; don't commit

Typical .gitignore additions:

# AI cache + personal settings stay local
.claude/settings.local.json
.cursor/settings.local.json

# But project-level rules MUST be committed:
# !.cursorrules
# !.cursor/rules/
# !CLAUDE.md
# !.claude/skills/

Mandatory review: changes to CLAUDE.md or .cursorrules must go through PR — no direct pushes. These files affect every engineer's AI behavior, equivalent to changing lint config; the team needs to agree.

Real example: how JR Academy layers it

~/.claude/CLAUDE.md                         # Personal (~50 lines)
└─ "use bun not npm"
└─ "auto-push after commit"
└─ Projects registry

jr-academy-ai/CLAUDE.md                     # Project laws (~600 lines)
└─ ABSOLUTE RULES (rm policy, git safety)
└─ Service architecture (600-line cap, single responsibility)
└─ ID-First Principle (post-incident learnings)
└─ Anti-Template Content Rule
└─ MongoDB / Auth / Testing constraints

.cursor/rules/frontend.mdc                  # glob: *.tsx
└─ styled-components rules
└─ z-index conventions

.claude/skills/bootcamp-sync/               # Complex SOP (~400 lines)
└─ SKILL.md: sync curriculum/ → prod
└─ scripts/diff-check.ts
└─ templates/

.claude/skills/lesson-design/
└─ SKILL.md

Result: a typical session loads ~8K of context (the CLAUDE.md); when a deploy or sync is needed, the AI auto-triggers the matching skill and pulls in another 5-10K. About 60% cheaper than putting everything in CLAUDE.md.

Common traps

• Rules written too abstractly — "code should be clean and maintainable" is dead weight; AI can't act on it. Write "split any service file over 600 lines" instead.
• Conflicting rules — .cursorrules says "use tabs", CLAUDE.md says "4 spaces", AI behavior becomes unpredictable. Audit periodically.
• Skill trigger conditions are vague — if SKILL.md description says "helps with code review", the AI will never auto-trigger it. Write "auto-triggers on PR review, takes a PR diff, outputs a 5-category issue list."
• Rules go stale — team locked in "use React 17" six months ago, you've since upgraded to React 19, AI still writes legacy patterns. Audit quarterly.

Next

• MCP Development Best Practices — extending AI capabilities into external systems
• AI Rules Continuous Improvement — versioning and iterating on rules
• Claude Code Context Management — controlling token cost of loaded rules