Claude Code .claude directory: what goes where

Claude Code looks for configuration in a .claude/ directory at your project root. Here's what goes in it and what each file does.

The directory structure

your-project/
├── .claude/
│   ├── settings.json     # permissions, mode, MCP servers
│   ├── settings.local.json  # personal overrides (gitignore this)
│   └── skills/           # custom skills (optional)
├── CLAUDE.md             # rules and context for Claude
├── .claudeignore         # files to exclude from context
└── ...

settings.json

The main config file. Common settings:

{
  "defaultMode": "acceptEdits",
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(node:*)"
    ]
  },
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/path/to/pg-mcp-server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

defaultMode controls whether Claude asks for confirmation before running commands:

• "default" — asks for each command
• "acceptEdits" — runs without asking
• "bypassPermissions" — skips all permission checks (use carefully)

permissions.allow is a list of command patterns that Claude can run. Bash(git:*) allows any git command. Bash(npm install) allows exactly that command.

settings.local.json

Same structure as settings.json, but meant for personal preferences that shouldn't be checked into source control. Add it to .gitignore.

Use it for things like your personal MCP server paths, or setting bypassPermissions in your own dev environment when you trust everything but don't want that setting checked in.

CLAUDE.md

Not inside .claude/ — it lives at the project root. This file loads into Claude's context on every message. Keep it short.

Two things it's actually good for:

1. Hard rules Claude needs to follow ("Never use axios. Use native fetch.")
2. Project context that saves Claude from having to figure out the structure ("This is a Next.js 15 app. Pages are in app/, components are in components/, API routes are in app/api/.")

Keep it under 50 lines. Every line costs tokens every message.

.claudeignore

Also at project root. Works like .gitignore. Files matching these patterns are excluded from Claude's context window.

Common exclusions:

dist/
build/
.next/
node_modules/
*.log
package-lock.json
**/__fixtures__/
**/*.generated.ts

The global config

Everything above is project-level. For global settings that apply to all projects, use ~/.claude/settings.json (your home directory).

Global CLAUDE.md also works: ~/.claude/CLAUDE.md. This loads on every Claude Code session regardless of which project you're in. Use it for preferences that apply everywhere.

---

More setup notes at builtbyzac.com.