The Complete Guide to AI Coding Rules: .cursorrules, CLAUDE.md & More

AI coding assistants are transforming how developers write software. But out of the box, they don’t know your project’s conventions, preferred patterns, or architectural decisions. That’s where AI coding rules files come in — configuration files that sit in your repository and tell the AI how to behave when working on your code.

This guide covers every major format: .cursorrules, CLAUDE.md, .windsurfrules, and .github/copilot-instructions.md. You’ll learn what to put in them, see real examples, and pick up practical tips for getting the most out of AI-assisted development.

Why AI Coding Rules Matter

Without explicit rules, AI coding assistants rely on generic training data. The result: inconsistent code style, wrong framework patterns, and suggestions that don’t match your project. Here’s what rules files solve:

• Consistent code style — enforce naming conventions, formatting, and import ordering across every AI-generated suggestion
• Project-specific patterns — tell the AI to use your state management library, your error handling approach, your testing framework
• Architectural guardrails — prevent the AI from introducing patterns you’ve deliberately avoided (e.g., “never use class components” or “no ORM, raw SQL only”)
• Onboarding acceleration — new team members get AI suggestions that already match your codebase from day one
• Reduced review friction — AI-generated code that follows your rules needs fewer corrections in code review

Think of rules files as documentation that both humans and AI can read. They’re a single source of truth for “how we write code here.”

AI Rule File Formats: A Complete Overview

Every major AI coding tool now supports some form of project-level configuration. Here’s the landscape:

.cursorrules (Cursor IDE)

Location: .cursorrules in your project root

Cursor reads this file automatically and includes its contents as system-level context for all AI interactions within the project. It supports plain text or markdown.

# Project: MyApp
# Framework: React 18 + TypeScript 5
# Styling: Tailwind CSS

## Conventions
- Use functional components with hooks
- Prefer named exports over default exports
- Use `cn()` utility for conditional class names

Cursor also supports .cursor/rules/ directory for modular rule files scoped to specific file patterns. Each file in that directory can target different parts of your codebase.

CLAUDE.md (Claude Code CLI)

Location: CLAUDE.md in your project root (also reads from ~/.claude/CLAUDE.md for global rules)

Claude Code, Anthropic’s official CLI agent, reads CLAUDE.md automatically when you start a session. It also reads CLAUDE.md files in subdirectories for context-specific instructions. This file uses markdown format.

# Project Overview
Backend API built with Python 3.12 + FastAPI

## Development Commands
- `make dev` -- start development server
- `make test` -- run pytest suite
- `make lint` -- run ruff linter

## Conventions
- Type hints on all function signatures
- Pydantic models for all request/response schemas
- Async handlers by default

A key difference: CLAUDE.md is designed for an agentic coding workflow where the AI runs commands, edits files, and manages entire tasks — so including build commands and project structure is especially useful.

.windsurfrules (Windsurf / Codeium)

Location: .windsurfrules in your project root

Windsurf (formerly Codeium’s IDE) reads this file for project-level AI customization. The format is similar to .cursorrules — plain text or markdown with instructions for the AI.

# Windsurf Rules for MyApp
- Language: TypeScript (strict mode)
- Always use early returns to reduce nesting
- Prefer composition over inheritance
- Write JSDoc comments for all public functions

.github/copilot-instructions.md (GitHub Copilot)

Location: .github/copilot-instructions.md

GitHub Copilot reads this markdown file to customize suggestions across VS Code, JetBrains, and other supported editors. This is the newest format, introduced in late 2024.

## Code Style
- Use ESM imports, never CommonJS require()
- Prefer `const` over `let`, never use `var`
- Use template literals instead of string concatenation

## Testing
- Use Vitest for unit tests
- Use Testing Library for component tests
- Always include at least one happy path and one error case

For a detailed breakdown of how these editors compare, check out our Cursor vs Copilot vs Windsurf comparison.

What to Include in Your Rules File

Regardless of format, effective rules files cover these areas:

1. Project Identity

State the language, framework, and major dependencies upfront. This gives the AI immediate context.

2. Code Style and Conventions

Naming conventions (camelCase, snake_case), file naming patterns, import ordering, and formatting preferences. Be explicit about choices your linter doesn’t enforce.

3. Architecture Patterns

Component structure, state management approach, data fetching patterns, folder organization. Tell the AI how you build things, not just what you build.

4. Testing Requirements

Which test framework, what coverage expectations, preferred assertion style, mocking approach. AI assistants generate much better tests when they know your patterns.

5. Error Handling

How to handle errors (Result types? try/catch? error boundaries?), logging conventions, and validation approach.

6. Things to Avoid

Explicitly list anti-patterns. “Never use any type” is more effective than “use proper types.” Negative rules prevent the most common AI mistakes.

Example: .cursorrules for React + TypeScript

# Project: E-commerce Dashboard
# Stack: React 18, TypeScript 5.3, Vite, Tailwind CSS 3, Zustand, React Query

## Code Style
- Functional components only, no class components
- Named exports for components: `export function ProductCard() {}`
- File naming: PascalCase for components (ProductCard.tsx), camelCase for utilities (formatPrice.ts)
- Use `interface` for component props, `type` for unions and intersections
- Prefer early returns to reduce nesting

## Component Structure
- One component per file
- Props interface directly above the component
- Hooks at the top of the component body
- Event handlers prefixed with `handle`: `handleSubmit`, `handleClick`

## State Management
- Zustand for global state (stores in src/stores/)
- React Query for server state (hooks in src/hooks/queries/)
- Local state with useState for UI-only state
- Never use useEffect for data fetching -- use React Query

## Styling
- Tailwind utility classes only, no CSS modules
- Use `cn()` from src/lib/utils for conditional classes
- Responsive: mobile-first (sm:, md:, lg:)
- Dark mode: use `dark:` variant

## Testing
- Vitest + React Testing Library
- Test files colocated: `Component.test.tsx` next to `Component.tsx`
- Test behavior, not implementation
- Mock API calls with MSW

## Do NOT
- Use `any` type -- use `unknown` and narrow
- Use barrel exports (index.ts re-exports)
- Import from @mui or other UI libraries -- we use shadcn/ui + Tailwind
- Use useEffect for derived state -- use useMemo instead

Example: CLAUDE.md for Python + FastAPI

# Invoice Processing API

## Stack
Python 3.12, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, Alembic, Pydantic v2

## Commands
- `uv run fastapi dev` -- start dev server on port 8000
- `uv run pytest` -- run test suite
- `uv run ruff check .` -- lint
- `uv run ruff format .` -- format
- `alembic revision --autogenerate -m "description"` -- create migration
- `alembic upgrade head` -- apply migrations

## Project Structure
- `app/api/` -- route handlers (one file per resource)
- `app/models/` -- SQLAlchemy models
- `app/schemas/` -- Pydantic request/response models
- `app/services/` -- business logic layer
- `app/core/` -- config, security, dependencies

## Conventions
- All route handlers must be async
- Type hints on every function signature and return type
- Pydantic models for all request bodies and responses
- Service layer between routes and database -- routes should not contain business logic
- Use `Depends()` for dependency injection
- Database sessions via `async with` context manager

## Error Handling
- Raise `HTTPException` in route handlers only
- Services raise custom exceptions (defined in `app/core/exceptions.py`)
- All 4xx/5xx responses use the `ErrorResponse` schema

## Testing
- pytest with async support (pytest-asyncio)
- Use factory functions in `tests/factories.py` for test data
- Each test gets a fresh database transaction (rolled back after)
- Name tests: `test_<action>_<condition>_<expected>`

## Do NOT
- Use synchronous database calls
- Put business logic in route handlers
- Use `*` imports
- Commit `.env` files -- use `.env.example` as template

Tips for Writing Effective Rules

Be specific, not vague. “Write clean code” is useless. “Use early returns to avoid nesting beyond 3 levels” is actionable.

Include short examples. A 2-line code snippet communicates more than a paragraph of description. Show the pattern you want, not just the name.

State the negative. “Do NOT” sections are surprisingly effective. AI models respond well to explicit prohibitions because they eliminate entire categories of wrong answers.

Keep it updated. Rules files are living documents. When you adopt a new library or change a convention, update the rules file in the same PR. Stale rules cause more confusion than no rules.

Start small, iterate. Begin with 10-15 rules that address your biggest pain points. Add more as you notice patterns in the AI’s mistakes. Over-engineered rules files get ignored.

Version control them. Rules files belong in your repository, committed alongside your code. They’re part of your project’s developer experience.

One Source, Every Format

Maintaining separate rules files for Cursor, Claude Code, Windsurf, and Copilot is tedious. The content is 90% identical — only the file name and location differ.

Our AI Coding Rules Generator lets you define your project’s conventions once and export to every format: .cursorrules, CLAUDE.md, .windsurfrules, and .github/copilot-instructions.md. Fill in your stack, conventions, and preferences, then download all four files.

If you specifically need Cursor configuration, the Cursor Rules Generator provides a focused experience with Cursor-specific features like directory-scoped rules and glob pattern targeting.

Conclusion

AI coding rules files are one of the highest-leverage investments you can make in your development workflow. A well-crafted rules file turns a generic AI assistant into one that understands your project’s architecture, follows your conventions, and generates code that fits naturally into your codebase.

Start with one file for whichever AI tool you use most. Add your top 10 conventions. Commit it. Then iterate as you discover what the AI gets wrong. Within a week, you’ll wonder how you ever coded with AI without one.