Claude Code custom instructions: how to make Claude Code follow your rules every time

Claude Code does not have a settings panel where you configure custom instructions. There is no gear icon, no "system prompt" field, no preferences screen. The custom instructions system is a single markdown file in your project root: CLAUDE.md.

Every time you start a Claude Code session in a project, it reads that file first. Everything in it applies to the entire conversation. Get this file right and Claude follows your rules on the first try, every time. Leave it empty and you spend half your session correcting behavior that should have been automatic.

What CLAUDE.md actually is

CLAUDE.md is a plain markdown file. Claude Code reads it at session start and injects the contents as persistent context. There is nothing special about the format; you write it the same way you would write any other technical documentation.

The difference from a README is the audience. A README explains your project to humans. CLAUDE.md explains your project to Claude, with a focus on what Claude specifically needs to know to work correctly: where files live, which commands to run, what patterns to follow, and what to avoid.

Claude Code supports three locations for these files:

• ~/.claude/CLAUDE.md — Global rules that apply to every project on your machine
• CLAUDE.md — Project-level rules in your repo root
• .claude/rules/*.md — Section-specific rules loaded based on working directory context

Most teams start with just the project-level file. The global file is useful for personal preferences that travel across projects (your preferred code style, output format habits). The rules directory is for larger projects where you need different rules for different parts of the codebase.

Without CLAUDE.md vs with CLAUDE.md

Here is what a typical Claude Code session looks like without any custom instructions:

You: Add a new API endpoint for user preferences

Claude: I'll create the endpoint. Here's the code:

// Added to routes.js
app.get('/api/user/preferences', async (req, res) => {
  const userId = req.query.userId;
  ...
})

Three problems: wrong file (your project uses a router factory pattern, not raw Express), wrong location (endpoints go in src/routes/ not the root), and missing the auth middleware that every endpoint needs.

With a CLAUDE.md that covers these conventions:

You: Add a new API endpoint for user preferences

Claude: I'll add the endpoint following your router factory pattern
with the auth middleware applied. Creating src/routes/preferences.js...

Same request. Right output on the first try. The difference is context, not capability.

What to put in your CLAUDE.md

Project overview

Start with two or three sentences about what the project is and what stack it uses. Claude does not need a sales pitch; it needs to know whether this is a Next.js app, a Python CLI, a Go microservice, or something else entirely.

# My Project

A REST API for managing construction project timesheets.
Stack: Node.js, Express, PostgreSQL, TypeScript.
Deployed to Railway via GitHub Actions.

File structure

Tell Claude where things live. This prevents it from creating files in the wrong location, which is one of the most common problems in projects with non-standard directory structures.

## File Structure

- src/routes/       — Express route handlers (one file per resource)
- src/services/     — Business logic (no direct DB access here)
- src/models/       — Database queries and schema definitions
- src/middleware/   — Shared middleware (auth, validation, logging)
- tests/            — Jest tests, mirroring src/ structure
- scripts/          — One-off scripts, not part of the app

Coding conventions

Be specific. "Use best practices" does nothing. "Always use named exports, never default exports" changes actual output.

## Conventions

- TypeScript strict mode is enabled. No implicit any.
- Named exports only, no default exports.
- Use async/await, not .then() chains.
- Error handling: throw errors up to the route handler,
  never swallow them in services.
- Database queries go in model files only.
  Services call models, routes call services.
- All new routes need the authenticateUser middleware applied.

Testing setup

If Claude does not know how your tests work, it will either write tests in the wrong format or skip writing them entirely. Give it the framework, the test runner command, and any important patterns.

## Testing

Framework: Jest with ts-jest
Run tests: npm test
Run single file: npx jest tests/routes/preferences.test.ts
Coverage: npm run test:coverage

Test files mirror src/ structure.
A new file at src/routes/preferences.ts
gets a test at tests/routes/preferences.test.ts.
Use supertest for route testing, not direct function calls.

Build and deploy commands

One section, a few lines. Claude needs to know how to build the project, how to run it locally, and what to check before it considers a task done.

## Commands

Build: npm run build
Dev: npm run dev (runs on port 3001)
Lint: npm run lint
Type check: npx tsc --noEmit
Deploy: push to main, GitHub Actions handles the rest

Guardrails

Guardrails are the most underused section. They define what Claude should never do, which is often more important than telling it what to do. Common ones:

## Guardrails

- Never delete files directly. Move to .trash/ using mv instead.
- Never run database migrations without confirming the migration plan first.
- Never commit .env files or expose API keys in output.
- Never push to main directly. All changes go through pull requests.
- Do not install new dependencies without asking first.

The "never delete files" guardrail alone has saved countless developers from accidental data loss. Claude is fast, and fast plus destructive is a bad combination without guardrails.

Directory-specific rules with .claude/rules/

For larger codebases, a single CLAUDE.md can get unwieldy. Claude Code supports a .claude/rules/ directory where you can put separate rule files for different parts of your project.

.claude/
  rules/
    frontend.md      — React component conventions, CSS rules
    api.md           — API design, authentication patterns
    database.md      — Migration rules, query patterns
    deployment.md    — Deploy checklist, environment specifics

These files are loaded in addition to the root CLAUDE.md, not instead of it. Use them when a section is growing large enough that it would distract from the main file, or when different team members work in different parts of the codebase and need different context loaded.

The naming is up to you. Claude Code reads all files in .claude/rules/ and loads them as additional context. There is no automatic filtering by directory — they are all loaded together.

Global instructions across all projects

Some rules apply everywhere. Your personal code style preferences, output format habits, how you want Claude to communicate. These go in ~/.claude/CLAUDE.md.

# Global Claude Instructions

## Output format
- Keep explanations short. Show code first, explain after if needed.
- Do not narrate what you're about to do. Just do it.
- When you're not sure about something, ask before doing.

## Code style
- Prefer explicit over clever.
- Comments explain why, not what.
- Variable names should be unambiguous even without context.

The project-level CLAUDE.md takes precedence over the global file when there are conflicts. Use the global file for defaults, the project file for overrides.

These work across other AI coding tools too

CLAUDE.md is Claude Code's format, but every major AI coding tool has the same concept:

• Cursor reads .cursorrules in your project root
• Gemini CLI reads GEMINI.md
• GitHub Copilot / Codex reads AGENTS.md

The content is 80% identical across formats: project overview, file structure, conventions, testing setup, commands. The remaining 20% is tool-specific directives. If you use multiple tools, you end up maintaining four files that say roughly the same thing, slowly drifting out of sync as you update one and forget the others.

The clean solution is to pick one format as your source, then generate the others. Or use a tool that handles the translation automatically. The worst approach is updating them manually one at a time.

Common mistakes and how to avoid them

Too vague

"Follow best practices" and "write clean code" are not instructions. Claude already tries to do those things. Instructions that change behavior are specific: "use camelCase for variables, PascalCase for classes, SCREAMING_SNAKE_CASE for constants," not "follow naming conventions."

Too long

A 2000-word CLAUDE.md with exhaustive documentation of every edge case is not better than a focused 400-word file. Claude reads the whole thing on every session start. Bloated context dilutes the signal. Put the important rules first and keep everything else short.

Out of date

Your CLAUDE.md is documentation. It rots the same way all documentation rots. Add "update CLAUDE.md" to your PR checklist for any change that affects conventions, structure, or commands. A file that tells Claude your test runner is Jest when you migrated to Vitest six months ago is worse than no file at all.

No guardrails

Guardrails are the section most developers skip. They are also the most important section. Write down the things you never want Claude to do automatically. You will be glad you did the first time it would have done one of them.

A minimal starting template

If you have nothing in your CLAUDE.md yet, start here and expand as you find gaps:

# Project Name

One sentence describing what this project is.
Stack: [languages, frameworks, databases].

## File Structure

[list your key directories and what goes in them]

## Conventions

[3-5 specific rules about code style and patterns]

## Commands

Build: [command]
Test: [command]
Dev: [command]

## Guardrails

- Never delete files directly. Use mv to .trash/.
- Never commit credentials or .env files.
- [add your project-specific rules here]

For more on structuring these files effectively, see the complete guide to Claude Code cost optimization which covers how context file structure affects both quality and token spend.