Project Memory: CLAUDE.md & AGENTS.md

Every session starts from zero conversational context — Claude doesn't remember last week's session. What it can have, every single time, is a memory file that loads automatically before any work starts. That's the entire point of CLAUDE.md (and the equivalent AGENTS.md, recognized the same way): a place to put the things you'd otherwise repeat in every prompt.

What belongs in it

The useful content is almost always operational, not descriptive — not "this is a React app" (that's obvious from the files), but the things that aren't obvious from reading the code alone:

• The exact commands for testing, linting, building, and running the project locally.
• Conventions that aren't enforced by a linter: naming patterns, where new code of a given kind should live, how errors are typically handled in this codebase.
• Things to actively avoid — a deprecated module nothing should import from anymore, a directory that's generated and shouldn't be hand-edited, a pattern the team moved away from.
• Anything about the review or commit process: commit message conventions, whether to create PRs automatically, branch naming.

A short, accurate file beats a long, stale one. If a rule in CLAUDE.md stops being true, it actively misleads every future session until someone fixes it — which is itself worth remembering: when you ask for a change that contradicts something in the file, that's often a sign the file needs updating too, not just the code.

A minimal example

# Project conventions
 
- Run tests with `npm test`; run a single file with `npm test -- path/to/file.test.ts`.
- Lint with `npm run lint`; this must pass before any commit.
- API routes live under `app/api/`, one folder per resource.
- Don't import from `src/legacy/` — it's frozen and being phased out.
- Commit messages: imperative mood, no period at the end of the summary line.

CLAUDE.md vs AGENTS.md

AGENTS.md is a cross-tool convention for the same idea — project instructions for an AI coding agent — recognized by multiple agentic tools, not just Claude Code. CLAUDE.md is Claude Code's own name for the same concept. You can use either; some projects keep a single AGENTS.md and have CLAUDE.md reference it with an include, so the instructions aren't duplicated across two files for teams using more than one agent.

Scoping memory in larger projects

A single root-level file isn't always the right granularity. Claude Code also reads CLAUDE.md files in subdirectories, so a monorepo can have a root file with company-wide conventions and a package-specific file with that package's own build commands and quirks — loaded only when work touches that part of the tree.

Keeping it current

Treat the memory file as part of the codebase, not a one-time setup step. When a session teaches you something that future sessions would benefit from knowing, add it — you can ask Claude to update CLAUDE.md directly based on what it just learned, which is often faster than writing it by hand.

The next topic, permission modes, covers the other piece of session setup: how much Claude can do without asking first.