What Exactly Belongs in a .claude/ Folder? A Beginner’s Guide

TL;DR

CLAUDE.md

– store the most stable, high‑frequency project rules: commands, architecture boundaries, directory responsibilities, testing strategy, dangerous zones. .claude/CLAUDE.md and .claude/rules/*.md – project‑level memory loading paths; official docs stress these files. .claude/settings.json – defines what actions are allowed or denied; it is a permission layer, not a place for project knowledge. .claude/hooks/ – deterministic actions such as dangerous‑command interception, post‑write formatting, or final test checks. Hooks execute real code, unlike prompt hints. .claude/commands/ or .claude/skills/ – reusable workflows (code review, issue fixing, release notes, security checks). Commands are manual entry points; skills are auto‑triggered with richer context. .claude/agents/ – isolated sub‑agents for specialized tasks (code review, security audit, performance analysis) that keep intermediate state out of the main context.

What the .claude/ Folder Represents

The folder is not a mysterious “brain” that makes Claude smarter; it is a structured hand‑off desk for the agent. It translates the tacit project rules that senior engineers know into assets that Claude can read, enforce, and act upon.

Layered Organization

Two levels exist:

Project‑level ( <project-root>/.claude/) – shared rules, permissions, hooks, commands, skills, and agents committed to Git.

User‑level ( ~/.claude/) – personal preferences, global skills, and session history that are not committed.

CLAUDE.md – The Highest‑Leverage File

Only include stable, frequently used rules that directly affect agent behavior, such as install/run commands, directory responsibilities, architecture boundaries, error handling, and dangerous‑zone warnings. Keep the file short (under 200 lines, ideally 100) to avoid cache‑misses; long files dilute the stable prefix used by Claude’s KV cache.

# Project: Acme API

## Commands
- npm run dev   # start local server
- npm run test  # run unit tests
- npm run lint  # lint and format checks
- npm run build # production build

## Architecture
- Express REST API on Node 20
- PostgreSQL via Prisma
- Handlers in src/handlers
- Types in src/types

## Conventions
- Validate request bodies with zod
- Return { data, error } from handlers
- Use src/lib/logger.ts for logs
- Never expose stack traces to clients

## Watch out
- Tests use a local database, not mocks
- Run npm run db:test:reset before integration tests
- Do not edit migrations unless explicitly required

Do not turn CLAUDE.md into a full product spec or encyclopedia; it should only contain information the agent needs on every run.

settings.json – Permission Boundaries

Defines what the agent may do (allow) and what it must not do (deny). Start with a narrow allow list (read, search, diff, test) and gradually expand as the project matures. Explicitly deny dangerous actions such as deleting files or reading .env files.

{
  "$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.*)"
    ]
  }
}

When a rule is missing, Claude will ask before executing; this “middle ground” design prevents the need to enumerate every possible command.

Hooks – Deterministic Actions

Hooks go beyond soft prompts; they enforce hard constraints. Three useful hook types are:

PreToolUse – quick safety checks before a tool runs.

PostToolUse – automatic formatting or logging after a file is written.

Stop – run a minimal test suite before the agent declares success; abort with exit 2 if tests fail.

Example Bash firewall hook (blocks dangerous commands):

#!/usr/bin/env bash
set -euo pipefail
payload="$(cat)"
command="$(printf '%s' "$payload" | jq -r '.tool_input.command // empty')"
case "$command" in
  *"rm -rf /"*|*"git push --force main"*|*"DROP TABLE"*)
    echo "Blocked dangerous command: $command" >&2
    exit 2
    ;;
esac
exit 0

Exit codes matter: exit 0 continues, exit 1 reports an error but does not stop the workflow, and exit 2 truly blocks execution.

Commands and Skills – Reusable Workflows

Commands are legacy slash‑commands that require manual invocation (e.g., /project:review). Skills are richer, auto‑triggered definitions that can include templates, scripts, and reference documents.

# .claude/commands/review.md
---
description: Review the current branch before merge.
---
## Changes to review
!`git diff --name-only main...HEAD`
## Detailed diff
!`git diff main...HEAD`
Review the above changes, focus on:
1. correctness bugs
2. missing tests
3. security risks
4. behavior regressions
Give specific, actionable feedback per file.

Skills use a SKILL.md with YAML front‑matter to declare trigger conditions and allowed tools:

---
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 remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

Agents are defined similarly but include a model field to choose a cheaper model for read‑only tasks.

---
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.
- Flag bugs, not just style issues.
- Suggest specific fixes.
- Check edge cases and error handling.
- Note performance concerns only when they matter at scale.

Project vs. User Configuration

Team contracts belong in the repository ( CLAUDE.md, .claude/settings.json, etc.). Personal preferences stay in ~/.claude/ and are never committed. This separation prevents accidental propagation of individual habits (e.g., “use Chinese by default”) to the whole team.

Complete File Tree Example

your-project/
├── CLAUDE.md                # team rules (committed)
├── CLAUDE.local.md         # personal overrides (git‑ignored)
└── .claude/
    ├── settings.json        # permissions + hooks (committed)
    ├── settings.local.json # personal permission overrides (git‑ignored)
    ├── hooks/              # hook scripts
    │   ├── bash-firewall.sh
    │   ├── auto-format.sh
    │   └── enforce-tests.sh
    ├── rules/              # modular rule files
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/             # auto‑triggered workflows
    │   ├── security-review/
    │   │   ├── SKILL.md
    │   │   └── DETAILED_GUIDE.md
    │   └── deploy/
    │       ├── SKILL.md
    │       └── templates/release-notes.md
    ├── commands/           # manual slash commands
    │   ├── review.md
    │   └── fix-issue.md
    └── agents/              # isolated sub‑agents
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                # personal global rules
├── settings.json            # personal global settings + hooks
├── skills/                  # personal reusable skills
├── agents/                  # personal agents
├── commands/                # personal commands
└── projects/                # session history & automatic memory

Start small: write a concise CLAUDE.md, add a minimal settings.json, then introduce a few essential hooks, followed by high‑frequency commands or skills, and finally add agents when the workload justifies isolated contexts.

Key Takeaways

The .claude/ directory is a layered hand‑off desk that turns implicit team knowledge into explicit, version‑controlled assets.

Separate stable project rules ( CLAUDE.md) from permissions ( settings.json) and deterministic actions (hooks).

Use commands for simple entry points, skills for richer, auto‑triggered workflows, and agents for isolated sub‑tasks.

Keep personal preferences in ~/.claude/ to avoid contaminating the team contract.

Start with a short CLAUDE.md and gradually expand; most projects never need the full set of features.