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:

  1. Multiple CLAUDE.md locations — it's unclear which takes priority, or that both ~/CLAUDE.md and ~/.claude/CLAUDE.md exist and are both loaded
  2. Memory vs. instructions — the distinction between "memory" (per-project, auto-populated) and "instructions" (CLAUDE.md, user-authored) is not explained anywhere during setup
  3. 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
  4. 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
  5. 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 --setup command that walks through configuration
  • A claude config command that shows where all config files live and their current state
  • A brief explanation in claude --help or a claude help config subcommand
  • 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.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗