CLAUDE.md vs settings.json for Team Configuration
CoreConfigure Claude tools and environments for teams · Difficulty 2/5
Explanation
An architect standardizing Claude Code for a team must keep two configuration surfaces cleanly separated: **CLAUDE.md (memory/instructions) and settings.json** (deterministic configuration).
CLAUDE.md Hierarchy
Project memory is hierarchical and auto-loaded into context at multiple levels:
| Level | Location | Scope |
|---|---|---|
| Enterprise/system | Managed centrally | Org-wide policy |
| User | ~/.claude | Personal, per-developer |
| Project | ./CLAUDE.md | Whole team, via the repo |
| Subdirectory | Nested CLAUDE.md | Local to that part of the codebase |
The key architectural decision: the **project-level `CLAUDE.md` is committed to the repo** so the whole team shares the same conventions and context -- it is not something each developer maintains privately.
settings.json as the Control Surface
settings.json is the deterministic control surface for a team's Claude Code deployment. It holds:
- Tool allow/deny lists
- Hooks
- Environment variables
- Model selection
- Connected MCP servers
The distinction to hold firmly: **permissions and guardrails live in settings.json, not in `CLAUDE.md.** CLAUDE.md is instructions and memory that Claude reads; settings.json` is enforced configuration the harness applies regardless of what Claude decides.
Why the Split Matters
Mixing the two surfaces produces inconsistent, unsafe team behavior:
- If permission rules live only in `CLAUDE.md`, they are advisory instructions Claude could ignore or misinterpret, not enforced guardrails
- If team conventions live only in a developer's personal setup, new team members never receive them
Common exam traps
- Putting permissions or tool allow/deny rules in `CLAUDE.md
. Those belong insettings.json;CLAUDE.md` is instructions/memory, not an enforcement mechanism. - Assuming personal (
~/.claude) configuration is sufficient for team standardization -- shared conventions must live in the committed, project-level `CLAUDE.md` to reach every developer.
See the [Claude Code settings.json reference](/glossary/claude-settings).
Key Takeaways
- CLAUDE.md is memory/instructions; settings.json is deterministic configuration (permissions, hooks, MCP)
- Project memory is hierarchical: enterprise/system, user (~/.claude), project (./CLAUDE.md), and subdirectory levels
- Project-level CLAUDE.md is committed to the repo so the whole team shares conventions and context
- Tool allow/deny lists, hooks, environment, model selection, and MCP servers all live in settings.json
- Putting permissions or guardrails in CLAUDE.md instead of settings.json is a common misconfiguration
Glossary Terms
A markdown configuration file read by Claude Code at startup that injects persistent context, project conventions, and tool guidance into every session — without re-prompting. Claude Code supports CLAUDE.md files at the global, project-root, and subdirectory levels (see /glossary/path-specific-rules for the hierarchy). Uses @import for modular organization.
The Claude Code settings file that configures tool permissions, hook scripts, environment variables, and behavioral settings. Project-scoped (.claude/settings.json) checked into version control, or user-scoped (~/.claude/settings.json) for personal preferences. Hooks are defined here.
Related Concepts