Guide

Claude Code projects: CLAUDE.md, memory and where to start it

Harrowtech.ai · last checked 13 October 2026

How Claude Code works with a project: start it in the right folder, what goes in CLAUDE.md, where the file can live, and how its separate auto memory differs. It ends with the other thing “Claude Code projects” can mean: the cloud Projects feature, and how it uses the same CLAUDE.md files.

Harrowtech.ai is independent of Anthropic. Every outside fact below was read on Anthropic's or the vendor's own pages on 13 October 2026. Where a page said nothing, this guide says nothing.

Start it in the project folder

Claude Code works on the folder you start it in. Anthropic’s quickstart says to open a terminal in your project and run:

cd /path/to/your/project
claude

Anthropic says that when you run claude in a directory, it gains access to the files in that directory and its subdirectories, plus files elsewhere with your permission. It also sees your git state and your CLAUDE.md.

Each conversation is a session tied to your current directory. claude --continue (or -c) picks up the most recent one in that folder, and claude --resume lets you choose. Each new session starts with a fresh context window, with no memory of the last conversation. Two things carry knowledge across sessions: CLAUDE.md files and auto memory.

CLAUDE.md in one paragraph

A CLAUDE.md file is a plain markdown file of instructions that Claude reads at the start of every session. You write it. Anthropic says to keep it to facts Claude should hold in every session: build commands, conventions, project layout and “always do X” rules. It is context, not enforced configuration. If an action must be blocked or must always happen, Anthropic points to hooks, which run as shell commands whatever Claude decides.

Where the file can live

Anthropic lists four places, from broadest to most specific:

Managed policy	For an organisation, set by IT. `/etc/claude-code/CLAUDE.md` on Linux and WSL, `/Library/Application Support/ClaudeCode/CLAUDE.md` on macOS, `C:\Program Files\ClaudeCode\CLAUDE.md` on Windows.
User	`~/.claude/CLAUDE.md`. Your preferences across all projects.
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`. Shared with your team through source control.
Local	`./CLAUDE.local.md`. Personal to this project. Anthropic says to add it to `.gitignore`.

The files are joined together, not swapped for each other. Claude Code loads the CLAUDE.md in your working directory and in every directory above it. If you start in foo/bar/, it reads foo/CLAUDE.md and then foo/bar/CLAUDE.md, so the instructions nearest to you come last. Files in subdirectories below you load on demand, once Claude reads or edits a file there.

If your repository already has an AGENTS.md written for other coding tools, Anthropic says Claude Code can read it in place of a CLAUDE.md, from version 2.1.277. By default it does so only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. If there is one, Claude reads that and skips AGENTS.md, unless you change the Project instructions setting in /config.

Create one with /init

Run /init inside a session. Per the docs, Claude analyses your codebase and writes a starting file with the build commands, test instructions and conventions it finds. If a file exists already, /init suggests improvements instead of overwriting it. Anthropic then advises refining it with instructions Claude would not discover by itself.

To check that a file loaded, run /context and look under Memory files. A CLAUDE.md in a subdirectory will not appear there, because it loads on demand.

What to put in it

Anthropic’s best-practices page gives a test for every line: “Would removing this cause Claude to make mistakes?” If not, cut it. Its table of what to include and exclude, in short:

Include	Commands Claude cannot guess. Style rules that differ from defaults. Test instructions and the preferred test runner. Branch and pull request conventions. Architecture decisions specific to your project. Environment quirks such as required variables. Gotchas that are not obvious.
Leave out	Anything Claude can work out by reading the code. Standard language conventions. Long API documentation (link to it). Information that changes often. Tutorials. File-by-file descriptions. Platitudes like “write clean code”.

On how to word things, the memory page says to be concrete enough to check. “Use 2-space indentation” works better than “Format code properly”, and “Run npm test before committing” better than “Test your changes”.

A small example, written by us as an illustration and not taken from Anthropic:

# Commands
- Build: npm run build
- Test one file: npm test -- path/to/file.test.js

# Conventions
- API handlers live in src/api/handlers/
- Branch names: feature/short-description

# Gotchas
- Tests need a local Redis running on port 6379

Keep it short

Anthropic targets under 200 lines per CLAUDE.md file, noting that longer files use more context and reduce adherence. Its best-practices page warns that a bloated file makes Claude ignore some of your instructions, and its memory page says that if two instructions contradict, Claude may pick one arbitrarily.

Ways to keep the main file small:

Imports. Write @path/to/file in a CLAUDE.md to pull another file in, up to four hops deep. Anthropic notes imports help organisation but do not save context, because the imported files also load at launch.
Rules folder. Put topic files in .claude/rules/. A rule with a paths entry in its front matter loads only when Claude works on matching files.
Skills. For procedures needed only sometimes, Anthropic suggests a skill, which loads on demand.
Comments. Block-level HTML comments in a CLAUDE.md are removed before the content reaches Claude, so you can leave notes for people without spending context.

To tidy an existing file, the docs describe /doctor prompt-audit, which reports outdated or conflicting instructions and changes nothing until you ask. It needs Claude Code v2.1.283 or later.

Auto memory is separate

Auto memory is notes Claude writes for itself, such as your preferences and corrections. Anthropic says it is on by default in local sessions. Each project gets a folder at ~/.claude/projects/<project>/memory/ with a MEMORY.md index and topic files. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session. The topic files load only when Claude needs them.

The folder is derived from the git repository, so worktrees and subdirectories of one repo share it. It stays on your machine. Run /memory to list your CLAUDE.md files, switch auto memory on or off and open the memory folder. The files are plain markdown that you can edit or delete. If you say “remember that the API tests need a local Redis”, Claude saves it to auto memory. To put something in CLAUDE.md instead, say “add this to CLAUDE.md”.

When context fills up

Claude Code compacts the conversation automatically near the limit, and Anthropic says detailed instructions from early in a chat can be lost. Persistent rules belong in CLAUDE.md, which is re-read each session. You can also add a “Compact Instructions” section to it to control what survives a summary, and /context shows what is using space. For more on this, see Claude Code best practices.

If Claude ignores your file

Run /context and confirm the file is listed. If it is not, Claude cannot see it.
Check it is in a location that loads for your session, as in the table above.
Make the wording more specific.
Look for conflicts between files.
If it must happen every time, use a hook instead.

Anthropic’s Debug your configuration page adds the commands that show what actually loaded: /memory for memory file locations, /skills, /hooks, /mcp, /permissions for the allow and deny rules in effect, and /status for which settings sources are active. Its point is that CLAUDE.md is guidance, while permissions and hooks are the tools for anything that must never happen.

The other meaning: Claude Code Projects

“Projects” is also the name of a separate Claude Code feature, and it is not a project folder. Anthropic describes a project as one ongoing conversation in which Claude coordinates a stream of related work: you send it tasks, and it starts a thread for each one. Each thread is usually a cloud session, threads run in parallel, and an Overview pane shows which ones finished and which are waiting for you.

Who can use it	Public beta on Pro and Max plans, rolling out gradually. Anthropic says it is not available on Team or Enterprise plans yet, and that if Projects is missing from your sidebar, the rollout has not reached your account.
Where	At claude.ai/code, in the Code tab of the desktop app, and in the Claude mobile app. Not in the terminal CLI, the VS Code extension or the JetBrains plugin. A session you start yourself in the terminal cannot be added to a project.
What each thread loads	Each cloud thread clones every repository in the project and loads `CLAUDE.md` and skills from all of them. It does not pick up anything from the Claude Code setup on your own machine.
Its own instructions and memory	Project instructions, up to 16,000 characters, are sent to every new thread. Project memory is a set of notes Claude keeps for the project. Anthropic says it is separate from your repositories’ `CLAUDE.md` files and from the auto memory on your machine, even though it also uses a `MEMORY.md` index.

Anthropic’s rule for splitting the two: put instructions about a repository, such as its build commands, in that repository’s CLAUDE.md, and put notes about the project as a whole in project instructions or project memory. In practice a good CLAUDE.md serves both worlds, your local sessions and every cloud thread a project starts, so the advice earlier on this page applies to both. The older Projects in claude.ai chat and Cowork, which group conversations and reference files, are a different thing again.

What this guide does not cover

It does not walk through setting up a Projects workspace (the GitHub App, cloud environments, running a thread on your own computer), monorepo setups, or managed organisation policy beyond the file locations. The wider docs are mapped in Claude Code docs: where to start, and a plain overview of the tool is What is Claude Code?. Slash commands are listed in commands and shortcuts.

Sources

How Claude remembers your project, read 13 October 2026
Best practices, read 13 October 2026
How Claude Code works, read 13 October 2026
Quickstart, read 13 October 2026
Let Claude coordinate ongoing work with Projects, read 13 October 2026
Debug your configuration, read 13 October 2026

The claude --continue and --resume flags were also confirmed in claude --help on version 2.1.296.