CLAUDE.md: The File That Makes Claude Code Smarter (Complete Guide)

Every time you start a new Claude Code session, it forgets everything. Your coding conventions, your project structure, the mistakes you corrected yesterday — all gone. You spend the first five minutes of every session re-explaining the same things. CLAUDE.md fixes this permanently. It is a single file that sits in your project root and gives Claude Code persistent memory across sessions. Boris Cherny, the author of Programming TypeScript at O’Reilly and a senior engineer who has used Claude Code extensively, calls it one of his top three tips: “Claude is eerily good at writing rules for itself.”

This guide covers everything: what CLAUDE.md is, exactly where it goes, what to put in it, how to build one from scratch, real examples for React apps, Python backends, WordPress sites, and data pipelines, the feedback loop technique that makes it better over time, how it compares to competitor configuration files, and the mistakes that make it useless. If you use Claude Code for any serious work, this file is not optional.

Key Takeaways

• In one sentence: CLAUDE.md is a persistent memory file that Claude Code reads at the start of every session, giving it your project context, coding conventions, and past lessons without you having to repeat yourself.
• Key number: A well-maintained CLAUDE.md can reduce session setup time from 5–10 minutes of re-explaining to zero, and developers report 30–50% fewer correction cycles per session.
• Why it matters: Without CLAUDE.md, Claude Code treats every session as a blank slate — it will reinvent your wheel, break your conventions, and repeat old mistakes.
• What to do next: Create a CLAUDE.md file in your project root and start with 10–15 rules. Grow it over time using the feedback loop technique explained below.
• Related reading: Claude Code: Complete Beginners Guide, Claude for Coding, Best Claude Prompts

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code automatically reads at the start of every session. It acts as persistent memory — a place to store project conventions, coding standards, architectural decisions, preferred tools, testing patterns, common mistakes to avoid, and anything else Claude needs to know to work effectively in your codebase. Think of it as a briefing document you hand to a new developer on their first day, except this developer reads it every single morning and follows it to the letter.

The file was introduced as part of Claude Code’s architecture because Anthropic recognized a fundamental limitation of AI coding assistants: they lack persistent context between sessions. Large language models do not remember previous conversations. Every time you launch Claude Code, it starts fresh. CLAUDE.md bridges this gap by encoding your institutional knowledge in a file that the tool is programmed to read automatically.

According to Anthropic’s official documentation, Claude Code looks for CLAUDE.md files in specific locations and loads them as part of its system context before processing your first prompt. This means the rules in your CLAUDE.md file influence every response Claude gives during that session — from how it names variables to which libraries it reaches for to how it structures error handling.

Where CLAUDE.md Lives: File Locations and Hierarchy

Claude Code supports CLAUDE.md files in multiple locations, each with a different scope. Understanding this hierarchy is essential for teams and developers who work across multiple projects.

Project-Level CLAUDE.md (Most Important)

Place a CLAUDE.md file in your project’s root directory — the same folder as your package.json, pyproject.toml, or .git folder. This is the primary location Claude Code checks. Every time you run claude from within that directory (or any subdirectory), it reads this file first. Project-level CLAUDE.md is the one you will use 90% of the time. It contains rules specific to that particular codebase: naming conventions, import patterns, which ORM to use, how to run tests, which directories hold what, and which decisions have already been made.

Global CLAUDE.md (User-Wide Preferences)

Claude Code also supports a global CLAUDE.md file located at ~/.claude/CLAUDE.md on macOS and Linux. This file applies to every project you work on. Use it for personal preferences that span all your work: your preferred comment style, your git commit message format, your default linting preferences, or the fact that you always want TypeScript over JavaScript. Keep the global file lean — 10 to 20 lines maximum. If a rule only applies to one project, it belongs in the project-level file, not here.

Directory-Specific CLAUDE.md (Nested Scoping)

You can also place CLAUDE.md files in subdirectories. When Claude Code operates on files within a subdirectory that has its own CLAUDE.md, it reads both the project root file and the subdirectory file. This is useful for monorepos where the /frontend and /backend directories follow different conventions. The subdirectory file supplements — it does not replace — the root file. Rules from all applicable CLAUDE.md files are merged together, with more specific (deeper) files taking precedence when there are conflicts.

Loading Order and Priority

Claude Code loads CLAUDE.md files in this order: global first, then project root, then any subdirectory files relevant to the current working context. This means your global preferences serve as defaults that project-level rules can override, and subdirectory rules can override project-level rules. If your global file says “use tabs” and your project file says “use 2-space indentation,” the project file wins when you are working in that project.

What to Put in CLAUDE.md

The content of your CLAUDE.md file determines how useful it is. Too little and Claude still guesses. Too much and it gets buried in noise. After studying dozens of production CLAUDE.md files from open-source projects and interviewing developers who rely on them daily, here are the categories that matter most.

Project Overview and Architecture

Start with a 2–3 sentence description of what the project is and how it is structured. Claude Code can read your files, but it cannot read your mind about the overall design philosophy. Tell it what the project does, what framework it uses, what the deployment target is, and how the directory structure is organized. This is the foundation everything else builds on. Example: “This is a Next.js 14 e-commerce platform using the App Router, Prisma ORM with PostgreSQL, and Stripe for payments. The /app directory contains page routes, /lib contains shared utilities, and /components contains React components organized by feature.”

Coding Standards and Conventions

This is where most developers start and where CLAUDE.md delivers the most immediate value. Spell out your specific conventions: naming patterns (camelCase for functions, PascalCase for components, SCREAMING_SNAKE for constants), import ordering (stdlib first, then third-party, then local), error handling approach (always use custom error classes, never throw raw strings), file naming (kebab-case for files, PascalCase for components that match their filename). The more specific you are, the less you have to correct Claude later. Instead of writing “use good naming,” write “all React components use PascalCase filenames matching the default export name, e.g. UserProfileCard.tsx exports UserProfileCard.”

Common Mistakes to Avoid

This section is uniquely powerful because it teaches Claude from your past experience. Every time Claude makes a mistake during a session — uses the wrong import path, picks the deprecated API, or creates a file in the wrong directory — you add it here. Over time, this section becomes a curated list of anti-patterns specific to your project. Boris Cherny emphasizes this approach: when Claude makes an error, tell it “update your CLAUDE.md so you don’t make that mistake again.” Claude will write a clear, specific rule that prevents the error in future sessions. This is the feedback loop that makes CLAUDE.md increasingly valuable over time.

Architectural Decisions (ADRs)

Record the “why” behind major decisions. “We use Redux Toolkit instead of Zustand because our state is deeply nested and shared across 40+ components.” “We chose Postgres over MongoDB because our data is highly relational.” “We do not use ORMs for read-heavy queries — write raw SQL for anything touching the analytics tables.” Without these notes, Claude will cheerfully suggest alternatives that you already considered and rejected, wasting time in every session debating decisions that were settled months ago.

Preferred Tools and Libraries

List the tools and libraries you want Claude to reach for — and the ones you want it to avoid. “Use pnpm, not npm or yarn.” “Use date-fns for date manipulation, never moment.js.” “For HTTP requests, use the native fetch API, not axios.” “For testing, use Vitest with React Testing Library. Do not suggest Jest.” This prevents Claude from introducing dependencies you do not want and keeps your dependency tree clean. According to a 2025 Snyk report, the average JavaScript project has 683 transitive dependencies — every unnecessary library adds security surface area and maintenance burden.

Testing Patterns

Specify how tests should be written, where they should live, and what patterns to follow. “Tests live next to the file they test with a .test.ts suffix.” “Use describe/it blocks with meaningful descriptions.” “Mock external APIs using MSW (Mock Service Worker), not manual jest.mock calls.” “Every new utility function must have at least 3 test cases: happy path, edge case, and error case.” Claude Code can run tests after writing code, so giving it clear testing patterns means it can verify its own work autonomously.

Build and Run Commands

Tell Claude exactly how to build, test, lint, and run your project. “Run tests with pnpm test.” “Start dev server with pnpm dev.” “Lint with pnpm lint:fix.” “Build for production with pnpm build.” “Run database migrations with pnpm prisma migrate dev.” Claude Code executes terminal commands as part of its workflow — if it knows the right commands, it will use them to verify its changes work correctly before telling you it is done.

How to Create a CLAUDE.md from Scratch

Building your first CLAUDE.md takes about 15 minutes. Here is the step-by-step process, whether you prefer to write it yourself or let Claude help.

Option A: Write It Manually

Step 1: Create the file. In your terminal, navigate to your project root and run touch CLAUDE.md. Open it in any text editor.

Step 2: Add a project overview. Write 2–3 sentences describing what the project is, what stack it uses, and how the directory is organized.

Step 3: List your coding conventions. Think about the rules you would tell a new developer: naming patterns, import style, error handling approach, file organization.

Step 4: Add your build commands. List every command Claude might need: how to install dependencies, run tests, start the dev server, lint code, and build for production.

Step 5: Record 3–5 “do not” rules. Think about the mistakes a new developer would make in your codebase. “Do not modify files in /generated — they are auto-generated by Prisma.” “Do not use default exports except for page components.”

Step 6: Save the file and commit it to version control. CLAUDE.md should be tracked in git so your entire team benefits from it.

Option B: Let Claude Write Its Own Rules

This is Boris Cherny’s preferred approach and arguably the more powerful one. Start a Claude Code session in your project and give it this prompt: “Analyze this codebase and create a CLAUDE.md file with project conventions, coding standards, architecture notes, common patterns you observe, and build commands.” Claude will scan your files, identify patterns, and generate a comprehensive CLAUDE.md based on what it finds in the actual code. Then review what it wrote, edit anything that is wrong, and commit the file.

Boris describes this as one of Claude Code’s most impressive capabilities. Claude analyzes your existing code patterns — how you name variables, how you structure imports, which libraries you actually use — and codifies them into rules. “Claude is eerily good at writing rules for itself,” Cherny notes. The resulting CLAUDE.md often catches conventions that the developers themselves had not explicitly articulated but were following instinctively.

The Feedback Loop Technique: How CLAUDE.md Gets Better Over Time

The real power of CLAUDE.md is not what you put in it on day one — it is how it evolves through daily use. The feedback loop technique works like this:

1. Claude makes a mistake. Maybe it uses var instead of const, or imports from the wrong path, or creates a component in the wrong directory.
2. You correct it. “No, we use const for everything. And components go in /components/features, not /components.”
3. You tell Claude to remember. “Update your CLAUDE.md so you don’t make that mistake again.”
4. Claude adds a rule. It appends something like: “Always use const. Never use var or let unless mutation is required. React components live in /components/features/{FeatureName}/, not in the root /components/ directory.”
5. Next session, the mistake never happens again.

Over weeks and months of use, this loop compounds. Your CLAUDE.md file grows from a basic 15-line skeleton into a rich knowledge base that captures every hard-won lesson about your codebase. Boris Cherny advises pairing this growth with periodic pruning: “Ruthlessly edit over time.” Delete rules that are no longer relevant. Consolidate duplicate or overlapping rules. Remove anything too obvious (“write clean code” adds zero value). The best CLAUDE.md files are between 50 and 200 lines — dense, specific, and actionable.

This technique connects directly to one of the most effective patterns in prompt engineering: teaching the AI from specific corrections rather than abstract instructions. A rule like “do not use moment.js — it was deprecated in September 2020 and adds 300KB to the bundle; use date-fns instead” is vastly more useful than “use modern libraries.”

Real CLAUDE.md Examples for Different Project Types

Abstract advice only goes so far. Here are concrete CLAUDE.md examples for four common project types, showing exactly what to include and how to format it.

Example 1: React/Next.js Frontend

# CLAUDE.md — E-Commerce Frontend

## Project
Next.js 14 App Router, TypeScript strict mode, Tailwind CSS.
Deployed on Vercel. PostgreSQL via Prisma ORM.

## Conventions
- Components: PascalCase filenames, default exports, colocated .test.tsx files
- Hooks: use{Name} pattern in /hooks/, must have JSDoc comments
- Imports: React first, third-party next, then @/ aliases, then relative
- Styles: Tailwind utility classes only. No CSS modules, no styled-components
- State: Zustand for global state, React state for component-local

## Do NOT
- Use `any` type — use `unknown` then narrow with type guards
- Put API calls in components — use /lib/api/ wrapper functions
- Modify /generated/ directory — it's auto-generated by Prisma
- Use default exports except for page.tsx and layout.tsx files
- Use barrel exports (index.ts re-exports) — they break tree-shaking

## Commands
- pnpm dev — start dev server on localhost:3000
- pnpm test — run Vitest suite
- pnpm lint:fix — ESLint + Prettier auto-fix
- pnpm build — production build (must pass before PR merge)

Example 2: Python Backend (FastAPI)

# CLAUDE.md — Analytics API Service

## Project
FastAPI backend, Python 3.12, async throughout.
PostgreSQL with asyncpg (no ORM for read queries).
Redis for caching. Deployed on AWS ECS Fargate.

## Conventions
- snake_case for everything (functions, variables, files, directories)
- Type hints required on all function signatures — use | for union types
- Pydantic v2 models for all request/response schemas in /schemas/
- Repository pattern: /repositories/ for DB access, /services/ for business logic
- Every endpoint must have OpenAPI docstrings

## Do NOT
- Use SQLAlchemy — we use raw asyncpg for performance on read-heavy queries
- Use requests library — use httpx for async HTTP calls
- Put business logic in route handlers — extract to /services/
- Use print() for logging — use structlog with bound context
- Commit .env files — use .env.example as template

## Commands
- uv run uvicorn app.main:app --reload — start dev server
- uv run pytest -x — run tests (stop on first failure)
- uv run ruff check --fix . — lint and auto-fix
- uv run mypy . — type checking

Example 3: WordPress Content Site

# CLAUDE.md — Content Management for beginnersinai.org

## Project
WordPress site on WordPress.com Business plan.
Content uploaded via REST API. Category-based organization.
All content in Gutenberg block format.

## Conventions
- Articles: 2,500+ words, Gutenberg blocks, no bare HTML
- Crosslinks: 4+ per article using href="/slug/" format (relative, trailing slash)
- FAQ: exactly 5 questions as h3 tags at end of article
- Images: 1200x630px featured hero, alt text required
- Tags: 3-5 per article, lowercase-kebab-case
- External links: 3 per article, at least 1 to Grokipedia

## Do NOT
- Use h1 tags — WordPress adds the title as h1 automatically
- Link to banned or overly political tech publications
- Use full URLs for internal links — use /slug/ format only
- Publish without an excerpt — it's used as meta description
- Use generic filler phrases ("In today's fast-paced world")

Example 4: Data Pipeline (dbt + Airflow)

# CLAUDE.md — Analytics Data Pipeline

## Project
dbt Core 1.7 for transformations, Airflow 2.8 for orchestration.
Snowflake data warehouse. Source data from Fivetran connectors.

## Conventions
- Models: staging (stg_), intermediate (int_), mart (mart_) prefixes
- All models must have schema.yml with descriptions and tests
- Use CTEs, never subqueries — one CTE per logical transformation
- Incremental models must have _loaded_at timestamp filter
- DAG naming: {domain}_{frequency}_{description} (e.g., marketing_daily_attribution)

## Do NOT
- Use SELECT * in any model — enumerate columns explicitly
- Create models without corresponding .yml schema tests
- Hardcode dates — use dbt's {{ var('start_date') }} variables
- Skip the staging layer — raw sources must go through stg_ first
- Use UNION without UNION ALL (we never need deduplication at union)

How Claude Reads and Uses CLAUDE.md

Understanding the mechanics helps you write a better file. When you start a Claude Code session by typing claude in your terminal, the tool performs several initialization steps before you ever type your first prompt. One of those steps is scanning for CLAUDE.md files. It loads the global file (if it exists), then the project root file, then any subdirectory files relevant to the current path. The combined content is injected into Claude’s system prompt — the hidden instructions that guide the AI’s behavior for the entire session.

This has a critical implication: CLAUDE.md content counts against the context window. Claude’s context window is large — Claude 3.5 Sonnet supports 200K tokens and Claude Opus 4 supports 200K tokens as well — but it is not infinite. A 200-line CLAUDE.md file uses roughly 1,500–2,500 tokens, which is a negligible portion of the context window. A 2,000-line CLAUDE.md file, on the other hand, would consume 15,000–25,000 tokens and start competing with the actual code Claude needs to read. This is why Boris Cherny advises keeping it lean: “Ruthlessly edit over time.”

Claude does not just read CLAUDE.md once — it has access to it throughout the session. When it generates code, it checks its output against the rules. When you ask it to modify a file, it considers the conventions. The rules function as persistent constraints that shape every response, similar to how a coding style guide works for human developers, except Claude actually follows it consistently.

CLAUDE.md vs .cursorrules vs .github/copilot-instructions

CLAUDE.md is not the only AI configuration file in the developer ecosystem. If you use or have evaluated other AI coding tools, you may have encountered similar files. Here is how they compare.

.cursorrules (Cursor Editor): Cursor, the AI-powered code editor built on VS Code, reads a .cursorrules file from your project root. It serves the same purpose as CLAUDE.md — persistent project-level instructions for the AI. The syntax is similar (plain text or Markdown). However, .cursorrules only works with Cursor. If you use both Cursor and Claude Code, you will need both files, though the content can overlap significantly. Cursor also supports a .cursor/rules directory for more granular control as of their 2025 updates.

.github/copilot-instructions.md (GitHub Copilot): GitHub introduced this file path in late 2024 to give Copilot project-level context. It works with Copilot Chat and Copilot in VS Code. The format is Markdown, and the purpose is identical: tell the AI about your project conventions. The key difference is scope — GitHub’s implementation is tightly integrated with their Copilot ecosystem and does not affect other tools.

Windsurf Rules (Windsurf Editor): Windsurf, another AI code editor, uses its own rules file format stored in .windsurfrules. The concept is the same — project-level AI configuration — but with Windsurf-specific syntax options.

The key difference with CLAUDE.md: Claude Code runs in the terminal, not in an editor. This means CLAUDE.md governs an agent that can read your entire codebase, execute commands, create files, and run tests autonomously. The rules in CLAUDE.md influence a broader range of actions than editor-based configuration files, which primarily affect code suggestions and completions. CLAUDE.md rules shape an autonomous agent’s entire decision-making process.

If you use multiple AI coding tools, consider maintaining a shared “source of truth” file and copying relevant rules into each tool-specific config. A 2025 Stack Overflow Developer Survey found that 76% of developers now use at least one AI coding tool, and 38% use two or more — making cross-tool configuration an increasingly common concern.

Project-Level vs Global CLAUDE.md: When to Use Each

The distinction between project-level and global CLAUDE.md is straightforward, but getting the boundary right matters for productivity.

Put in Global (~/.claude/CLAUDE.md): Personal preferences that apply everywhere — your preferred language (TypeScript over JavaScript), your commit message format, your default test runner, your opinion on semicolons, your git identity configuration, and your general communication preferences (“be concise, skip explanations unless asked”).

Put in Project (./CLAUDE.md): Everything else. Architecture decisions, package choices, directory structure, API patterns, deployment procedures, team conventions, known bugs, environment setup — all project-specific. If a rule would not apply to every project you work on, it belongs in the project file.

The 80/20 rule: In practice, 80% or more of your CLAUDE.md content should be in the project-level file. The global file should be slim — 10 to 20 lines. If your global file is longer than your project file, you are probably putting project-specific rules in the wrong place, and they will conflict with other projects. A Python backend project does not need your React component naming conventions cluttering up its context window.

Tips for Keeping CLAUDE.md Lean and Effective

After months of community experimentation, several best practices have emerged for maintaining high-quality CLAUDE.md files.

1. Use direct, imperative language. Write “use const for all declarations” not “it would be preferable to consider using const.” Claude responds better to clear commands. Every extra word dilutes the signal.

2. Group related rules under clear headings. Use Markdown headers (##) to organize rules into categories: Conventions, Commands, Do-Not, Architecture. This makes the file scannable for both humans and Claude.

3. Include the “why” for non-obvious rules. “Do not use barrel exports — they break tree-shaking in our webpack config” is better than “do not use barrel exports.” The reason helps Claude make analogous decisions in situations the rule does not explicitly cover.

4. Review and prune monthly. Set a calendar reminder. Delete rules for libraries you no longer use. Remove rules Claude has clearly internalized (if it never makes a particular mistake anymore, the rule might be unnecessary). Consolidate overlapping rules. A lean 80-line file outperforms a sprawling 500-line file because the signal-to-noise ratio is higher.

5. Version control your CLAUDE.md. Track it in git. Review changes in pull requests. This is especially important for teams — a team member might add a rule that conflicts with existing conventions. PR review catches these conflicts before they confuse Claude.

6. Test your rules. After adding a new rule, start a fresh Claude Code session and give it a task that would trigger the rule. If Claude ignores it, the rule might be too vague or buried among too many other rules. Rewrite it to be more specific and prominent.

Common Mistakes That Make CLAUDE.md Useless

Some patterns reliably reduce CLAUDE.md’s effectiveness. Avoid these.

Making it too long. A 1,000-line CLAUDE.md file is not a sign of thoroughness — it is a sign of insufficient editing. When every rule competes for attention in the context window, none of them get adequate weight. The most effective CLAUDE.md files are 50–200 lines. If yours is longer, you almost certainly have redundant rules, rules that are too granular (“use a newline after opening braces” — this is what a linter is for), or rules that belong in documentation rather than AI configuration.

Making it too vague. “Write good code” teaches Claude nothing. “Follow best practices” is meaningless. “Be careful with security” adds zero value. Every rule must be specific enough that a developer could determine whether a piece of code complies with it. “Sanitize all user inputs through the /lib/sanitize.ts utility before passing them to database queries” — that is a rule Claude can follow.

Never updating it. A CLAUDE.md file written once and never touched becomes stale as the project evolves. Libraries get replaced, conventions change, new patterns emerge. The feedback loop technique (described above) ensures continuous improvement, but only if you actually use it. If you find yourself correcting Claude on the same issue repeatedly and your CLAUDE.md does not have a rule for it, you are choosing to waste time.

Duplicating what linters already enforce. If your project has ESLint configured with specific rules, you do not need to repeat those rules in CLAUDE.md. Claude Code runs linters and reads their output. Focus CLAUDE.md on higher-level architectural decisions and patterns that linters cannot enforce — code organization, naming conventions for domain concepts, which libraries to use for which tasks, and business logic patterns.

Contradicting yourself. If one section says “use Zustand for state management” and another says “prefer React Context for shared state,” Claude will be confused and inconsistent. Review your CLAUDE.md for contradictions, especially after it has grown through multiple feedback loop additions.

Boris Cherny’s Top Advice: “Ruthlessly Edit Over Time”

Boris Cherny has been one of the most vocal advocates for CLAUDE.md as a productivity lever. His core advice boils down to three principles that apply to the file.

First, let Claude write the initial draft. Claude can analyze your codebase and generate a surprisingly accurate set of conventions and rules. Use this as your starting point rather than writing everything from scratch. You will still need to review and edit — Claude might misidentify some patterns or miss context it cannot infer from code alone — but it handles 70–80% of the initial content.

Second, use the feedback loop religiously. Every time you correct Claude, make it a habit to say “add this to CLAUDE.md.” This is the mechanism that turns a static configuration file into a living knowledge base. Over weeks of use, the file accumulates precisely the rules that matter most for your project — the rules that were born from real mistakes and real corrections.

Third, ruthlessly edit over time. Cherny stresses that CLAUDE.md is not append-only. Rules that no longer apply should be deleted. Rules that are too verbose should be tightened. Rules that overlap should be merged. The file should get better over time, not just longer. A well-pruned 80-line CLAUDE.md outperforms a bloated 400-line version because every rule gets more weight in the context window. For more of Cherny’s techniques, read our full breakdown of his Claude Code tips and workflow.

Advanced Techniques

Once you are comfortable with the basics, several advanced techniques can push CLAUDE.md further.

Conditional rules with context markers. You can write rules that apply only in certain situations: “When working on migration files: always use raw SQL, never use the ORM builder. When working on API routes: always validate request bodies with Zod schemas.” Claude is sophisticated enough to apply rules selectively based on context.

Template sections for common tasks. If you frequently ask Claude to perform specific types of work, include templates: “When creating a new API endpoint, follow this pattern: create a route in /app/api/, a schema in /schemas/, a service in /services/, and a test in /tests/api/. Register the route in the router.” This turns a complex multi-file task into a single instruction.

Links to documentation. While Claude Code cannot browse the web during a session, you can include file paths: “For API documentation, refer to /docs/api-spec.md.” Claude can read local files, so pointing it to detailed documentation files keeps your CLAUDE.md concise while still giving it access to comprehensive references.

Team CLAUDE.md as onboarding tool. Several engineering teams have reported using CLAUDE.md as an accelerated onboarding document. New developers read the CLAUDE.md to understand the project’s conventions faster than reading through scattered documentation. The file’s concise, imperative style makes it one of the most efficient ways to communicate “how we do things here” — both to humans and AI.

Use STACK to Write Better CLAUDE.md Rules

The STACK framework from Beginners in AI applies directly to writing CLAUDE.md rules. STACK stands for Situation, Task, Action, Constraints, Knowledge. When you write a CLAUDE.md rule, you are essentially writing a compressed STACK prompt: the Situation is the project context, the Task is what Claude should do, the Action is the specific behavior, the Constraints are the “do not” rules, and the Knowledge is the architectural decisions and reasoning you include.

A rule like “When creating React components (Situation), generate a PascalCase .tsx file (Task/Action) in /components/features/ (Action), never use default exports except for pages (Constraint), because we use named exports for better refactoring support (Knowledge)” follows STACK perfectly. This framework ensures your rules are complete and unambiguous.

Related Articles

• Claude Code: Complete Beginners Guide — Full walkthrough of installation, setup, and core workflows
• Boris Cherny’s Claude Code Tips — Deep dive into the expert techniques that inspired this guide
• Claude for Coding — How to use Claude as a coding assistant across all skill levels
• How to Use Claude AI — Comprehensive guide from first login to advanced features
• Best Claude Prompts — Prompt templates and techniques for getting better results

Frequently Asked Questions

What is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. It serves as persistent memory for the AI, storing your project conventions, coding standards, architectural decisions, preferred tools, testing patterns, and lessons learned from previous sessions. Without it, Claude Code starts every session with zero knowledge of your project’s specific requirements. With it, Claude immediately follows your rules and avoids past mistakes. The file lives in your project root directory alongside your other configuration files.

Where do I put CLAUDE.md?

The primary location is your project root directory — the same folder as your package.json, pyproject.toml, or .git folder. Claude Code also supports a global file at ~/.claude/CLAUDE.md for preferences that apply across all projects, and subdirectory files for monorepos. For most developers, a single CLAUDE.md in the project root is sufficient. Commit it to version control so your entire team benefits from the shared rules.

How long should CLAUDE.md be?

The sweet spot is 50 to 200 lines. Start with 10–15 rules covering your most important conventions and build commands, then grow it organically through the feedback loop technique. Files under 50 lines often miss important context. Files over 200 lines often contain redundant rules, linter-level details that belong in configuration files, or rules so specific they rarely apply. Boris Cherny advises “ruthlessly edit over time” — prune monthly, consolidate overlapping rules, and delete anything that no longer applies. Quality and specificity always beat quantity.

Does CLAUDE.md work with other AI tools?

No. CLAUDE.md is specific to Anthropic’s Claude Code tool. Other AI coding assistants use their own configuration files: Cursor uses .cursorrules, GitHub Copilot uses .github/copilot-instructions.md, and Windsurf uses .windsurfrules. The concepts are identical — all of these files give the AI persistent project context — but the file names and specific loading behaviors differ. If you use multiple AI tools, you may want to maintain a shared “source” document and generate each tool-specific config from it. The Grokipedia article on AI-assisted software development provides additional context on how these tools compare.

Can Claude update its own CLAUDE.md?

Yes. This is one of the most powerful features and the foundation of the feedback loop technique. When you tell Claude Code “update your CLAUDE.md so you don’t make that mistake again,” it will open the file, add a specific rule based on the correction, and save it. Claude can also generate an entire CLAUDE.md from scratch by analyzing your codebase — Boris Cherny calls this “eerily good.” You should always review what Claude writes and edit it for accuracy and conciseness, but letting Claude draft rules for itself is a legitimate and effective workflow that Anthropic’s own engineering teams use. According to Anthropic’s documentation on Claude Code memory, the /memory command also supports saving key-value pairs to CLAUDE.md automatically during sessions.