Writing Your First CLAUDE.md Rules File

How to Generate a Starter File

The fastest way to start is the /init command. Open Claude Code in your project directory and run it.

# Inside your project directory
$ claude

# Once Claude Code starts, type:
/init

Claude examines your codebase, detects your build system, test framework, and code patterns, then generates a CLAUDE.md tailored to what it finds. The generated file is a starting point. Review every line, cut what is obvious, and add what is missing from how you actually work.

If you prefer writing from scratch, create a file named CLAUDE.md in your project root. The filename is case-sensitive. It must be exactly CLAUDE.md, uppercase, with a lowercase .md extension.

What Should Your CLAUDE.md Include?

A productive CLAUDE.md covers four things. Project context, build commands, code conventions, and restrictions. Here is a complete example for a TypeScript project:

# CLAUDE.md

## Project
Next.js 14 app with TypeScript, Tailwind CSS, and Prisma ORM.
Postgres database. Deployed on Vercel.

## Commands
- Dev server: npm run dev
- Run all tests: npm test
- Run single test: npx jest path/to/test.ts
- Lint: npm run lint
- Type check: npx tsc --noEmit

## Code Conventions
- Use functional components with hooks. No class components.
- Named exports only. No default exports.
- TypeScript strict mode. No `any` types.
- Colocate test files: Component.test.tsx next to Component.tsx.

## Do Not
- Do not commit directly to main. Use feature branches.
- Do not delete or modify migration files.
- Do not install new dependencies without asking first.

This file is 20 lines. That is intentional. Every line in CLAUDE.md loads into every request as recurring input cost, so each line competes for attention with the actual work you are asking Claude to do. The most effective CLAUDE.md files stay between 20 and 50 lines. Beyond roughly 50 lines, instructions start getting partially ignored as context fills with other information from your codebase and conversation history.

For each line you consider adding, ask one question. Would removing this cause Claude to make a mistake it would not make otherwise? If Claude already follows a convention by default (like using async/await in modern JavaScript), writing it down adds noise without improving output.

How to Verify Your Rules Are Working

After creating your CLAUDE.md, test it by giving Claude a task that would normally trigger one of your rules. If you wrote “No default exports,” ask Claude to create a new component and check whether it uses a named export.

You can also ask Claude directly:

# Ask Claude what it knows about your project
> What conventions does this project follow?

# Check context budget
/context

The /context command shows how much of the context window your session is consuming (for example, “450k/1000k tokens”). If CLAUDE.md is eating a disproportionate share on a project with a small codebase, the file is probably too long.

When a rule is not working, the most common causes are ambiguous phrasing and file length. “Format code properly” is vague. “Run prettier after editing .ts files” is actionable. If Claude keeps ignoring a specific instruction despite clear phrasing, the file may be too long for Claude to weigh every rule consistently. Prune first, then re-test.

When Should You Move Rules to .claude/rules/?

CLAUDE.md at the project root loads into every single request. For a 30-line file, the cost is negligible. For teams with extensive standards (style guides, architecture docs, testing protocols), the root file can grow past the point where it is effective.

The alternative is .claude/rules/. Files in this directory load selectively based on what Claude is working on. A rule about database migrations loads when Claude touches migration files. A rule about API conventions loads when Claude edits endpoint handlers. The per-request cost drops because only relevant rules enter the context.

my-project/
├── CLAUDE.md                     # Universal rules (20-30 lines)
└── .claude/
    └── rules/
        ├── database.md            # Loads when touching DB code
        ├── api-conventions.md     # Loads when editing endpoints
        └── testing.md             # Loads when writing tests

Start with everything in the root CLAUDE.md. Move rules to scoped files only when the root file grows past 50 lines or when you notice Claude dropping instructions. The next lesson covers adding skills, which is the next layer of customization beyond rules.