CLAUDE.md: Write It Once, Start Every Session Right

The payoff is less repeated onboarding. As a hypothetical time budget, four developers repeating three minutes of setup across five sessions each spend 60 minutes a week restating context. A shared instruction file gives you one place to maintain that setup. Measure the repetition it removes against the time you spend maintaining it; there is no guaranteed saving.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file containing instructions Claude Code reads for your project, your personal workflow or your organization. Think of it as the team's standing brief. Auto memory is the working notebook Claude keeps alongside it. You own the brief; Claude writes the notebook. Both become context for its decisions. Anthropic's memory guide

The useful distinction is what should remain true across sessions. A required test command belongs in the brief. Your feedback that a particular explanation was too detailed can become a learned preference. The current task belongs in the conversation.

This division follows the official directory guide. You do not need a large .claude folder to begin. Start with the brief, then add another file only when it has a clear job.

Where to Put CLAUDE.md: Project, User and Organization

For a small team, commit one project file at the repository root. Put personal preferences in your user file, so teammates do not inherit them accidentally.

These are the documented scopes and locations. Managed organization files cannot be excluded through individual settings, but their prose still serves as guidance.

Claude loads instruction files from the working directory and its ancestors at launch. Instructions in subdirectories load as it works with files there. The files are combined, so adding a more specific file does not erase conflicting instructions elsewhere. Keep your user and project guidance consistent. Loading behavior

A Starter CLAUDE.md for a Small Product Team

Write down the decisions that prevent repeated mistakes. The example below assumes a TypeScript product using pnpm, with lint, typecheck and test scripts already defined. Replace those commands and paths with ones you have verified in your repository before committing it.

Each section has a one-line explanation of why it exists. These are proposed team conventions, not Anthropic defaults.

# Product Team Instructions

## Product Intent
Why: Keep implementation tied to the customer problem.
- Read the task's acceptance criteria before changing code.
- Ask when missing product behavior would change the solution.

## Working Commands
Why: Make verification repeatable across teammates and sessions.
- Use pnpm for this repository; keep pnpm-lock.yaml consistent.
- Run pnpm lint and pnpm typecheck for application changes.
- Run pnpm test for behavior changes; report any checks not run.

## Change Boundaries
Why: Keep reviews small and dependencies deliberate.
- Follow nearby patterns before adding a new abstraction.
- Ask before adding a runtime dependency or changing public APIs.
- Keep unrelated cleanup out of the change.

## Data and Migrations
Why: Make data changes reviewable and reversible where possible.
- Add schema changes through the existing migration workflow.
- Describe compatibility and rollback concerns in the handoff.
- Use synthetic data in examples and tests.

## Quality
Why: Catch user-visible regressions before review.
- Add a focused regression test when fixing a behavior bug.
- Check loading, empty and error states when changing UI flows.
- State remaining uncertainty instead of calling unchecked work done.

## Project References
Why: Point to maintained decisions without copying the whole wiki.
- Read docs/product-decisions.md when product behavior is unclear.
- Read docs/release-checklist.md before preparing a release.

The references in this example are ordinary instructions to consult documents when relevant. Create those documents or replace the paths. They are intentionally not automatic imports.

Save the file, start a session from the repository, and run /context to check the startup memory list. Use /memory to open and edit the instruction file. Then give Claude a small real task and check whether the commands and boundaries help. Inspecting memory

Keep File-Type Rules Out of the Main Brief

Move a rule into .claude/rules/ when most tasks do not need it. For example, a frontend change should not carry every convention for your API handlers.

Create .claude/rules/api.md with a paths header. A glob is a filename pattern; src/api/**/*.ts selects TypeScript files inside that directory and its subdirectories.

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate external input before passing it to application logic.
- Use the existing error response format.
- Add a focused test when changing an endpoint's behavior.

The pattern controls when this instruction enters context. Without paths, the rule loads unconditionally at startup. Merely splitting a long brief into several rule files will not save context unless the loading is scoped. Path-specific rules

Use Imports to Share Text, Not to Hide Its Context Cost

An import such as @docs/team-conventions.md inside CLAUDE.md pulls that file into context at launch. Relative paths resolve from the file containing the import. Put the actual import outside Markdown backticks or code fences, which keep it literal. Project imports outside your working directory prompt for approval. Import syntax

Import a short convention another team already maintains when it belongs in every session. For a long release checklist, prefer a plain reference like the starter uses. An import reorganizes the brief; it does not reduce how much Claude reads at startup.

Already Have AGENTS.md? Keep One Source of Instructions

Claude Code can use AGENTS.md directly instead of CLAUDE.md, starting with version 2.1.277 when that support is available. The default has an important condition: there must be no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or its ancestors. Your user and organization instruction files do not prevent this fallback. AGENTS.md loading

That makes CLAUDE.local.md an easy source of confusion. Adding personal project notes can change which shared instruction file loads for you.

If you need both files, open /config and set Project instructions to claude-md-and-agents-md. Alternatively, put @AGENTS.md in a neighboring CLAUDE.md; that import also works when direct AGENTS.md support is unavailable. Avoid maintaining two copies of the team's rules. Our AGENTS.md setup guide covers that choice in more detail.

Claude Code Memory: Let Auto Memory Keep the Learned Notes

Auto memory lets Claude save useful preferences, corrections and project context between conversations. It decides what is worth keeping and may save nothing in a session. It is enabled by default in local sessions. Auto memory

By default, the files live at ~/.claude/projects/<project>/memory/. Within the same repository, worktrees and subdirectories share that memory directory on your machine. A worktree is another checkout of the repository, so starting work on a branch there does not give you an independent notebook. These files are not automatically shared with teammates, other machines or cloud environments. Storage location

MEMORY.md is the index. At session start, Claude loads its first 200 lines or 25KB, whichever comes first. Detailed topic files are read when needed. That threshold describes startup loading of the index, not the total amount of memory you can store. How auto memory loads

Use /memory as the front door: it lists memory locations, opens files in your editor, offers the auto-memory folder and lets you toggle auto memory. Use /context when you need to verify which CLAUDE.md and rules files loaded at launch. Memory controls

Be explicit about the destination. “Remember that I prefer shorter handoffs” asks for a learned note. “Add our required test command to CLAUDE.md” asks for a maintained instruction. A rule the whole team needs should not depend on a note in one developer's home directory.

Do not assume an ordinary subagent receives this notebook. The main conversation's auto memory is not loaded into ordinary subagents; forks that inherit the parent conversation are an exception, and subagents can have their own configured memory. See our Claude Code subagents guide when you separate work between agents. Memory behavior for subagents

How to Turn Auto Memory Off

Choose the control that matches your intent:

• Your user setting: open /memory and switch auto memory off. The toggle saves autoMemoryEnabled in ~/.claude/settings.json.
• One project: set "autoMemoryEnabled": false in its settings. Use .claude/settings.json for a shared project setting or .claude/settings.local.json for your local override.
• An environment-controlled launch: set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

These are the documented disable controls and settings locations. Disabling auto memory leaves the separate CLAUDE.md instruction mechanism available. If you want old notes removed as well, inspect and delete those Markdown files explicitly.

A Monthly Auto-Memory Cleanup

Treat this as a short editorial review of what Claude will carry into future work. The monthly cadence is a suggested team habit, not a product requirement.

1. Open /memory and browse the auto-memory folder. Read MEMORY.md, then follow its references to the actual notes.
2. Delete expired context. Remove completed deadlines, abandoned plans and exceptions that no longer apply. Confirm uncertain notes against the current project.
3. Merge repeated corrections. Keep one accurate statement instead of several slightly different versions.
4. Promote durable team decisions. Move a convention everyone needs into the committed CLAUDE.md or a scoped rule, then remove the redundant personal note.
5. Shorten the index. Keep brief pointers in MEMORY.md and detail in topic files. Check both its line count and byte size against the startup threshold.
6. Try a fresh session. Verify the instruction list with /context and check the next real task for stale advice.

Auto-memory files are editable Markdown, and transcript retention does not automatically clean them out. Someone still needs to retire obsolete notes. Editing and retention

Five Places This Setup Pays Off

Start where repeated corrections are already slowing reviews. These are proposed workflows, ranked by likely usefulness to a small product team.

Two Small Things Worth Building Around This

The strongest opportunity is a repository instruction audit. A small team could pay for a review that verifies commands, finds conflicting guidance and proposes a short brief plus scoped rules. The smallest useful deliverable is a reviewed pull request and a repeatable audit checklist. DataForSEO estimates 260 US monthly searches for “claude project instructions.” That broad query includes interest beyond Claude Code; it is a discovery signal, not a buyer count. A generic template is easy to copy, so the paid value would have to be repository-specific judgment.

A local memory hygiene report could help teams with many active repositories. Its first version could flag oversized indexes, missing topic references and candidate stale notes, then let the developer review edits. DataForSEO estimates 1,300 US monthly searches for “claude code memory.” That shows interest in the problem, not demand for this particular tool. The catch is substantial: a file's age cannot tell you whether a decision is obsolete. Keep semantic decisions with the person who knows the project.

Both estimates are US English keyword-overview results retrieved on October 11, 2026 through the site's DataForSEO research integration. These are proposed products, not features built into Claude Code. For one small repository, start with the file and monthly review before buying or building either.

Memory Is Context, Not Enforcement

Writing “never do this” in CLAUDE.md does not make an action impossible. The same applies to auto memory and organization-wide prose. Claude can misinterpret a vague instruction or encounter contradictory guidance. Anthropic's warning

Use a PreToolUse hook, a control that runs before a tool action, when you need to block that action regardless of Claude's decision. A reminder about protected files can explain team intent; the blocking behavior needs an implemented control. Our Claude Code hooks configuration guide covers the hook setup.

For context size, aim for a brief someone can actually maintain. Anthropic recommends keeping individual CLAUDE.md files under 200 lines, but that recommendation is separate from the MEMORY.md startup cutoff. Do not pad your starter to meet a supposed quota, or move everything into imports and assume it became cheaper. Writing effective instructions

Questions a Small Team Actually Asks

Your Monday move: take the corrections from your last few sessions, turn the recurring team decisions into one reviewed CLAUDE.md, and test it on a small task. Put the monthly memory review on the team's calendar.

If you need help turning these conventions into a reliable development workflow, see our AI production systems service.