CLAUDE.md and settings.json as Versioned Project Configuration
CoreManage Claude application configuration as versioned artifacts · Difficulty 1/5
Explanation
CLAUDE.md
`CLAUDE.md` is project/repo memory and instructions for Claude Code -- the persistent context that shapes how Claude Code behaves inside a given repository. Because it directly shapes agent behavior, it should be checked into version control just like source code: changes to it are reviewable, diffable, and revertible through the same PR process as any other change.
settings.json
settings.json is Claude Code's settings surface: permissions, hooks, tool allow/deny lists, and environment configuration. This is where deterministic, structural controls (as opposed to prompt-level guardrails) get configured -- which tools are permitted, what hooks fire at which points, and what environment the agent runs in.
Why Both Are Configuration, Not Code
Treating `CLAUDE.md and settings.json` as configuration -- rather than as incidental local files -- means applying the same discipline used for any configuration: version control, code review, and deliberate change management. A change to either can materially change agent behavior, so it deserves the same scrutiny as a code change, not less.
Common exam traps
- Treating `CLAUDE.md` as a personal scratch file rather than checked-in project memory that should be reviewed like any other change.
- Assuming
settings.jsonis a one-time setup step rather than an ongoing configuration surface (permissions, hooks, tool lists) that evolves with the project and needs the same version-control discipline.
See the [Claude Code settings.json reference](/glossary/claude-settings).
Key Takeaways
- CLAUDE.md is project/repo memory for Claude Code and belongs in version control, reviewed like code
- settings.json configures permissions, hooks, tool allow/deny lists, and environment for Claude Code
- Both are configuration surfaces that materially change agent behavior and deserve the same review discipline as code
- Neither is a one-time local setup file -- both evolve with the project and need ongoing version control
Glossary Terms
Shell scripts or commands configured in .claude/settings.json that run at defined lifecycle points: PreToolUse (before tool execution), PostToolUse (after tool execution), Stop (before ending), SubagentStop (when subagent finishes). Used for code quality gates, notifications, logging, and safety checks.
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