Why the .claude Folder Is the Most Crucial Part of Claude Code to Configure

Two .claude directories

Project‑level .claude/

Committed to Git so every team member gets the same rules, commands, and permission policies.

Stores team‑wide configuration such as custom commands, permission policies, and project constraints.

Global ~/.claude/

Contains personal preferences and local state (session history, auto‑memory, personal commands and skills).

Used for personal overrides that should not affect the shared project configuration.

Key files

CLAUDE.md : system prompt

When a Claude Code session starts, the content of CLAUDE.md is injected into the system prompt and consulted for the entire session. Rules written here become constraints for Claude, e.g., "always write tests before implementation" or "never use console.log for error handling".

Typical contents (keep under 200 lines):

Build, test, lint commands (e.g., npm run test, make build)

Key architectural decisions (e.g., using Turborepo monorepo)

Important pitfalls (e.g., TypeScript strict mode enabled)

Import conventions, naming standards, error‑handling style

Core module folder structure

Example minimal CLAUDE.md:

# Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

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

## Conventions
- Use <code>zod</code> for request validation
- Return shape always <code>{ data, error }</code>
- Never expose stack traces to the client
- Use the logger module, not <code>console.log</code>

## Watch out for
- Tests use a real local DB; run <code>npm run db:test:reset</code> first
- Strict TypeScript: no unused imports

CLAUDE.local.md : personal overrides

Git‑ignored file for personal preferences that should not be shared with the team (e.g., preferred testing tool, custom file‑opening behavior).

rules/ : modular instructions

Split a large CLAUDE.md into separate markdown files (e.g., code-style.md, testing.md, api-conventions.md). Each file is loaded together with CLAUDE.md.

Path‑scoped rules can be added with YAML front‑matter:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules
- All handlers return { data, error } shape
- Use zod for request validation
- Never expose internal error details to clients

commands/ : slash commands

Place a markdown file in .claude/commands/ and it becomes a slash command. The file can embed shell snippets using ! syntax; the command runs and its output is injected into the prompt.

Example review.md (creates /project:review):

---
description: Review the current branch diff for issues before merging
---
## Changes to Review

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

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns

Give specific, actionable feedback per file.

Commands can accept arguments via $ARGUMENTS. Example fix-issue.md (creates /project:fix-issue):

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

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a test that would have caught it.

Project‑level commands live in .claude/commands/; global commands live in ~/.claude/commands/ and appear as /user:command-name.

skills/ : auto‑invoked workflows

Skills are triggered automatically when Claude detects a matching task. Each skill resides in its own directory with a SKILL.md entry point.

Directory layout example:

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

Example SKILL.md for a security review:

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:
1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

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

Personal skills can be placed in ~/.claude/skills/ and are available across all projects.

agents/ : sub‑agents for complex tasks

Define a persona in a markdown file (e.g., code-reviewer.md) with fields such as name, description, model, and tools. When Claude needs to perform a code review, it can spin up this agent in a separate context.

Example code-reviewer.md:

---
name: code-reviewer
description: Expert code reviewer. Use proactively when reviewing PRs, checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

Agents should have tightly scoped tool permissions (e.g., only Read, Grep, Glob for a security auditor) and should not have write permissions unless explicitly required.

settings.json : permissions and configuration

Defines what Claude is allowed or denied to do. A typical allow list includes safe Bash patterns and file operations; the deny list blocks dangerous commands and sensitive files.

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

If an operation is neither in allow nor deny, Claude asks for confirmation, providing a safety buffer.

settings.local.json

Git‑ignored personal overrides for permissions, analogous to CLAUDE.local.md.

Global ~/.claude/ structure

CLAUDE.md

: personal global instructions (coding principles, style preferences). settings.json: global permission rules. commands/, skills/, agents/: personal versions of the respective project‑level directories. projects/: session history and auto‑memory (commands discovered, patterns, architectural clues) accessible via /memory.

Getting started – step‑by‑step

Run /init in Claude Code to generate a starter CLAUDE.md, then prune it to the essentials.

Add .claude/settings.json with appropriate allow/deny rules (at minimum allow project scripts, deny .env reads).

Create a couple of useful commands, e.g., a code‑review command and an issue‑fixing command.

When CLAUDE.md becomes crowded, move rules into .claude/rules/ and optionally scope them by path.

Add personal preferences to ~/.claude/CLAUDE.md (e.g., always write types before implementations).

Key takeaway

The .claude/ folder is a protocol that tells Claude who you are, what your project does, and which rules it must obey. The clearer and more structured this configuration, the less manual correction is needed and the more productive the AI‑assisted workflow becomes.