Unlock Claude Code’s Hidden Power: Inside the .claude/ Folder

Claude Code stores its configuration in a special .claude/ directory that actually consists of two separate locations: a project‑level folder placed at the root of the repository (shared via Git) and a global folder at ~/.claude/ for personal preferences and local state such as session history.

.claude/ is not a single folder—it’s two

Project level: .claude/ lives in the project root and is committed to the repository, allowing the whole team to share the same rules, commands, and permission policies.

Global level: ~/.claude/ is private to the user; it stores personal overrides, local memory, and other per‑machine data that should not be committed.

CLAUDE.md – the core instruction file

Every Claude Code session reads CLAUDE.md first and injects its contents into the system prompt, making the instructions persist for the entire conversation. A typical CLAUDE.md includes sections for commands, architecture, conventions, and notes, and should stay under 200 lines; longer files cause the model’s compliance to drop.

# Project: Acme API

## Commands
npm run dev          # start dev server
npm run test         # run Jest tests
npm run lint         # ESLint + Prettier
npm run build        # production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- Handlers in src/handlers/
- Shared types in src/types/

## Conventions
- Validate request params with zod
- Uniform response { data, error }
- No stack traces to client
- Use logger module instead of console.log

## Notes
- Run real DB in tests, not mocks. Use `npm run db:test:reset`
- TypeScript strict mode: no unused imports

Do not put linter configuration, full documentation links, or lengthy technical explanations inside CLAUDE.md; keep it concise.

CLAUDE.local.md – personal overlay

For preferences that should not be shared, create CLAUDE.local.md in the project root. Claude reads it alongside CLAUDE.md, and the file is automatically added to .gitignore.

rules/ – modular command files

When a single CLAUDE.md becomes unwieldy, split it into individual markdown files under .claude/rules/. Each file focuses on one concern (e.g., code style, testing, API conventions) and can be scoped to specific paths using a YAML front‑matter block.

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error }
- Validate requests with zod
- Never expose internal error details

Files without a paths field are loaded for every session.

commands/ – custom slash commands

Claude ships with built‑in commands like /help and /compact. Adding a markdown file to .claude/commands/ creates a new slash command. For example: review.md →

/project:review

fix-issue.md

→

/project:fix-issue

deploy.md

→ /project:deploy A practical review.md might look like:

---
description: Check diff before merge
---
## Changed files

!`git diff --name-only main...HEAD`

## Full diff

!`git diff main...HEAD`

Check for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance problems

Provide actionable feedback per file.

The leading ! syntax runs the shell command and injects its output into the prompt, enabling dynamic, context‑aware commands.

Passing arguments

Use $ARGUMENTS in a command file to capture trailing text. Example for fixing a GitHub issue:

---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS

!`gh issue view $ARGUMENTS`

Understand the bug, find the root cause, fix it, and write a reproducing test.

Running /project:fix-issue 234 injects the content of issue #234 directly into Claude’s prompt.

skills/ – auto‑triggered workflows

Skills differ from commands because Claude can invoke them automatically when certain conditions match. Each skill resides in its own subdirectory with a SKILL.md that describes when to run.

---
name: security-review
description: Full security audit when reviewing code, preparing a deployment, or when the conversation mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for:
1. SQL injection and XSS risks
2. Exposed credentials or keys
3. Insecure configurations
4. Authentication/authorization gaps

Report findings with severity and remediation steps.
Reference DETAILED_GUIDE.md for our security standards.

Skills can also reference additional files (e.g., @DETAILED_GUIDE.md) to bundle supporting documentation.

agents/ – dedicated sub‑agents

For complex tasks that merit a specialized “expert”, define an agent in .claude/agents/. Example code-reviewer.md:

---
name: code-reviewer
description: Senior code reviewer that runs automatically on PR review.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior reviewer focused on correctness and maintainability.

When reviewing code:
- Spot real bugs, not just style issues
- Provide concrete fix suggestions
- Check edge cases and error handling
- Consider performance only for large‑scale changes

The agent runs in an isolated context, returns a concise summary, and avoids blowing up the main token budget. The tools field limits what the agent can do, and the model field lets you pick a cheaper model (e.g., Haiku) for simple tasks.

settings.json – permissions and project configuration

The file .claude/settings.json defines what Claude is allowed or denied to execute.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Commands in the allow list run without confirmation; everything else prompts the user. A sensible deny list blocks destructive shell commands, network calls, and sensitive files like .env.

Global ~/.claude/ directories

Files under ~/.claude/ are loaded for every Claude Code session, regardless of the project. Typical entries include a personal CLAUDE.md for universal coding preferences and settings.json for global permissions. The projects/ subfolder stores per‑project session memory, accessible via the /memory command.

Full architecture overview

your-project/
├── CLAUDE.md                  # team commands (committed)
├── CLAUDE.local.md            # personal overlay (git‑ignored)
│
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── commands/
    │   ├── review.md
    │   ├── fix-issue.md
    │   └── deploy.md
    ├── rules/
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/
    │   ├── security-review/ SKILL.md
    │   └── deploy/ SKILL.md
    └── agents/
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # global personal commands
├── settings.json
├── commands/                  # personal slash commands
├── skills/                    # personal skills
├── agents/                    # personal agents
└── projects/                  # session history + auto‑memory

Getting started from scratch

Run /init inside Claude Code; it generates an initial CLAUDE.md based on the project, then trim it to the essentials.

Add .claude/settings.json with at least one allowed run command and a deny rule for .env files.

Create 1–2 custom commands (e.g., code review, issue fix) in .claude/commands/.

When CLAUDE.md grows large, split reusable sections into .claude/rules/ files and use path‑scoped frontmatter.

Put personal preferences that should apply to every project into ~/.claude/CLAUDE.md.

Most projects stop at step 4; skills and agents are added only when recurring complex workflows justify the extra structure.