CLAUDE.md Essentials: Configuring Claude Code for Production Workflows

Most Claude Code users never read the CLAUDE.md documentation. They probably don't know it exists. But every time you run Claude Code in a directory, it reads the CLAUDE.md file in that project root—if one exists—and uses it to shape how Claude Code behaves.

CLAUDE.md is the configuration file that controls which files Claude Code can see, what it can do, how it interacts with your team, and what constraints it operates within. Getting it right is the difference between Claude Code being a helpful collaborator and Claude Code being a liability.

This guide covers what CLAUDE.md actually does, how to structure it, and the patterns that work for production workflows.

What CLAUDE.md Actually Is

CLAUDE.md is a Markdown file in your project root that Claude Code reads at the start of every session. It contains instructions—both about the project and about how Claude Code should behave within it.

Claude Code doesn't execute CLAUDE.md as code. It reads it as context and uses it to inform its behaviour. Think of it as a prompt template that's loaded automatically.

Basic Structure

Here's a minimal CLAUDE.md:

# Project: MyApp

You are working on MyApp, a Node.js backend API.

## Constraints

- Never modify database migrations without explicit approval
- Always run tests before committing
- Use the existing code style (check .prettierrc)

## Key Files

- `src/server.ts` — main entry point
- `src/api/routes/*.ts` — route handlers
- `tests/*.test.ts` — test files

## How to Run Tests

npm test

## When You're Done

- Commit your changes with a clear message
- Push to a feature branch
- Do not merge to main yourself

When Claude Code starts a session, it reads this file and understands the project structure, constraints, and practices.

Section 1: Project Overview

The first section should describe what the project is, what it does, and who maintains it:

# Project: CLI Tool for Database Migrations

This is a command-line tool for running and managing database schema migrations. It's written in Rust, supports PostgreSQL and MySQL, and is used by 150+ companies in production.

**Maintainer:** Platform Team
**Current Release:** v2.3.1
**Critical Environment:** Production database is PostgreSQL 14 on AWS RDS

This context helps Claude Code make sensible decisions. If it knows the tool is production-critical, it'll be more cautious about refactoring than if it's a side project.

Section 2: Constraints and Non-Negotiables

This section lists things Claude Code must not do. Be specific:

Bad: "Don't break things"

Good: "Never modify the authentication layer without a security review. Never commit directly to main. Never update dependencies without checking for breaking changes."

Here's a realistic example:

## Constraints

- **Database migrations:** Once a migration has been deployed to production, do not modify it. Create a new migration instead.
- **Authentication:** Changes to `src/auth/` require explicit approval. Do not implement new auth schemes without discussion.
- **Dependencies:** Pin all package versions in package.json. Do not use wildcard versions (^, ~).
- **Tests:** New code must have tests. Do not reduce test coverage.
- **Commits:** Write meaningful commit messages. Use conventional commit format: `feat: ...`, `fix: ...`, etc.

Constraints aren't punitive—they're guardrails. They prevent Claude Code from doing things that look helpful but cause downstream problems.

Section 3: Project Structure and Key Files

Tell Claude Code where things are and what each part does:

## Project Structure

- `src/` — application source code
  - `api/` — HTTP endpoint handlers
  - `db/` — database connection and queries
  - `middleware/` — Express middleware
  - `tests/` — unit tests
- `migrations/` — database schema migrations (PostgreSQL)
- `scripts/` — utility scripts for development
- `docker-compose.yml` — local development environment

This saves Claude Code from having to explore the codebase to understand structure. It'll have a mental model before it starts.

Section 4: Development Workflow

Explain how to set up, test, and deploy locally:

## Local Development

1. Clone the repository
2. Run `docker-compose up` to start PostgreSQL
3. Run `npm install`
4. Run `npm run dev` to start the development server
5. Run `npm test` to run tests

## Running Tests

npm test # Run all tests

npm test -- auth # Run tests matching 'auth'

npm test -- --coverage # Run with coverage report

Tests take ~30 seconds. They require a running PostgreSQL instance (docker-compose provides one).

## Deploying Changes

1. Create a feature branch
2. Make changes and commit
3. Push to GitHub
4. Create a pull request
5. Wait for CI to pass
6. Get approval from the code owner
7. Merge to main
8. CI automatically deploys to staging

Claude Code will follow this workflow without having to ask for clarification.

Section 5: Code Style and Standards

Reference the standards your project uses:

## Code Style

- **Language:** TypeScript
- **Format:** Prettier (configured in .prettierrc)
- **Linter:** ESLint (configured in .eslintrc.json)
- **Run linting:** `npm run lint`

All code must:
- Pass TypeScript compilation (`tsc --noEmit`)
- Pass linting
- Have tests for new functions
- Include JSDoc comments for exported functions

With this, Claude Code knows what the code style is and can adhere to it.

Section 6: Known Issues and Gotchas

Document the quirks and workarounds:

## Known Issues

1. **Database connections timeout after 5 minutes of inactivity.** Always call `pool.query()` at least once per session to keep the connection warm. If you see "connection timeout", run the test suite first before proceeding.

2. **Docker volume on macOS is slow.** If running tests feels sluggish, it's the Docker volume. Native macOS tests are faster.

3. **The `admin` table is denormalised.** It's intentional for performance. Do not normalise it without consulting the database team.

When Claude Code encounters these, it'll know what to do instead of spending turns debugging.

Section 7: Communication Protocol

If Claude Code is running as part of a team workflow, tell it how to request help:

## Communication

If you encounter:
- **Merge conflicts:** Pause and ask for help in #engineering on Slack
- **Database locks:** Wait 5 minutes and retry. If still locked, ask in #backend
- **Unclear requirements:** Ask in the GitHub issue or PR comments
- **Security questions:** Ask in #security before proceeding

When asking for help, be specific: include error messages, what you tried, and what you're stuck on.

This prevents Claude Code from guessing or making assumptions when it's genuinely unsure.

Section 8: What Success Looks Like

End with a clear definition of success:

## Success Criteria

A task is complete when:
1. All tests pass (`npm test`)
2. Linting passes (`npm run lint`)
3. TypeScript compilation succeeds (`tsc --noEmit`)
4. New code has test coverage
5. Commit message is clear and follows conventional commits
6. No console.log statements remain (unless they're intentional debugging aids)

This prevents the common problem of Claude Code deciding it's done before the work is actually done.

Best Practices for Production CLAUDE.md

1. Keep it concise. More than 2,000 words and Claude Code won't absorb it all. Focus on constraints, structure, and how to verify success.

2. Update it when you change standards. If you adopt a new linter or change your deployment process, update CLAUDE.md immediately. Stale CLAUDE.md is worse than no CLAUDE.md.

3. Include example commands. "Run tests" is vague. "Run npm test takes 30 seconds" is clear.

4. Be specific about what not to do. "Don't break tests" is useless. "Never merge changes to src/auth/ without explicit approval" is actionable.

5. Document workarounds and gotchas. If there's a weird bug that takes people 20 minutes to find, document it. That's what CLAUDE.md is for.

FAQ

Q: Does Claude Code always read CLAUDE.md?

A: Yes, if it exists in the project root. It reads it at the start of every session.

Q: Can I have multiple CLAUDE.md files in different directories?

A: Claude Code reads the one in the directory it's working in. Subdirectories don't have their own CLAUDE.md files—the root one applies to the whole project.

Q: What if CLAUDE.md says to do something and the user says to do something else?

A: User instructions take priority. CLAUDE.md is context, not a hard constraint. If you explicitly tell Claude Code to ignore CLAUDE.md, it will.

Q: Should I commit CLAUDE.md to git?

A: Yes. It's part of the project. Everyone—and every instance of Claude Code—should follow the same standards.