Last updated: 22 October 2026 · Reading time: 9 minutes · Level: Beginner to intermediate

Contents

1. What the .claude folder is
2. The full folder map
3. settings.json and settings.local.json
4. Which setting wins
5. CLAUDE.md and rules
6. Skills, subagents and workflows
7. .mcp.json and connected tools
8. A 15-minute starter setup
9. Common mistakes
10. FAQ

What the .claude folder is

Claude Code has no hidden settings panel. Almost everything that shapes how it behaves in a project, from which commands it can run without asking to the house rules it follows, lives in plain text files you can read, edit and version-control.

Those files sit in 2 folders with the same name:

• your-project/.claude/: rules for 1 project. Commit it and every teammate who clones the repo gets the same setup.
• ~/.claude/: your personal defaults. They apply in every project on your machine and never reach anyone else.

Think of the project folder as the team handbook and the home folder as your own notebook. When they disagree, the more specific one usually wins, which we cover in Which setting wins.

The full folder map

You do not need every file below. Installing Claude Code creates none of them. They appear when you create them or when Claude Code writes one for you, for example after you approve a command with “don’t ask again”.

Project level

Path	What it holds	Commit it?
CLAUDE.md (project root)	Project instructions loaded at the start of every session	Yes
.mcp.json (project root)	MCP servers the whole team should have	Yes
.claude/settings.json	Team permissions, hooks, plugins, environment variables	Yes
.claude/settings.local.json	Your personal overrides for this project	No
.claude/rules/	Topic instruction files, optionally limited to certain file paths	Yes
.claude/skills/	Reusable workflows, each a folder with a SKILL.md	Yes
.claude/agents/	Subagents with their own prompt, tools and context window	Yes
.claude/commands/	Older single-file slash commands (skills now cover this)	Yes
.claude/workflows/	Scripts that orchestrate many subagents	Yes

Home level (~/.claude)

Path	What it holds
~/.claude/CLAUDE.md	Personal preferences for every project
~/.claude/settings.json	Your default settings everywhere
~/.claude/skills/, agents/, rules/, commands/	Personal versions available in all projects
~/.claude/output-styles/	Instruction sets that change how Claude responds
~/.claude/keybindings.json, themes/	Shortcuts and terminal colours
~/.claude/projects/	Auto memory Claude writes for itself, per project

There is also ~/.claude.json (a file, not the folder). Claude Code uses it for account details, MCP server configs and per-project state. You rarely need to touch it.

settings.json and settings.local.json

These 2 files share the same format. The difference is who they are for.

• settings.json is the shared team file. Put the permissions, hooks and plugins everyone should have.
• settings.local.json is yours alone. When you choose “Yes, and don’t ask again” on a permission prompt, Claude Code saves that approval here and adds the file to your global git excludes so it never lands in a commit. If you create it by hand, add it to .gitignore yourself.

A practical team file that lets Claude run tests and lint freely while blocking access to secrets:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

3 things worth knowing:

1. It is strict JSON. A trailing comma or a // comment breaks the file. Claude Code will flag it as a Settings Error at the next start.
2. The $schema line is worth keeping. Editors like VS Code and Cursor use it for autocomplete and validation.
3. Most edits apply live. Claude Code watches these files and reloads permissions and hooks without a restart. A few keys, such as the default model, only load at session start.

To confirm what actually loaded, run /status inside Claude Code and check the “Setting sources” line. For rejected entries, run claude doctor.

Which setting wins

When the same key is set in more than one place, Claude Code takes the value from the highest level:

1. Managed: deployed by your organisation. Nothing you set overrides it.
2. Command line: --settings for a single session.
3. Project local: .claude/settings.local.json
4. Shared project: .claude/settings.json
5. User: ~/.claude/settings.json

The exception is lists. Keys like permissions.allow merge across files instead of replacing each other, so your personal allow rules add to the team’s rather than wiping them.

Example: your team file sets the model to Sonnet, but you want Opus in this repo. Put the model key in settings.local.json. Only your sessions change.

CLAUDE.md and rules

CLAUDE.md is the briefing Claude reads before doing anything. It is the single biggest lever on output quality, and the most common place people overdo it.

What belongs in it:

• How to build, test and run the project, with exact commands
• Conventions a new teammate would get wrong in week 1
• Folders or files Claude should never touch
• A 3 to 5 line map of how the codebase is organised

What does not: long style essays, anything a linter already enforces, and content that only matters for 1 part of the codebase. That last category is what .claude/rules/ is for. Each rule file covers 1 topic and can be scoped to certain paths, so API conventions load only when Claude is working in backend code and test conventions load only around test files. Your main briefing stays short.

A lean starter CLAUDE.md:

# Project: client-reporting-app

## Commands
- Install: npm install
- Dev server: npm run dev
- Tests: npm run test
- Lint before every commit: npm run lint

## Structure
- /src/api: server routes
- /src/ui: React components
- /scripts: one-off data jobs, do not edit without asking

## Rules
- TypeScript strict mode. No `any`.
- Never commit to main. Open a branch per task.
- Ask before adding a new dependency.

Skills, subagents and workflows

These 3 folders turn Claude Code from a single assistant into something closer to a small team.

skills/

A skill is a folder with a SKILL.md file describing when to use it and how to do the job, plus any supporting files such as checklists or templates. You call it by name with a slash command, or Claude picks it up when the task matches. Skills have replaced the older commands/ folder for new work because they can bundle files.

Good first skill: any task you explain to Claude more than twice a month, such as a release checklist or a code review against your standards.

agents/

Each markdown file defines a subagent with its own system prompt, tool access and optionally its own model. Subagents work in a fresh context window, so a long investigation does not clutter your main conversation. Typical uses: a code reviewer that only reads, or a test writer that only touches test files.

workflows/

Workflow files orchestrate many subagents and each one becomes a /name command. Reach for these only once single skills and subagents feel limiting.

.mcp.json and connected tools

MCP servers give Claude access to tools outside your files: a database, a browser, an issue tracker. .mcp.json sits in the project root, not inside .claude/, and lists the servers the team should share. Personal servers you do not want to impose on teammates go in your user configuration instead.

Never put API keys directly in .mcp.json if it is committed. Reference environment variables and keep the values out of the repo.

A 15-minute starter setup

1. Create CLAUDE.md in the project root with commands, structure and 3 to 5 hard rules. Keep it under 60 lines.
2. Create .claude/settings.json with deny rules for .env files and any secrets folder, plus allow rules for your test and lint commands.
3. Add 1 skill in .claude/skills/<name>/SKILL.md for your most repeated task.
4. Check .gitignore covers .claude/settings.local.json.
5. Start Claude Code and run /status to confirm both settings files loaded.
6. Commit everything except the local file.

Add rules, subagents and MCP servers only when you hit a real limit. A small, accurate setup beats a large one Claude half-follows.

Common mistakes

Mistake	What happens	Fix
Committing settings.local.json	Your personal approvals become everyone’s	Add it to .gitignore and remove it from the repo
A 400-line CLAUDE.md	Important rules get diluted	Move topic detail into .claude/rules/
Trailing comma in JSON	File is skipped with a Settings Error	Keep the $schema line and let your editor validate
Expecting a local allow rule to beat a team ask rule	You still get prompted	Change the team file, or ask whoever owns it
API keys in committed .mcp.json	Secrets leak into git history	Use environment variables

FAQ

Does Claude Code create the .claude folder automatically?

No. Installing it creates no settings files. They appear when you create them or when Claude Code saves a choice, such as a permanent permission approval.

Should I commit the .claude folder to git?

Yes, except settings.local.json. Committing the rest gives every teammate the same permissions, skills and rules.

What is the difference between CLAUDE.md and settings.json?

CLAUDE.md holds instructions in plain language. settings.json holds enforced configuration like permissions and hooks.

Why is my setting being ignored?

Usually a higher level sets the same key, or the JSON is invalid. Run /status to see loaded sources and claude doctor to see rejected entries.

Do these settings work in Claude Code on the web?

Partly. Cloud sessions read the committed project file in single-repo sessions, but not your user or local files.

---

Sources: Claude Code settings documentation, Claude directory reference. Checked 22 October 2026.