Home / Glossary / CLAUDE.md

Definition

CLAUDE.md

CLAUDE.md is a markdown configuration file placed in your project root that provides Claude Code with persistent, project-specific instructions. It tells the agent about your coding conventions, architecture, common commands, and rules—acting as a form of long-term memory that applies to every session in that project.

How CLAUDE.md works

When Claude Code starts a session, it automatically reads the CLAUDE.md file in your project root (and any CLAUDE.md files in parent directories or subdirectories). The contents become part of the agent's system context, so it follows your instructions without needing to be reminded every session. This makes the agent behave consistently with your team's conventions.

What to include in CLAUDE.md

  • +Project architecture overview and key file locations
  • +Coding conventions (naming, formatting, patterns to use or avoid)
  • +Common commands for testing, building, and deploying
  • +Rules like "always write tests for new functions" or "never modify the auth module directly"
  • +Technology stack details the agent should be aware of
markdown
# CLAUDE.md

## Project
Next.js 14 app with App Router, TypeScript, Tailwind CSS.

## Commands
- `npm run dev` — start dev server
- `npm test` — run Jest tests
- `npm run lint` — ESLint check

## Conventions
- Use server components by default
- Client components go in `components/client/`
- All API routes must validate input with Zod
- Write tests for every new utility function

## Do NOT
- Modify files in `lib/core/` without explicit approval
- Use `any` type in TypeScript
- Add new dependencies without justification

Keep CLAUDE.md concise. The agent reads it every session, so include only information that is relevant across multiple tasks. Move task-specific details into your prompts instead.

Where should I place the CLAUDE.md file?+
Place it in the root of your project directory. Claude Code also supports CLAUDE.md files in subdirectories for module-specific instructions, and in parent directories for organization-wide rules. All applicable files are merged together.
Does CLAUDE.md work with other AI tools?+
CLAUDE.md is specific to Claude Code. However, some other tools have adopted similar concepts. Cursor uses .cursorrules, and other agents may read custom config files. The concept of project-level AI instructions is becoming a common pattern.
How long should CLAUDE.md be?+
Keep it under 500 lines. Focus on the most important conventions and rules. The agent can always read individual files for details—CLAUDE.md should provide the high-level context that applies across tasks.

Related terms

Agentic CodingClaude CodePrompt Engineering for Code

Master Claude Code in days, not months

37 hands-on lessons from beginner to CI/CD automation. Module 1 is free.

START FREE →
← ALL TERMS