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

1.The CLAUDE.md hierarchy

CLAUDE.md files are instructions you write to give Claude persistent context. They load into every session, so they suit coding standards, workflows and project architecture. Claude Code does not read just one CLAUDE.md. It looks for one at each of four scopes, and each scope reaches a different audience.

IT or DevOps deploys the managed file with configuration management, and it carries organization-wide instructions. The local file is for personal project preferences, and the docs tell you to add it to .gitignore. Specific instructions work better than vague ones: write "Run npm test before committing" rather than "Test your changes". A CLAUDE.md can also pull in other files with @path imports, so a short CLAUDE.md can point to the README, package.json or a separate instructions file.

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

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

Sources1

2.AGENTS.md and path-scoped rules

Claude Code can also read a repository's AGENTS.md. By default it reads one or the other, not both. If a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or any directory above it, Claude reads the CLAUDE.md files and skips AGENTS.md. Three kinds of file don't count toward that switch and keep loading alongside AGENTS.md: your ~/.claude/CLAUDE.md, the managed CLAUDE.md, and .claude/rules/ files. A CLAUDE.md that imports AGENTS.md gets both, through the import. AGENTS.local.md, AGENTS.override.md and anything under .agents/ are never read.

Rules are the modular form of project instructions. You split guidance into files under .claude/rules/, such as code-style.md, testing.md and security.md. A rule can use a paths frontmatter field to apply only to matching files. Personal rules live in ~/.claude/rules/, and a shared rule set can be symlinked into .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

Sources1

3.Agent memory: what Claude writes for itself

Everything so far is written by you. Auto memory is the counterpart that Claude writes: it takes notes from your corrections and preferences and loads them into later sessions. Use CLAUDE.md for rules the team agrees on. Auto memory captures things such as a correction you would otherwise have to repeat next session.

Sources1

4.settings.json: four files and an order of precedence

CLAUDE.md shapes what Claude is told. settings.json configures how Claude Code itself behaves: permissions, hooks, plugins, environment variables and the model. It uses the same scope pattern as CLAUDE.md.

{
  "$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 several levels set the same key, precedence from highest to lowest is: managed settings, then command-line arguments (including JSON passed with --settings), then project local, then shared project, then user. The merge works key by key. A higher level wins for the keys it sets, and lower-level values survive for the keys it leaves out. Nothing you set overrides managed settings. A flag such as --model can only pick from the models your organization allows. Some settings can also change mid-session: /model switches the model and /effort changes effort.

Sources2

5.Setting up a repository for Claude Code

The sources for this lesson do not describe a dedicated initialization command, so this section covers what they do say: which files make up a repository's shared Claude Code setup and which stay personal. The shared layer is ./CLAUDE.md (or .claude/CLAUDE.md), .claude/rules/, .claude/settings.json, .claude/skills/ and .claude/agents/. Teammates only get these once they are committed. Until then a file is just something on your disk.

Claude Code creates some personal files for you. The first time you change a /config option that it stores in user settings, it writes ~/.claude/settings.json. The first time you answer "Yes, and don't ask again" to a permission prompt, it writes .claude/settings.local.json. When it creates that local file, it also adds **/.claude/settings.local.json to your global git excludes. If you create the file by hand, you have to add it to .gitignore yourself. While the local file stays untracked, its allow rules apply without the workspace trust step that the committed file needs.

Sources23

Exam traps

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

1. 1.CLAUDE.local.md is the project file your team shares through source control.Why is that wrong?

   ./CLAUDE.md is the shared project file. CLAUDE.local.md holds your personal preferences for one project, and the docs say to keep it out of git.

   Covered in The CLAUDE.md hierarchy

2. 2.A repository with both AGENTS.md and CLAUDE.md gives Claude both files by default.Why is that wrong?

   Under the default setting, a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it makes Claude read the CLAUDE.md files instead of AGENTS.md. Your user CLAUDE.md does not trigger this switch.

   Covered in AGENTS.md and path-scoped rules

3. 3.Passing a key with --settings at launch overrides whatever the organization has set.Why is that wrong?

   --settings ranks above user, project and local files but below managed settings, so a managed key still wins.

   Covered in settings.json: four files and an order of precedence