How to Use CLAUDE.md to Give Claude Code Persistent Project Context

Every Claude Code session begins with a fresh context window. Claude does not automatically remember everything you explained in a previous session, such as your technology stack, project structure, architectural decisions, coding conventions, or preferred workflows.

A fresh context window is useful because it gives Claude room to reason about the current task without carrying an unlimited conversation history. However, it also means you may find yourself repeatedly explaining the same project details—or waiting for Claude to explore the codebase again.

A CLAUDE.md file solves much of this problem by giving Claude Code persistent, project-specific instructions.

In this tutorial, you’ll learn:

• What a CLAUDE.md file is
• How Claude Code loads project instructions
• How to generate a starting file with /init
• What information belongs in the file
• What should be removed
• Why shorter instructions are usually more effective
• How to maintain the file as your project evolves

What Is a CLAUDE.md File?

CLAUDE.md is a Markdown file containing instructions and context you want Claude Code to use across sessions. It functions like onboarding documentation written specifically for your coding agent.

You can use it to explain:

• What the application does
• Which frameworks and libraries it uses
• How the project is organized
• Important architectural decisions
• Commands for development, testing, linting, and building
• Naming and coding conventions
• Rules Claude should follow when modifying the project

It is similar in spirit to a README.md, but the audience and purpose are different.

A README.md primarily helps people understand, install, and use a project. A CLAUDE.md file tells Claude how to work effectively inside that project.

According to the official Claude Code documentation, project instructions can live at either:

./CLAUDE.md

or:

./.claude/CLAUDE.md

For a simple application, placing CLAUDE.md at the repository root makes it easy to discover, review, and commit with the rest of the project.

Why Persistent Project Instructions Matter

Imagine beginning a new Claude Code session and asking:

Add filtering to the workout list.

Without additional context, Claude may need to inspect the project before it can answer several basic questions:

• Is this a React application?
• Does it use JavaScript or TypeScript?
• Where are the workout components located?
• Does the project use a router?
• Where is application state stored?
• Is there a backend or database?
• Which commands verify a change?
• What naming and styling conventions should new code follow?

Claude can often discover these facts from the repository, but repeating that exploration uses time and context. A concise CLAUDE.md file provides the most important answers immediately.

It also improves consistency. Claude is less likely to introduce React Router into a deliberately router-free sample project or invent a backend when the file clearly states that data is persisted with localStorage.

CLAUDE.md Is Context, Not Enforcement

A CLAUDE.md file guides Claude’s behavior, but it is not a configuration system that guarantees compliance. Claude receives the file as context and instructions, then reasons about them alongside your prompt and the codebase.

That distinction matters. If an action must be technically blocked—for example, preventing access to a protected command—use an appropriate permission or hook mechanism rather than relying exclusively on a sentence in CLAUDE.md.

For normal project guidance, however, clear instructions are extremely useful. Specific, concise, noncontradictory rules are more likely to be followed than vague or overloaded documentation.

Generate a Starting CLAUDE.md With /init

Claude Code can inspect your repository and generate an initial project-instructions file.

Open Claude Code from the project directory:

claude

Then run:

/init

Claude analyzes the codebase and proposes a starting CLAUDE.md containing information it can discover, such as:

• Development and build commands
• Test and lint commands
• Frameworks and libraries
• Important directories
• Architectural patterns
• Project conventions

If the project already has a CLAUDE.md, /init can suggest improvements instead of blindly replacing it. Review the proposed content before accepting it.

The generated file is only a starting point. Claude can describe what it observes in the codebase, but you still need to add decisions and intentions that cannot be inferred reliably from code alone.

Review the Generated File

After running /init, open CLAUDE.md from the root of the project.

For the sample workout logger, Claude may identify facts such as:

• It is a browser-based application built with Vite, React, and TypeScript.
• It is a single-page application without a routing library.
• View changes are handled through React state and conditional rendering.
• Workouts contain exercises.
• Data is persisted in localStorage.
• The project currently has no automated test suite.
• Standard Vite commands are available for development and production builds.

These details help future sessions understand the project without rediscovering the same architecture from scratch.

However, generated content may include introductory statements, repetitive descriptions, or details that are obvious from package.json. Remove anything that does not improve Claude’s decisions.

The goal is not to document every file. The goal is to preserve the context Claude should know before working on almost any task.

Add a Clear Project Overview

A generated file may describe the technical structure without clearly stating the purpose of the application. Add a short overview near the top.

For example:

# Project Overview

This is a simple browser-based workout logger built with Vite, React,
and TypeScript. Users create workout sessions and record the exercises,
sets, reps, and weight performed during each workout.

This gives Claude a product-level mental model before it reads the implementation details.

You can ask Claude Code to add the overview for you:

Update CLAUDE.md with a concise project overview near the top.
Explain that this is a browser-based workout logger built with Vite,
React, and TypeScript. Users create workout sessions and record the
exercises, sets, reps, and weight performed during each session.
Do not add generic introductory text or repeat information already
covered elsewhere in the file.

Review the proposed edit and remove unnecessary repetition.

What Belongs in CLAUDE.md?

Add information Claude should know in most sessions and cannot always infer quickly or reliably.

Project purpose

Explain what the application does and how users interact with it. Keep this to a short paragraph.

Technology stack

List the important technologies that affect implementation decisions:

## Technology Stack

- Vite
- React
- TypeScript
- Tailwind CSS
- shadcn/ui
- React Hook Form and Zod for forms and validation

Avoid copying every dependency from package.json. Include only the tools that shape the development workflow or architecture.

Common commands

Document the commands Claude should run when developing or verifying changes:

## Commands

- Start development server: `npm run dev`
- Run linting: `npm run lint`
- Create production build: `npm run build`
- No automated test suite is currently configured

Be accurate. Do not instruct Claude to run a test command that does not exist.

Architecture

Describe decisions that are easy to misunderstand:

## Architecture

- This is a single-page React application with no routing library.
- The root component switches between the workout list and workout
  detail views with React state and conditional rendering.
- A workout contains an array of exercises.
- Data is stored in `localStorage`; the project has no backend.

File locations

Document non-obvious locations Claude should use:

## Project Structure

- Reusable UI components live in `src/components/ui/`.
- Workout feature components live in `src/components/`.
- Shared TypeScript types live in `src/types.ts`.
- General utility functions live in `src/lib/`.

Use paths that match your actual project.

Coding conventions

Write rules that are objective and verifiable:

## Coding Conventions

- Use TypeScript for all application code.
- Use function components and React hooks.
- Keep state updates immutable.
- Reuse existing shadcn/ui components before creating new UI primitives.
- Use React Hook Form with Zod for nontrivial forms.
- Preserve existing component APIs unless the task requires a change.

“Use two-space indentation” is actionable. “Write clean code” is too vague to guide a specific decision.

A Sample CLAUDE.md

Here is a compact example for the workout logger:

# Project Overview

This is a browser-based workout logger built with Vite, React, and
TypeScript. Users create workout sessions and record the exercises,
sets, reps, and weight performed during each workout.

## Commands

- Start development server: `npm run dev`
- Run linting: `npm run lint`
- Create production build: `npm run build`
- No automated test suite is currently configured

## Architecture

- This is a single-page application with no routing library.
- React state controls whether the workout list or detail view is shown.
- Each workout contains an array of exercises.
- Data is persisted in `localStorage`; there is no backend.

## Conventions

- Use TypeScript, function components, and React hooks.
- Keep state updates immutable.
- Reuse existing components and styling patterns.
- Use React Hook Form and Zod for nontrivial forms.
- Run `npm run lint` and `npm run build` after meaningful changes.

This file is short, but it answers the questions most likely to affect Claude’s implementation choices.

Keep the File Concise

Claude Code loads project instructions into its context. Every unnecessary paragraph competes with your conversation, source code, tool results, and the reasoning required for the current task.

Anthropic currently recommends targeting fewer than 200 lines per CLAUDE.md file. That is an upper guideline, not a target to fill. A small project may need only a few dozen lines.

Before adding a section, ask:

• Does Claude need this in most sessions?
• Is this information difficult to infer from the project?
• Will it materially change implementation decisions?
• Is the rule concrete enough to verify?
• Does it duplicate another instruction?
• Could it become outdated quickly?

If the answer is no, leave it out or place it in more appropriate documentation.

What Should Not Go in CLAUDE.md?

Avoid turning the file into a complete encyclopedia of the project.

Usually, you should not include:

• Long explanations of basic framework concepts
• A list of every dependency
• Documentation copied from external libraries
• Temporary requirements for a single task
• Large code examples
• Detailed descriptions of obvious files
• Stale implementation history
• Personal or secret information
• Contradictory rules

Task-specific requirements belong in the task prompt or a dedicated specification. Sensitive local preferences can be placed in CLAUDE.local.md, which should be excluded from version control.

For a larger codebase, use .claude/rules/ to organize instructions by topic or apply them only to matching paths. This prevents frontend-only rules, for example, from occupying context while Claude works on unrelated backend files.

Verify That Claude Loaded the File

Do not assume the file is active simply because it exists. In a Claude Code session, run:

/context

Check the memory-file list to confirm that the expected CLAUDE.md was loaded.

Claude Code can load instruction files from the current directory and parent directories. It may also load more specific instructions when working inside subdirectories. If behavior seems inconsistent, check for additional CLAUDE.md, CLAUDE.local.md, or .claude/rules/ files containing conflicting guidance.

Maintain It as the Project Evolves

A CLAUDE.md file is living documentation. Do not generate it once and forget about it.

Review and update it when:

• The stack changes
• A new architectural pattern is adopted
• Commands are added or renamed
• Files move to different directories
• The team establishes a new convention
• Claude repeats the same project-specific mistake
• A code review reveals context Claude should have known
• You repeatedly type the same correction in new sessions

Also remove instructions that are obsolete, redundant, or contradicted by newer decisions.

A useful maintenance rule is:

If you have to give Claude the same project-specific correction twice, consider whether it belongs in CLAUDE.md.

Commit the shared project file to Git so teammates and future sessions use the same guidance:

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

Review the diff like any other project change. Incorrect agent instructions can influence many future edits, so they deserve careful review.

Final Takeaway

A well-written CLAUDE.md gives Claude Code the stable project context it should know at the beginning of every session. It reduces repeated explanations, limits unnecessary codebase exploration, and makes generated changes more consistent with your architecture and conventions.

The key is restraint. Include the project purpose, essential commands, important architectural decisions, useful file locations, and concrete coding rules. Remove generic filler, duplicated facts, temporary requirements, and details Claude can easily discover elsewhere.

Treat CLAUDE.md as living onboarding documentation for your coding agent: generate a starting point with /init, refine it manually, verify that it loads, and keep it concise as the project changes.