Settings Hierarchy — Claude Code Guide

Where a rule comes from

The same Claude Code command can behave differently in different repositories or local copies. During diagnosis, it is useful to start with the question: “Where did Claude get this rule?”

Settings have different scopes. Put a rule at the level where it actually belongs instead of duplicating everything in one global file.

The `.claude` directory as an engineering layer

The `.claude/` directory stores service instructions and settings that help Claude work within project agreements. It is not application business logic but a contextual layer for working with it.

At first, it is enough to know the role of the main elements. You do not need to master every extension immediately if the current task does not use it.

• CLAUDE.md — shared project instructions.
• rules/ — focused rules for specific areas.
• skills/, agents/, hooks/, and mcp/ — extended mechanisms for later guide levels.

.claude/
├── CLAUDE.md
├── rules/
├── skills/
├── agents/
├── hooks/
└── mcp/

Review configuration without rushing

1. Make sure the required local repository copy is open.
2. Review the Git state before reading configuration.
3. Inspect .claude/ and read CLAUDE.md first.
4. Then investigate rules/ or other directories if they relate to the task.
5. Determine whether the rule you found belongs to the user, project, local, or managed level.

pwd
git status
ls -la .claude
find .claude -maxdepth 2 -type f

Shared versus local

Team rules should be available in the repository and useful for most sessions. Local settings are for machine-dependent details or personal preferences and are usually not committed.

A local file is not a secret store. Do not put tokens, passwords, or keys there just because the file is excluded from Git.

.claude/CLAUDE.local.md
.claude/settings.local.json

Diagnosing strange behavior

1. Check the path and Git state to rule out the wrong directory.
2. Read the shared CLAUDE.md before drawing conclusions about behavior.
3. Find the source of the specific rule instead of changing all settings at once.
4. If the rule belongs to the managed level, do not try to bypass it with local changes.
5. Change only the layer to which the rule actually belongs.