Claude Code Project Configuration: CLAUDE.md, Rules, Auto Memory and settings.json

1.The CLAUDE.md hierarchy

A CLAUDE.md file holds instructions you write, and it loads into every session. The hard part is choosing where to put it. There are four scopes. Each one answers a different question: who should this instruction reach, and should it be committed to git?

CLAUDE.local.md is for personal project-specific preferences, such as your sandbox URLs, and you should add it to .gitignore. The project file is what the team shares. If a repository has an AGENTS.md, Claude reads it only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. Your user-level and managed CLAUDE.md files don't count toward that rule.

Write instructions that are specific. 'Use 2-space indentation' works better than 'Format code properly'. Keep each file under about 200 lines, and group related rules under headers. If two instructions contradict each other, Claude may follow either one. You can split a long file with @path imports, but imports don't make it cheaper: the imported files load at launch too.

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

Two built-in slash commands help when an instruction seems to be ignored. /context lists the memory files that actually loaded. /memory opens those files so you can edit them.

Sources1

2.Repository initialization with /init, and path-scoped rules

In a new repository you don't need to write CLAUDE.md from scratch. Run /init and Claude explores the codebase and drafts one, covering build and test commands, a structure overview and any conventions it detects. The draft is only a starting point: review it, delete anything inaccurate, then commit it so the team shares it.

As the project grows, some instructions only matter for part of the code. Put those in Rules: markdown files under .claude/rules/. A rule with a paths frontmatter field loads only when Claude works with files that match its glob patterns, so API conventions don't take up context while Claude edits CSS. You can also keep personal rules in ~/.claude/rules/.

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

---
 ? :
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Sources21

3.Agent memory: auto memory alongside CLAUDE.md

CLAUDE.md holds what you tell Claude. Auto memory holds what Claude learns: it writes its own notes when you correct it or confirm an approach that worked. The two systems differ in who writes them, what they hold and how much of them loads.

Memories are stored under ~/.claude/projects/<project>/memory/. A MEMORY.md index there points to one file per memory. Each memory has a type: user (your role and preferences), feedback (corrections and confirmed approaches), project (ongoing work and decisions that the code doesn't show), or reference (where to find outside information). You control it from settings: autoMemoryDirectory moves the folder, and autoMemoryEnabled turns the feature off.

{
  "autoMemoryEnabled": false
}

Sources1

4.settings.json scopes and precedence

CLAUDE.md tells Claude what to do. settings.json controls what Claude Code allows and how it is configured: permissions, hooks, plugins, environment variables and the model. Settings files have four scopes, like CLAUDE.md, but the local scope works differently in git.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

When the same key is set in more than one place, the highest scope wins. The order is managed settings, then command-line arguments, then project local, then shared project, then user. The --settings flag passes JSON for a single session and sits above all your own files. Nothing you set overrides a managed key. Claude Code creates .claude/settings.local.json itself the first time you give a standing approval on a permission prompt, and keeps it out of your commits. If ~/.claude.json can't be parsed, a -p run prints the error and exits.

Sources3

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Moving parts of a long CLAUDE.md into @imported files saves context.Why is that wrong?

   Imported files also load at launch. They make the file easier to organize but cost the same context. To save context, use path-scoped rules.

   Covered in The CLAUDE.md hierarchy

2. 2.Everything auto memory has saved is loaded into each new session.Why is that wrong?

   Only the start of the memory index loads at session start: the first 200 lines or 25KB.

   Covered in Agent memory: auto memory alongside CLAUDE.md