Writing CLAUDE.md files

What CLAUDE.md is

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every session. It provides persistent project-specific instructions, conventions, and context so you don't need to repeat setup information in every prompt. Think of it as your project's instruction manual for the AI agent.

File locations and hierarchy

Claude Code reads CLAUDE.md files from multiple locations, merged in this priority order:

Location	Purpose	Shared via git?
~/.claude/CLAUDE.md	User-level defaults for all projects	No
./CLAUDE.md	Main project configuration (most common)	Yes
./.claude/CLAUDE.md	Alternative project location	Yes
./CLAUDE.local.md	Personal preferences (auto-gitignored)	No
./.claude/rules/*.md	Modular scoped rules	Yes
./subdir/CLAUDE.md	Subdirectory-specific rules (loaded on demand)	Yes

Files closer to the working directory take precedence over files higher up.

What to include

Build and test commands

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Test all: `npm test`
- Test single file: `npm test -- path/to/test.ts`
- Type check: `npx tsc --noEmit`

This is the highest-impact section. Claude Code uses these commands to verify its own work.

Code style and conventions

## Code style

- TypeScript strict mode, no `any` types
- Functional components with hooks (no class components)
- Named exports, not default exports
- Use `@/` import alias for all project imports
- Error responses use `{ error: { code, message } }` format
- Database queries go through the repository pattern in `src/repos/`

Project structure

## Project structure

- `src/app/` — Next.js app router pages and API routes
- `src/components/` — React components (colocated styles)
- `src/lib/` — Shared utilities and business logic
- `src/repos/` — Database access layer
- `src/types/` — Shared TypeScript type definitions
- `prisma/` — Database schema and migrations

Workflow rules

## Workflow

- Run `npm run lint` and `npm test` before marking any task complete
- Commit after each logical change, not in large batches
- Never modify files in `src/generated/` (auto-generated by codegen)
- When creating API endpoints, also create the corresponding test file

What NOT to include

• Standard language conventions Claude already knows (e.g., "use camelCase in JavaScript")
• Information Claude can infer from code (e.g., which framework you use)
• Detailed API documentation (use MCP servers for this instead)
• Frequently changing information (dates, version numbers, sprint goals)
• Everything from your internal wiki (keep it focused on coding instructions)

Scoped rules with .claude/rules/

For larger projects, split instructions into modular files in .claude/rules/:

.claude/
└── rules/
    ├── typescript.md
    ├── react-components.md
    ├── api-routes.md
    └── database.md

Each file can include a globs: frontmatter to scope it to specific file patterns:

---
globs: src/app/api/**/*.ts
---

API routes must validate request bodies with zod schemas.
Always return proper HTTP status codes.
Include rate limiting headers in responses.

Important caveat: As of early 2026, the globs: field works with unquoted patterns. Quoted strings and YAML array syntax may not work reliably. Use globs: src/**/*.ts instead of globs: "src/**/*.ts".

Instruction budget

Claude Code's system prompt consumes approximately 50 instruction slots. You have roughly 100-150 instructions before quality begins to degrade. Guidelines for staying within budget:

• Keep your root CLAUDE.md under 300 lines
• Every line should be a real instruction, not filler
• Use scoped rules in .claude/rules/ to load instructions only when relevant
• If you find yourself writing paragraphs of explanation, it's too verbose

Getting started

Quick start with /init

Run /init in Claude Code to auto-generate a starter CLAUDE.md based on your project structure and detected tech stack. Then edit aggressively: remove anything generic, add your team-specific conventions, and trim to essential instructions.

Manual creation

Create CLAUDE.md in your project root:

## Commands

- Dev: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Code conventions

- TypeScript strict, no `any`
- Functional React components with named exports
- Use `@/` import paths
- All API routes must have corresponding test files

## Rules

- Run lint and tests before completing any task
- One logical change per commit
- Never modify generated files in `src/generated/`

Commit this to your repository so the entire team shares the same AI assistant behavior.