Improve onboarding: explain configuration file system to new users
Resolved 💬 4 comments Opened Feb 28, 2026 by dratman Closed Mar 29, 2026
Summary
The Claude Code configuration system is powerful but not well-explained to new users. There's no first-run walkthrough or clear documentation of how the various configuration files relate to each other.
The problem
A new user has to discover the following on their own:
~/.claude/CLAUDE.md— global instructions loaded into every session~/CLAUDE.md— also global instructions (overlapping purpose with the above)<project>/CLAUDE.md— per-project instructions~/.claude/settings.json— permissions and status line configuration~/.claude/projects/<encoded-path>/memory/— per-project persistent memory, only populated if Claude has written to it
Key things that aren't obvious:
- Multiple CLAUDE.md locations — it's unclear which takes priority, or that both
~/CLAUDE.mdand~/.claude/CLAUDE.mdexist and are both loaded - Memory vs. instructions — the distinction between "memory" (per-project, auto-populated) and "instructions" (CLAUDE.md, user-authored) is not explained anywhere during setup
- Memory is per-directory, not global — this is surprising. Users reasonably expect "memory" to follow them across projects, like a person's memory would. The mental model needs to be made explicit: memory is more like "project-specific notes" than human memory
- Encoded path names — the
~/.claude/projects/directory uses dash-separated encoded paths (e.g.,-Users-RalphDratman-1-0-HomeFolder-...) which are not intuitive to navigate - Memory files are plain files — users may not realize they can read, edit, or pre-populate memory files from a regular terminal
Suggestion
Consider one or more of:
- A first-run message or
claude --setupcommand that walks through configuration - A
claude configcommand that shows where all config files live and their current state - A brief explanation in
claude --helpor aclaude help configsubcommand - Better documentation in the README covering the full configuration file hierarchy and how the files interact
Context
This issue comes from a real new-user experience setting up Claude Code for the first time.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗