The most ironic thing? Complaining “I have to re-explain the project to Claude every session” while your project root doesn’t have a CLAUDE.md.

Don’t laugh. I was in that exact spot.

Turns out there’s a shortcut — run /init. Claude analyzes your project structure, detects build tools and test frameworks, and generates a starting CLAUDE.md. If you already have one, /init suggests improvements instead of overwriting it.

What CLAUDE.md is for

Claude Code reads this file at startup and uses it as the starting point for understanding your project. How to run tests, how the directory is organized, what conventions to follow — put it there, and it just knows.

Category one: commands

This is the most common use — save the commands so you never have to repeat them:

## Commands
- Test: npm test
- Build: npm run build
- Single test: npx jest src/xxx.test.ts
- Lint: npx eslint src/

Claude knows what to run without you saying “run the tests” every time.

Category two: architecture

Things Claude can’t infer from code alone:

## Architecture
- State management uses Zustand, not Redux
- All API calls go through src/api/
- Don't modify files in src/core/, extend through the interface instead

Category three: conventions

Rules that linters can’t enforce but reviewers will catch:

## Conventions
- Component files use PascalCase
- Every component needs a unit test
- No hardcoded strings — use i18n

What doesn’t belong

CLAUDE.md’s most common problem is being too long. When real instructions drown in noise, the model treats everything equally, which means nothing sticks.

• Personality prompts — “you’re a senior engineer” is already in the system prompt
• Generic rules everyone knows
• Speculative rules — wait until Claude actually makes a mistake, then add one rule

I start with the bare minimum. Use it for a while. Every time Claude makes a mistake, I add one rule. That way every line in CLAUDE.md has earned its place.

The official docs recommend keeping CLAUDE.md under 200 lines. Anything longer and Claude starts ignoring half of it. If you have a lot of rules, split them up:

• .claude/rules/ directory: scoped by file path. A rule with paths: ["src/api/**/*.ts"] only loads when Claude works with those files. Saves context.
• Skills: infrequently used reference material goes into skills, loaded on demand.
• @ imports: CLAUDE.md can import other files with @README.md or @docs/guide.md syntax.

There are two more CLAUDE.md files

CLAUDE.local.md lives in your project root but isn’t checked into git. Put personal overrides there — your local sandbox URLs, test credentials, personal preferences.

~/.claude/CLAUDE.md applies to every project on your machine. Put personal coding style preferences and universal workflow rules there.

Auto Memory: Claude takes its own notes

CLAUDE.md is what you write. Auto Memory is what Claude writes itself. Build commands, debugging insights, preferences it discovers from your corrections — Claude saves them to ~/.claude/projects/<project>/memory/ and reads them back next session. You don’t have to write anything.

Run /memory to browse what it saved. Plain markdown, editable or deletable anytime.

One more thing: permissions

Besides CLAUDE.md, Claude Code has settings.json that controls what the agent can do.

Three permission levels:

• allow: do it, no need to ask
• ask: ask me each time
• deny: not allowed

My setup is deny-everything by default, then open up as needed:

{
  "permissions": {
    "default": "deny",
    "allow": ["read", "edit", "search"],
    "deny": ["run:curl", "run:wget"]
  }
}

Blocking network calls by default is recommended for everyone — you don’t want Claude downloading random packages on its own.

Article Link: