Migrate from Cursor Rules

If you're coming from Cursor (or any tool that uses a single .cursorrules / .cursor/rules/*.md file), the kit's structure looks unfamiliar. This recipe maps your existing rules into the kit's layout.

TL;DR mapping

Step 1 — Install the kit

npx @tansuasici/claude-code-kit init

Don't delete .cursorrules yet. You'll port content out of it gradually.

Step 2 — Decide what stays "always loaded" vs "on demand"

The kit splits agent context into tiers (see Session Boot):

• Tier 1 (always): CODEBASE_MAP.md, CLAUDE.project.md
• Tier 2 (if continuing): tasks/handoff-*.md, tasks/todo.md
• Tier 3 (on demand): tasks/lessons.md, tasks/decisions.md, agent docs

In .cursorrules everything is loaded every prompt — that's fine for short rules, expensive for long ones.

For each rule in .cursorrules, decide:

• Always? → put in CLAUDE.project.md
• Only when working on X? → put in agent_docs/project/<X>.md, link from CLAUDE.project.md's "Additional Agent Docs"

This split alone saves significant token cost on every session.

Step 3 — Port stack rules

Most .cursorrules files are 80% stack rules. Move them straight into CLAUDE.project.md under ## Stack-Specific Rules:

Before (.cursorrules):

This is a Next.js 16 project. Use Server Components by default. Add 'use client' only when needed.

API responses follow the envelope pattern: { data, error, meta }.

All forms use react-hook-form with Zod schemas.

After (CLAUDE.project.md):

## Stack-Specific Rules

- **Server Components first** — only add `'use client'` when you need interactivity, browser APIs, or local state.
- **API responses use the envelope pattern**: `{ data: T, error: { code, message } | null, meta?: object }`. Never return raw data.
- **All forms** use `react-hook-form` with Zod schemas. No uncontrolled forms.

See the full Customize CLAUDE.project.md recipe for more examples.

Step 4 — Port "always do X" / "never do Y" rules

Two paths depending on enforcement strictness:

Soft enforcement (advisory) → CLAUDE.project.md:

## Project-Specific Protected Changes

Stop and request approval before:
- Modifying sync conflict resolution logic
- IndexedDB schema version bumps

Hard enforcement (deterministic block) → .claude/hooks/project/:

If you have a rule like "never edit dist/" and you want to physically prevent the agent from doing it, add a project-specific hook:

# .claude/hooks/project/protect-dist.sh
#!/usr/bin/env bash
input=$(cat)
file=$(echo "$input" | grep -oE '"file_path":"[^"]+"' | cut -d'"' -f4)

if [[ "$file" == */dist/* ]]; then
  echo "BLOCKED: dist/ is generated, edit source files instead" >&2
  exit 2
fi

Then wire it up in .claude/settings.json under PreToolUse matcher Edit|Write. See the Hooks guide.

Step 5 — Port "auto-attached" rules (Cursor's description: field)

Cursor's description: on a rule file makes it auto-attach when relevant. The kit's equivalent is skills:

---
name: api-route-review
description: Reviews API route handlers for the envelope response pattern, error handling, validation via Zod, and authentication checks. Run after any new route is added.
user-invocable: true
---

# API Route Review

[full skill content]

Skills load automatically via Claude Code's semantic matching against the description field. See Add a project-specific skill.

Step 6 — Decide what to do with .cursorrules

You have two options:

Option A — Delete it

Once everything is ported, the file is dead weight. git rm .cursorrules and commit.

Option B — Keep it as a generated mirror

If you have teammates still using Cursor, regenerate .cursorrules from the kit's source of truth:

./scripts/convert.sh cursor

This produces a .cursorrules (and Windsurf / Aider equivalents) from your CLAUDE.md + CLAUDE.project.md. Run it whenever you update kit content. Don't edit .cursorrules directly anymore — it's generated.

What you gain over .cursorrules

• Tiered context loading → less tokens per session
• Deterministic hooks → some rules are physically enforced, not advisory
• Skill system → richer than rules, includes process/output format/examples
• Project overlay separation → CLAUDE.project.md survives --upgrade cleanly
• Cross-tool export → one source, multiple AI tools (Cursor, Windsurf, Aider, Copilot, etc.)

What you lose

Honest list:

• Cursor-specific UI integrations (rule attachment indicator, etc.) don't exist in Claude Code
• Cursor's @ mention syntax for files isn't a kit feature
• The "rules editor" UI — kit edits are file-based, no GUI

If those matter, run both side-by-side; the kit doesn't conflict with .cursorrules files.

Verification

After migration:

./scripts/validate.sh CODEBASE_MAP.md   # placeholders filled
./scripts/validate-skills.sh            # any new project skills validate
./scripts/doctor.sh                     # installation healthy

In a Claude Code session, run a task that should trigger your migrated rules. If the rule isn't applied, it's probably:

• Too vague (rewrite more concretely)
• In the wrong tier (move to CLAUDE.project.md for always-loaded)
• Conflicting with kit defaults (overlay wins, but only if it's actually in the overlay file)

Related

• CLAUDE.md guide — anatomy of the main rules file
• Customize CLAUDE.project.md — where most ported rules end up
• Add a project-specific skill — for richer auto-attached rules
• Hooks guide — for deterministic enforcement