How to Master Claude Code: A Practical Guide to the .claude Folder

Most people see the .claude folder in the project root but never open it. This article explains its purpose and how to configure it.

CLAUDE.md: the most important file

Claude Code reads CLAUDE.md first, loading its content as a system prompt that applies for the whole session. Whatever you write there, Claude follows.

Examples: ask it to write tests before implementation, or forbid console.log for error handling.

The project‑level CLAUDE.md is common, but you can also place a global version in ~/.claude/CLAUDE.md or add rule files in sub‑directories; Claude merges them.

What to write and what to avoid

Write:

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

Key architectural decisions (e.g., “We use Turborepo for the monorepo”)

Hidden pitfalls (e.g., “TypeScript strict mode is on, unused variables cause errors”)

Import conventions, naming patterns, error‑handling style

Major module file and folder structure

Avoid:

Linter or formatter configuration files

Full documentation that can be linked

Long explanatory theory paragraphs

Keep CLAUDE.md under 200 lines; longer files consume too much context and reduce Claude’s compliance.

rules/: splitting a large CLAUDE.md

When the file grows beyond 300 lines, place additional markdown files under .claude/rules/. Each file is loaded together with CLAUDE.md, allowing you to separate concerns (api‑conventions.md, testing.md, etc.).

You can limit a rule to specific paths by adding a YAML front‑matter block:

---
paths:
  - src/api/**
  - src/handlers/**
---

This prevents the rule from affecting unrelated files such as React components.

hooks: making behavior deterministic

Claude treats instructions in CLAUDE.md as suggestions; it may not always obey. Hooks defined in settings.json guarantee execution of shell scripts at specific workflow nodes.

Common events

PreToolUse : fires before any tool runs (safety gate)

PostToolUse : fires after a tool succeeds (format output)

Stop : fires when Claude ends (quality gate, e.g., “tests must pass to finish”)

UserPromptSubmit : fires on Enter key (prompt validation)

Notification : desktop notification

SessionStart/SessionEnd : context injection and cleanup

A common pitfall: only exit code 2 stops execution; exit 1 merely logs the event.

skills/: on‑demand workflows

Skills are markdown‑defined workflows that Claude can invoke automatically when the context matches. Each skill lives in its own sub‑directory with a SKILL.md, for example:

---
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.

You can trigger it with a natural language request (“review this PR for security issues”) or manually with /security-review. Unlike commands, a skill can include supporting files.

agents/: specialized sub‑agents

For complex tasks you can define an agent in .claude/agents/. An agent markdown file contains its own system prompt, tool permissions, and model choice:

---
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 with a focus 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

The agent runs in an isolated context, returns a concise report, and does not pollute the main session. The tools field restricts what the agent can do, and the model field lets you pick a cheaper or more powerful model as needed.

settings.json: permissions and project configuration

.claude/settings.json defines what Claude may or may not do. Example:

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

Allow list contains commands that can run without confirmation; typical entries include npm scripts, make, and read‑only git commands. Deny list blocks destructive commands, network calls, and sensitive files.

Anything not explicitly allowed or denied triggers an interactive prompt, providing a safety net.

~/.claude/: the global folder

Key files:

~/.claude/CLAUDE.md : loaded for every Claude Code session, useful for personal coding principles.

~/.claude/projects/ : stores per‑project session history and automatic memory.

~/.claude/commands/ and ~/.claude/skills/ : personal commands and skills available across projects.

These global settings let Claude retain knowledge across sessions and let you clear a project's memory when needed.

Getting started

Step 1: Run /init in Claude Code to generate a starter CLAUDE.md and trim it to essentials.

Step 2: Add a .claude/settings.json with allow/deny rules suitable for your stack (allow run commands, deny .env reads).

Step 3: Create a couple of commands for frequent workflows such as code review or issue fixing.

Step 4: When CLAUDE.md becomes large, split it into .claude/rules/ files and use path‑limited rules.

Step 5: Add a personal ~/.claude/CLAUDE.md for preferences like “write types before implementation” or “prefer functional style”.

These steps cover most project needs; skills and agents are added only when recurring complex workflows merit encapsulation.

Beyond the folder itself, mastering its structure helps you understand the design of many agents, including the clever Openclaw designs, which fundamentally rely on organized prompt files and workflow control; these are key to harness design.

Summary: The .claude folder is a protocol that tells Claude who you are, what your project does, and which rules it must follow. The clearer the definition, the less time you spend correcting Claude and the more time it spends doing useful work. CLAUDE.md is the highest‑leverage file—get it right first.