Mastering Claude Code: A Complete Guide to the .claude Folder and Advanced Configurations

Understanding the Two .claude Directories

Claude Code uses two separate folders: a project‑level .claude directory that lives in the repository and is shared with the whole team, and a global ~/.claude directory in the user’s home folder that stores personal preferences and state such as session history and auto‑memory.

CLAUDE.md – The Core Instruction File

When a Claude Code session starts, it reads CLAUDE.md first and loads its contents into the system prompt, making the directives persist throughout the conversation. By writing commands such as npm run test or policies like “always write tests before code”, you can shape Claude’s behavior precisely.

CLAUDE.local.md – Personal Overrides

For preferences that should not be shared, create a CLAUDE.local.md file in the project root. It is automatically merged with the main CLAUDE.md and is added to .gitignore, keeping personal tweaks private.

rules/ – Modular Command Rules

When CLAUDE.md grows large, split it into multiple markdown files under .claude/rules/. Each rule file can include a YAML front‑matter that limits its activation to specific paths (e.g., only for files in src/api/), keeping the configuration focused and maintainable.

Hooks – Deterministic Control of Claude’s Behavior

Hooks are event‑driven scripts that run at defined points (e.g., PreToolUse, PostToolUse, Stop, UserPromptSubmit, SessionStart/SessionEnd). They receive JSON via stdin and decide the next step based on exit codes: 0 for success, 1 for error (no block), and 2 to abort the operation. A typical safety hook blocks dangerous commands like rm -rf / or git push --force by exiting with code 2.

skills/ – Reusable Workflows

Skills are self‑contained workflows stored in subfolders, each with a SKILL.md that defines when the skill should be triggered via YAML front‑matter. When a user asks Claude to “review this PR for security issues”, the matching skill is invoked automatically, allowing complex actions without manual prompting.

agents/ – Sub‑agent Personas

For tasks that require a dedicated “expert”, define an agent in .claude/agents/. Each agent is a markdown file specifying its system prompt, allowed tools, and model (e.g., a lightweight Haiku model for read‑only analysis, or a powerful Sonnet/Opus model for heavy lifting). An example code-reviewer.md agent runs in its own context, summarizes findings, and returns a concise report, keeping the main conversation clean.

settings.json – Permissions and Project Configuration

The .claude/settings.json file defines what Claude is allowed to do without confirmation ( allow) and what is strictly prohibited ( deny). Typical allow entries include safe Bash patterns like npm run * or git *, while deny entries block destructive commands ( rm -rf), network utilities ( curl), and sensitive files ( .env, secrets/).

Practical On‑boarding Steps

Run /init inside Claude Code to generate a baseline CLAUDE.md and then trim it to the essentials.

Create .claude/settings.json with an allow rule for your build/test commands and a deny rule for .env files.

Add a few custom commands for frequent workflows such as code review or bug fixing.

When the main file becomes crowded, move path‑specific directives into .claude/rules/ and use YAML front‑matter to limit their scope.

Optionally add a global ~/.claude/CLAUDE.md for personal coding principles (e.g., “always write type definitions first”).

Key Takeaways

The .claude folder acts as a protocol that tells Claude who you are, what your project does, and which rules it must obey. A well‑crafted CLAUDE.md provides the highest leverage; everything else—rules, hooks, skills, agents, and settings—are refinements that amplify productivity while keeping the AI assistant safe and predictable.