CLAUDE.md: The Complete Guide for Claude Code

What is CLAUDE.md?

CLAUDE.md is a markdown file that gives Claude Code persistent context about your project. When Claude Code starts a session, it reads your CLAUDE.md and uses those instructions to guide every action it takes — from generating code to running commands to making architectural decisions.

Unlike chat messages that vanish after a conversation, CLAUDE.md persists. It's the difference between telling a new hire the same instructions every morning and giving them an onboarding document.

Where CLAUDE.md files live

Claude Code reads instructions from multiple locations, with a clear hierarchy:

Claude Code merges all applicable files, with project-level instructions taking precedence over global ones. The .claude/skills/ and .claude/rules/ directories let you organize instructions into focused, modular files — similar to how Cursor uses .cursor/rules/.

Writing effective project instructions

A good CLAUDE.md is specific, structured, and includes examples. Here's a template that works for most projects:

# Project: my-app

## Tech stack
- Next.js 15 (App Router)
- TypeScript 5.7 (strict mode)
- Tailwind CSS v4
- Drizzle ORM + PostgreSQL
- Vitest for testing

## Architecture
- All API routes go in src/app/api/
- Components in src/components/ (named exports only)
- Database schema in src/schema/
- Shared utilities in src/lib/

## Conventions
- Use snake_case for database columns
- Use camelCase for TypeScript variables
- Every API route returns { data, error } shape
- Always handle errors with try/catch

## Commands
- Dev server: pnpm dev
- Type check: pnpm type-check
- Tests: pnpm test
- Build: pnpm build

## Do NOT
- Never use the Pages Router
- Never use default exports for components
- Never commit .env files
- Never use any as a type

Tips for better instructions

• Be explicit about your tech stack — Claude Code can infer a lot from your codebase, but explicit instructions prevent mismatches
• Include build commands — Claude Code runs terminal commands autonomously. Telling it exactly how to build, test, and lint prevents wasted turns
• Show patterns, not just rules — "Use named exports" is good. Showing an actual component example is better
• Set boundaries — The "Do NOT" section prevents Claude Code from making common mistakes specific to your project

Advanced patterns

Conditional context with skills

Instead of one massive CLAUDE.md, split instructions into focused files in .claude/skills/:

.claude/
  CLAUDE.md              # Core project info, tech stack
  skills/
    api-patterns.md      # API route conventions
    testing.md           # Test writing patterns
    database.md          # Schema and migration rules
    components.md        # React component patterns

Claude Code loads all files in the skills directory automatically. This keeps each file focused and easy to maintain.

Rules for governance

The .claude/rules/ directory is for constraints and governance — things that must always be enforced:

# Security rules

- Never log sensitive data (tokens, passwords, PII)
- Always validate user input at API boundaries
- Use parameterized queries — never string concatenation for SQL
- Check authorization before every data mutation

Linking to documentation

You can reference other files in your CLAUDE.md:

## Reference docs
- API design: see docs/api-design.md
- Database schema: see src/schema/README.md
- Component library: see src/components/README.md

Claude Code will read these files when it needs context, keeping your CLAUDE.md concise while providing deep reference material.

From CLAUDE.md to shareable skills

CLAUDE.md files are great for a single project. But when your team works across multiple repositories, you end up copying the same instructions everywhere — API conventions, testing patterns, security rules.

localskills.sh turns your CLAUDE.md content into shareable, versioned skills:

# Install the CLI
npm install -g @localskills/cli

# Publish your existing Claude Code skills
localskills publish

The CLI automatically detects files in .claude/skills/ and .claude/rules/ and publishes them to your team's registry. Other developers install them with one command:

localskills install your-team/api-conventions --target claude

Every update creates a new version. You can roll back from the dashboard if something breaks. Analytics show you how many team members have installed each skill.

Using CLAUDE.md instructions in Cursor and Windsurf

The content you write for CLAUDE.md works great in Claude Code, but what about developers on your team who use Cursor or Windsurf?

With localskills.sh, one published skill installs into all 8 supported tools:

# Install into Claude Code, Cursor, and Windsurf
localskills install your-team/api-conventions --target claude cursor windsurf

The CLI handles format differences — the same content becomes a .md file in .claude/skills/, an .mdc file in .cursor/rules/, and the right format for Windsurf. No manual conversion needed.

Read more about the fragmentation problem across AI tools or see a full comparison of Cursor, Claude Code, and Windsurf.

---

Ready to turn your CLAUDE.md into shareable skills? Get started with localskills.sh.

npm install -g @localskills/cli
localskills login
localskills publish