CLAUDE.md Guide: How to Give Claude Code Memory and Project Rules

What is CLAUDE.md?

CLAUDE.md is a markdown file you add to your project root that Claude Code reads at the start of every session. The documentation describes using it to set coding standards, architecture decisions, preferred libraries, and review checklists.

Think of it as the briefing you would give a capable new hire on their first morning: how to run the tests, where things live, what the team insists on, and what to never touch. Without it, every session starts from zero and you repeat yourself.

What should go in a CLAUDE.md?

Include what Claude cannot infer quickly from the code and what you would otherwise repeat in every prompt.

• Commands. How to build, run, lint, and test, exactly as you type them.
• Conventions. Naming, formatting, error handling, and patterns your team prefers.
• Architecture. A few lines on how the pieces fit, and where to look first.
• Guardrails. Directories or files not to modify, and operations that need approval.
• Definition of done. For example, "tests pass and the changelog is updated."

# Project notes

## Commands - Install: npm ci - Test: npm test - Lint: npm run lint

## Conventions - TypeScript strict mode. No any without a comment explaining why. - Prefer small pure functions. Keep side effects at the edges.

## Do not - Edit files under /generated. They are overwritten by the build. - Add dependencies without asking. ```

What should you leave out?

Leave out anything long, obvious, or likely to go stale. A bloated CLAUDE.md dilutes the rules that matter and costs attention on every session.

• Do not paste whole style guides. Link or summarize them.
• Do not include secrets, tokens, or personal data.
• Do not duplicate what linters and formatters already enforce.
• Do not write vague advice like "write clean code." Write the specific rule.

A useful test: if you removed a line and no behavior would change, remove it.

How does CLAUDE.md relate to AGENTS.md and auto memory?

Claude Code can read an existing AGENTS.md in place of a CLAUDE.md, according to the documentation. This matters for teams that use more than one coding agent, because you can maintain a single instruction file rather than two that drift apart. AGENTS.md is also used in OpenAI’s Codex; see our AGENTS.md guide.

Claude Code also builds auto memory as it works, saving learnings across sessions without you writing anything. Treat auto memory as a convenience and CLAUDE.md as the source of truth your team reviews. Rules that matter should be written down where a person can read and approve them.

How should teams maintain CLAUDE.md?

Treat it like code. Keep it in version control, review changes in pull requests, and assign an owner. When Claude makes the same mistake twice, that is a signal to add a line. When a rule no longer applies, delete it.

A short review ritual helps: once a month, read the file top to bottom, run a typical task, and see whether the instructions still produce the right behavior. In training, we have participants write a first CLAUDE.md for their own project during the workshop, then run the same task with and without it. The difference is usually convincing without any lecture.

Related: Claude Code for beginners, and hooks, skills, and subagents for rules you need enforced rather than suggested.

What does the .claude directory contain, and where does CLAUDE.md fit?

CLAUDE.md is one file in a larger structure. Anthropic’s documentation describes the .claude directory in your project and in your home folder as where Claude Code reads instructions, settings, skills, subagents, and memory. Most people only edit CLAUDE.md and settings.json; the rest is optional.

Commit project files to share them with your team. Personal files in your home directory apply across all your projects. Organization-managed settings can override personal and project settings, which is how administrators enforce rules that must hold.

What does a good CLAUDE.md template look like for a team?

Start from a short template and let real mistakes earn new lines. Keep each section to a few lines.

# Project: [name]

## What this is [Two sentences on purpose and users.]

## Commands - Install: [command] - Dev: [command] - Test: [command] # run before saying a task is done - Lint: [command]

## Architecture - [Folder] holds [what]. Start in [file] for [what].

## Conventions - [Language/framework conventions in one line each] - Prefer small, pure functions. Keep side effects at the edges.

## Boundaries - Always: run tests and lint before finishing. - Ask first: adding dependencies, changing schemas. - Never: commit secrets, edit generated files, push to main. ```

The "always, ask first, never" structure mirrors guidance in GitHub’s analysis of AGENTS.md files across thousands of repositories, which found that naming what the agent must never touch, especially secrets, is among the most useful constraints. Because Claude Code can read AGENTS.md in place of CLAUDE.md, the same template works for either; see our AGENTS.md guide.

Frequently asked questions

Product features, plans, and limits change often. This guide reflects the vendor documentation listed above as of November 2026. Check the vendor’s current documentation before you make purchasing or policy decisions. TechStack Consulting is an independent training firm and is not affiliated with Anthropic or OpenAI.