Claude Code: The Full Picture

For developers who’ve installed Claude Code and want to understand the whole landscape — what everything is, what to configure, what to leave alone, and what’s actually possible.

The map

your-project/
├── CLAUDE.md                  ← your project constitution (edit this)
├── .claude/
│   ├── settings.json          ← project permissions & hooks (edit this, commit it)
│   ├── settings.local.json    ← your machine-specific overrides (don't commit)
│   └── commands/              ← custom slash commands (create these)
│       └── my-command.md

~/.claude/                     ← global, applies to all projects
├── CLAUDE.md                  ← instructions always loaded, every session
├── settings.json              ← global defaults
└── projects/                  ← memory files (auto-managed, don't touch)

CLAUDE.md — the constitution

What it is: A Markdown file Claude reads at the start of every conversation. The closest thing to persistent context that exists. Anything you put here doesn’t need to be re-explained every session.

What to put in it:

What not to put in it:

You can have multiple: A root CLAUDE.md for the whole project, plus CLAUDE.md files in subdirectories for subsystem-specific context. Claude reads all of them.

Generate a starter: Run /init in Claude Code — it’ll scan the codebase and produce a draft CLAUDE.md for you to edit down.

.claude/settings.json — permissions and hooks

What it is: Project-level configuration. Commit this — it’s part of the project, not your personal preferences.

What you can configure:

Permissions — what Claude is allowed to do without asking:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

Hooks — shell commands that run automatically on events:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint --fix" }]
      }
    ]
  }
}

Common hook patterns:

.claude/settings.local.json — your machine only

Same format as settings.json but never commit this. Good for:

.claude/commands/ — custom slash commands

What it is: Markdown files that become slash commands. Create review-pr.md and you get /project:review-pr in any session.

Format:

---
description: Run a pre-PR checklist on the current branch
---

Review the changes on the current branch against main. Check for:
- TypeScript errors
- Missing tests for new functions
- Console.log statements left in
- Anything that should be in an environment variable but isn't

Report findings as a checklist.

Useful custom commands to build:

Built-in slash commands

Command What it does
/help Show available commands and features
/init Scan codebase and generate a CLAUDE.md draft
/clear Wipe conversation context. Use between tasks.
/compact Compress conversation to free up context space
/review Run a code review on current changes
/memory View and edit Claude’s memory (if enabled)
/cost Show token usage for the current session

When to use /clear: After a task is done and you’re starting something unrelated. Don’t let old context from task A pollute task B.

When to use /compact: When a long session is getting slow or you’re hitting context limits but want to continue in the same thread.

MCP servers — extending what Claude can do

What they are: Model Context Protocol servers that give Claude tools beyond the filesystem and bash. Think of them as plugins.

What’s possible:

Where they’re configured: ~/.claude/settings.json (global) or .claude/settings.json (project). The MCP server runs as a separate process; Claude calls it as a tool.

How to add one:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--access-token", "YOUR_TOKEN"]
    }
  }
}

What Claude Code can actually do

File system:

Shell:

Multi-step tasks:

What it cannot do:

What to edit vs leave alone

Thing Edit? Notes
CLAUDE.md Yes This is yours
.claude/settings.json Yes Commit it
.claude/settings.local.json Yes Don’t commit it
.claude/commands/*.md Yes Build useful ones
~/.claude/settings.json Yes Global defaults
~/.claude/CLAUDE.md Yes Global context across all projects
~/.claude/projects/ No Auto-managed memory, editing manually causes confusion
The Claude Code binary itself No Update via the installer

Permission modes

By default, Claude Code asks before running commands or making changes it considers risky. You can tune this:

Start conservative. Add permissions as you learn which prompts are annoying vs which ones are genuinely protecting you.

Practical first-session checklist

Stay current

Claude Code moves fast. The best place to follow changelogs, API releases, and deep dives is the official developer account:

@ClaudeDevs — direct line from the Anthropic team to developers building with Claude. Changelogs, API releases, community updates. Has an adorable pixel art orange monster mascot. Highly recommended.

Source: Claude Code (self-reported, claude-sonnet-4-6)