CLAUDE.md: The Configuration File That Shapes Every Claude Code Session

Most developers discover CLAUDE.md by accident. They run Claude Code, see something unexpected happen, and then notice a CLAUDE.md file at the root of their project. They open it. They see instructions to themselves.

And then they realise: everything Claude Code does in their project is shaped by this file.

CLAUDE.md is a lightweight, human-readable configuration file that lets you define rules, constraints, and context for Claude Code sessions in your project. It's not strictly required—Claude Code works without it. But every project benefits from having one, and most well-maintained projects rely on it.

This post covers what CLAUDE.md is, what goes in it, and how to structure it for reliable, repeatable Claude Code automation.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file at your project root that Claude Code reads before starting any task. It contains:

• Project context (what the project does, its architecture)
• Coding standards and patterns (style, naming conventions, testing rules)
• Constraints and guardrails (things Claude Code must never do)
• Instructions for specific workflows (how to add a feature, how to run tests)
• Links to documentation and runbooks

Claude Code doesn't execute CLAUDE.md like a script. Instead, it reads it as context—instructions that shape how Claude Code approaches your project.

Think of it as a lightweight replacement for onboarding a new developer. Instead of explaining your project in conversation, you write it down once in CLAUDE.md. Every Claude Code session in your project starts with that same baseline understanding.

The Difference Between .claude/CLAUDE.md and CLAUDE.local.md

There are actually two versions:

CLAUDE.md (committed to git)

• Shared context for your entire team
• Project architecture, coding standards, approved tools
• Public patterns and conventions
• What everyone working on the project should know

CLAUDE.local.md (.gitignored)

• Personal preferences and overrides
• Your specific development setup
• Tools you use locally that aren't project-wide standards
• What only you need to know

A project should have a committed CLAUDE.md describing shared patterns. Individual developers can optionally have CLAUDE.local.md with personal preferences.

What Goes in CLAUDE.md?

1. Project Overview

Start with a brief description of what the project does, who uses it, and what problem it solves. Include:

• Project name and purpose
• Key technologies and frameworks
• Where the project runs (frontend, backend, CLI, etc.)
• Link to main documentation

Example:

# Acme API

Backend JSON REST API for the Acme platform. Built with Node.js, Express, PostgreSQL.

Handles customer accounts, billing, integrations, webhooks.

Deployed to AWS Lambda. 50+ deployments per day.

2. Architecture and File Structure

Describe the layout:

• Where the entry point is
• How the project is organized (by feature, by layer, by concern)
• Which directories contain business logic vs. test fixtures vs. generated files
• Dependencies between major components

This prevents Claude Code from accidentally placing code in the wrong location.

3. Coding Standards

Define the patterns you follow:

• Language dialect (TypeScript, Python, etc.) and version
• Testing framework and coverage expectations
• Code style (ESLint config, formatting rules)
• Naming conventions (files, functions, variables)
• Database schema rules and migration patterns
• API response format (always JSON, status codes, error format)

Example:

## Code Standards

- **Language**: TypeScript 5.0+. Strict mode required (`"strict": true`).
- **Testing**: Jest. 80% coverage minimum. Test files live alongside source (`*.test.ts`).
- **Style**: Prettier for formatting. ESLint for rules.
- **Naming**: camelCase for variables, PascalCase for classes, SCREAMING_SNAKE for constants.
- **Async**: Use async/await, not .then() chains.

4. What Claude Code Must Never Do

This is the guardrails section. List things that are explicitly out of bounds:

• Never commit secrets (API keys, passwords) to git
• Never break backwards compatibility without a migration
• Never add production dependencies without explicit approval
• Never delete user data
• Never run destructive database operations without user confirmation
• Never merge to main without passing tests

Example:

## Constraints

- ❌ Never commit .env files or secrets
- ❌ Never run `npm install` without updating package-lock.json
- ❌ Never deploy to production without manual approval
- ❌ Never delete rows from the users table

5. How to Do Specific Things

Provide step-by-step runbooks for common tasks:

• How to add a new API endpoint
• How to write a new test
• How to add a database migration
• How to add a new page to the frontend
• How to deploy to production

These are procedures Claude Code can reference when starting a task.

Example:

## Adding a New API Endpoint

1. Create route handler in `src/routes/[endpoint].ts`
2. Add request/response types to `src/types/api.ts`
3. Add tests to `src/routes/[endpoint].test.ts`
4. Update README with endpoint documentation
5. Run `npm test` and `npm run lint` locally
6. Commit and push; CI will verify

6. External References

Link to documentation that Claude Code should consult:

• API documentation (for integrations)
• Architecture decision records (ADRs)
• Deployment runbooks
• Infrastructure diagrams (if available)
• Third-party service documentation

How Claude Code Uses CLAUDE.md

When you start a Claude Code session, Claude Code:

1. Reads CLAUDE.md from your project root
2. Includes it in the context window
3. Uses it to guide decisions about code style, patterns, and constraints

Claude Code doesn't follow CLAUDE.md mechanically. Instead, it treats it as a set of guidelines that shape the quality and consistency of the work.

If CLAUDE.md says "always use async/await, never use .then()", Claude Code will write async/await. If it says "run tests before committing", Claude Code will run tests. If it says "never delete user data without a safety check", Claude Code will add that safety check.

Best Practices for CLAUDE.md

1. Keep it up to date

If your project's standards change, update CLAUDE.md. Stale documentation is worse than no documentation.

2. Prioritize clarity over completeness

A focused, easy-to-scan CLAUDE.md is better than a 5000-word reference manual. Readers (human and AI) skim it quickly. Make the important bits obvious.

3. Use sections and headings

Break content into sections: Overview, Architecture, Standards, Constraints, How To, References. This makes it skimmable.

4. Commit to git

CLAUDE.md belongs in version control. It's project knowledge, and it should be tracked with your code.

5. Link to external docs, don't duplicate them

Don't copy your API documentation into CLAUDE.md. Link to it. External docs are the source of truth; CLAUDE.md points to them.

6. Include "what not to do"

Constraints are often more useful than instructions. "Don't delete the users table" is clearer than "follow this migration pattern".

Real-World Example: A Minimal CLAUDE.md

Here's a complete, minimal CLAUDE.md for a typical backend service:

# Acme API

Backend REST API. Node.js + Express + PostgreSQL. Handles authentication, billing, webhooks.

## Architecture

- `src/routes/` - Route handlers and middleware
- `src/models/` - Database models and queries
- `src/middleware/` - Express middleware
- `src/utils/` - Utilities and helpers
- `tests/` - Test suite
- `.env` - Environment configuration (local only, never commit)

## Code Standards

- TypeScript 5.0+ with strict mode
- Jest for testing; 80% coverage minimum
- ESLint + Prettier (run `npm run lint` before committing)
- async/await only; no .then() chains
- Error responses always include `{ error: string, status: number }`

## Constraints

- ❌ Never commit .env or credentials
- ❌ Never break backwards compatibility without a migration
- ❌ Never run database DELETE without confirmation
- ❌ Never merge to main without passing all tests

## How To

**Add an API endpoint:**
1. Create handler in `src/routes/[name].ts`
2. Add types to `src/types/api.ts`
3. Write tests in `tests/[name].test.ts`
4. Run `npm test` and `npm run lint`
5. Commit and push

**Deploy to production:**
1. Merge to main (CI runs tests)
2. Tag release: `git tag v1.2.3`
3. Push tag: `git push --tags`
4. GitHub Actions handles deployment

## References

- [API Documentation](https://docs.acme.api/)
- [Architecture Decision Records](./docs/ADRs/)
- [Deployment Runbook](./ops/DEPLOY.md)

FAQ

Q: Do I need a CLAUDE.md?

A: No, but you should have one. Claude Code works without it, but a CLAUDE.md makes Claude Code's output more consistent and predictable.

Q: How long should CLAUDE.md be?

A: As long as it needs to be, but usually 500–2000 words. Anything shorter and you're probably missing important context. Anything longer and most of it won't be read.

Q: Can I use CLAUDE.md for other tools?

A: Possibly. Some other AI tooling reads CLAUDE.md. But it's primarily designed for Claude Code.

Q: Should CLAUDE.md include examples?

A: Yes, but sparingly. A few code examples of the pattern you want followed are useful. A reference manual is not.