CLAUDE.md — Everything you need to know

What is CLAUDE.md?

CLAUDE.md is a lightweight configuration and instruction file that acts as the local memory engine for Anthropic's Claude Code CLI assistant. It serves as an instant context-injector that loads at startup, preventing the LLM from executing slow, repetitive system searches or wasting API context windows seeking project conventions.

Unlike general chat tools, Claude Code operates directly in your local terminal. Without clear guidance, it has to guess your project layout, search for package files, figure out the test command, and guess your code standards. Providing a CLAUDE.md makes the assistant behave as an experienced engineer who already knows your codebase inside out.

The consensus that has emerged from real-world use: a good CLAUDE.md is short, command-focused, and framework-specific. It contains exact command strings, directory conventions, and style constraints — the things the AI genuinely needs, not the things a human onboarding document would explain. Verbose prose costs tokens on every turn without improving output.

Where does it go?

By default, Claude Code checks for configuration files in two locations:

• Workspace Scope (Root): Place a CLAUDE.md directly in the root of your project directory (e.g., /my-project/CLAUDE.md). This governs code written for this specific project.
• Global Scope (User Home): Put instructions at ~/.claude/CLAUDE.md. This acts as a global rule sheet that gets inherited across all repositories you run Claude Code in.

In monorepos or nested architectures, you can place multiple CLAUDE.md files inside individual subdirectories. Subdirectory rules inherit options from the parent root, but override them for scoped modules (e.g., separating microservices from frontend modules).

What should it contain?

A performant CLAUDE.md file should be concise, structured, and contain direct instructions rather than boilerplate prose. Following claude.md best practices, an ideal schema outlines:

Frontmatter and structure

Standard markdown frontmatter can be defined using YAML syntax at the top of the file to manage metadata and customization states. Currently, frontmatter acts as a semantic metadata block, while the markdown content itself structures the executable directions:

---
name: my-project-guide
description: Code standards and command specs for NextJS & Prisma setup.
---
# Build and Test Commands
- Build: `npm run build`
- Single Test: `npm test -- [filename]`
- All Tests: `npm test`
- Lint: `npm run lint`

Global vs Project-Scoped Configurations

Managing where your commands sit is crucial for preventing context limits. Use the table below to choose the right location:

Common Mistakes

Keep these anti-patterns in mind when writing your CLAUDE.md files:

• Overly Wordy Guidelines: Avoid narrative explanations. Use lists and direct code rules (e.g. "Use TypeScript enums" instead of "We really like using TypeScript enums in our project because...").
• Outdated Commands: Ensure your test and build commands are fully functional. If Claude Code gets a failing build because the command is wrong, it will spend tokens trying to debug the build configuration itself.
• Giant File Sizes: Do not copy-paste your entire design guidelines document. Keep it focused and under 300 lines of markdown.

Full Config Example

# Build and Test Commands
- Build: `npm run build`
- Dev server: `npm run dev`
- Test single file: `npm run test -- [filename]`
- Test all: `npm run test`
- Lint: `npm run lint`

# Code Style Guidelines
- Use React functional components with TypeScript
- Enforce strict typing, no implicit `any`
- Tailwind: Use inline classes, follow spacing tokens
- Prefer async/await over raw Promises
- Formatting: 2 spaces indent, semi-colon required

# Project Conventions
- Folder structure: `src/components`, `src/layouts`, `src/pages`
- Put reusable utility helpers inside `src/utils/`
- Monorepos: backend folder contains Web API, frontend holds NextJS

How CLAUDE.md relates to AGENTS.md

While both files are custom markdown configurations used to guide AI, they target different tools and architectures:

• CLAUDE.md is explicitly designed for the CLI terminal agent. It requires build and test commands so it can run verification checks on local changes.
• AGENTS.md is an IDE-agnostic, broader context rulebook used by editor extensions. It focuses mostly on directory layout and styling guidelines rather than command execution.

Read our complete comparative details on our CLAUDE.md vs AGENTS.md Comparison Page.