Claude Code CLAUDE.md Guide: Project Instructions That Actually Work

Overview

CLAUDE.md is Claude Code’s project instruction file. Drop it in your repo root, and every Claude Code session in that directory picks up your rules automatically — coding standards, architecture decisions, deployment constraints, whatever you need the agent to follow consistently.

Think of it as .editorconfig for an AI agent. No UI, no settings panel. Just a markdown file checked into version control that travels with your codebase.

This guide covers file placement, syntax, scoping rules, and practical patterns for teams using Claude Code across macOS, Linux, and Windows.

Tool

Claude Code

Version

1.x

Pricing

Free with Claude Pro ($20/mo), Team ($30/mo), Max ($100-200/mo)

Platforms

macOS, Linux, Windows

Last Checked

2026-04-10

What CLAUDE.md Does

Claude Code reads CLAUDE.md files at session start and loads their contents as system-level instructions. Every prompt you send, every tool call the agent makes — all filtered through those rules.

The file supports standard Markdown. No special syntax required. Write plain English instructions and Claude Code follows them. The key difference from a regular README: Claude Code treats CLAUDE.md contents as binding instructions, not suggestions. If you write “never use any type in TypeScript,” the agent actively avoids it.

Multiple CLAUDE.md files can coexist at different directory levels. Claude Code merges them with a clear precedence order, which makes monorepo setups straightforward.

Prerequisites

• Claude Code installed (v1.x or later)
• Claude subscription: Pro ($20/mo), Team ($30/mo), or Max ($100–200/mo)
• OS: macOS, Linux, or Windows
• A git repository (CLAUDE.md works best in version-controlled projects)
• Terminal access — Claude Code is a CLI tool

# Verify Claude Code is installed
claude --version

No additional dependencies. CLAUDE.md is a plain text file — any editor works.

File Placement and Scoping

CLAUDE.md files follow a hierarchy. Claude Code checks three locations, in order of precedence:

~/.claude/CLAUDE.md              # User-level (all projects)
/project-root/CLAUDE.md          # Project-level (this repo)
/project-root/src/CLAUDE.md      # Directory-level (this folder and below)

User-level (~/.claude/CLAUDE.md): Applies to every project. Good for personal preferences — your preferred language, comment style, or response format.

Project-level (repo root): Shared team rules. Check this into git. Covers architecture decisions, tech stack constraints, and coding standards.

Directory-level (subdirectories): Scoped overrides. A frontend/CLAUDE.md can enforce React-specific rules without affecting backend code.

When files conflict, the more specific scope wins. Directory-level overrides project-level, which overrides user-level.

Step 1: Create Your First CLAUDE.md

Start with a project-level file in your repo root:

touch CLAUDE.md

Add basic project context:

# Project Instructions

## Tech Stack
- Python 3.12 / FastAPI / PostgreSQL
- Frontend: React 18 with TypeScript
- Testing: pytest (backend), Vitest (frontend)

## Rules
- All Python code uses type hints
- SQL queries use parameterized statements only — no string interpolation
- API responses follow the existing envelope format in utils/response.py
- Never modify migration files that are already applied

That’s it. Next time you open Claude Code in this directory, it reads these instructions automatically. No import command, no configuration step.

Step 2: Write Effective Instructions

CLAUDE.md instructions work best when they’re specific and actionable. Vague guidance gets vague compliance.

Weak:

- Write clean code
- Follow best practices
- Be careful with the database

Strong:

- Functions must not exceed 30 lines. Extract helpers if needed.
- All database writes go through the Repository pattern in src/repos/.
- Error responses use HttpException from src/exceptions.py, never raw dicts.
- Import order: stdlib → third-party → local, separated by blank lines.

Rules that reference specific files, patterns, or numbers leave no room for interpretation. Claude Code can verify these against the actual codebase.

What to Include

Step 3: Scope Rules for Monorepos

Monorepos benefit most from directory-level CLAUDE.md files. Each package or service gets its own instructions.

monorepo/
├── CLAUDE.md                    # Shared: git conventions, PR format
├── packages/
│   ├── api/
│   │   └── CLAUDE.md            # Python/FastAPI rules
│   ├── web/
│   │   └── CLAUDE.md            # React/TypeScript rules
│   └── shared/
│       └── CLAUDE.md            # "No framework-specific imports"

Example packages/web/CLAUDE.md:

# Web Package Rules

- Components use functional style with hooks. No class components.
- State management: Zustand only. No Redux, no Context for global state.
- CSS: Tailwind utility classes. No inline styles, no CSS modules.
- All components need a corresponding .test.tsx file.
- Barrel exports (index.ts) are banned — use direct imports.

Example packages/api/CLAUDE.md:

# API Package Rules

- All endpoints require OpenAPI docstrings (FastAPI auto-generates docs).
- Authentication middleware is already applied at router level — don't re-check.
- Database sessions: use the `get_db` dependency, never create sessions manually.

Step 4: Team Patterns and Version Control

CLAUDE.md belongs in version control. It’s a project artifact, same as .eslintrc or tsconfig.json.

git add CLAUDE.md
git commit -m "Add Claude Code project instructions"

Branch-specific instructions work naturally. A feature branch can modify CLAUDE.md to add context:

## Current Work
- Branch: feat/auth-v2
- Migrating from JWT to session-based auth
- Do not modify any v1 auth endpoints — they're being deprecated separately

When the branch merges, the temporary instructions merge too (or get removed in review).

Team conventions to standardize:

• Designate one person to own the root CLAUDE.md
• Use PRs for CLAUDE.md changes — they affect everyone’s Claude Code sessions
• Review CLAUDE.md in onboarding, same as you’d review the contributing guide

Step 5: Advanced Patterns

Conditional Instructions

Claude Code understands conditional language:

- When modifying files in `src/legacy/`: preserve existing patterns even if
  they violate our current standards. This code is scheduled for deletion in Q3.
- When creating new API endpoints: always add rate limiting middleware.
- If a test file doesn't exist for a module you're editing, create one.

File References

Point Claude Code to existing documentation:

## References
- API design guide: docs/api-standards.md
- Database schema: docs/schema.md
- Deployment runbook: ops/deploy.md

Claude Code reads these files when relevant to the task. You don’t need to paste their contents into CLAUDE.md.

Output Formatting

Control how Claude Code communicates:

## Communication
- Explain changes in plain English before showing code
- Keep explanations under 3 sentences unless asked for detail
- Use Korean for all status messages and summaries

Tips and Best Practices

• Be specific over general. “Use zod for validation” beats “validate inputs properly.” Claude Code can act on the former immediately.
• Update CLAUDE.md when you repeat yourself. If you’ve corrected Claude Code three times about the same thing, it belongs in the file.
• Keep it under 500 lines. Extremely long instruction files dilute important rules. If you need more, split into directory-level files.
• Use headers for organization. Claude Code parses Markdown structure. Grouped rules under clear H2/H3 headers get applied more reliably than flat lists.
• Test your instructions. After updating CLAUDE.md, start a fresh Claude Code session and ask it to do something the rules should affect. Verify compliance.
• Don’t duplicate linter rules. If ESLint or Ruff already enforces a rule, CLAUDE.md doesn’t need to repeat it. Focus on architectural and design decisions that linters can’t catch.

FAQ