April 10, 2026 · 12 min read

The Ultimate Claude Code CLAUDE.md Guide: Templates, Hooks & Workflows (2026)

Claude Code just shipped v2.1.98 and developers everywhere are asking the same question: "How do I actually set this up properly?"

After 75+ sessions using Claude Code to build production applications, here's everything I've learned about CLAUDE.md files, hooks, skills, subagents, and token optimization — condensed into actionable templates you can copy-paste right now.

What is a CLAUDE.md File (And Why It Matters)

A CLAUDE.md file sits in your project root and tells Claude Code how to work with your codebase. Without one, Claude Code treats every project like a blank slate — asking about your framework, guessing at conventions, and making mistakes it shouldn't.

With a good CLAUDE.md, Claude Code:

• Follows your coding standards from the first prompt
• Knows your test framework and how to run tests
• Respects forbidden patterns (no any types, no force pushes)
• Uses the right file structure without asking
• Avoids destructive commands that could break your project

CLAUDE.md Template: React / Next.js

This is the template I use for every Next.js project. Drop it in your repo root:

# Project: [Your App Name]

## Stack
React 19 + Next.js 15 (App Router), TypeScript strict, Tailwind CSS
Database: Prisma + PostgreSQL | Auth: NextAuth v5

## Rules
- ALWAYS use Server Components by default. Add "use client" only when needed
- NEVER use `any` type. Use `unknown` + type narrowing
- Components: /src/components/[Feature]/[Component].tsx
- API routes: /src/app/api/[resource]/route.ts
- All async functions must have try/catch with proper error types
- Prefer named exports over default exports (except pages/layouts)

## Testing
- Vitest + React Testing Library
- Test files: [Component].test.tsx colocated with component
- Run: npm test -- --watch

## Forbidden
- No console.log in committed code (use logger util)
- No direct DOM manipulation
- No git push --force or rm -rf
- No inline styles (use Tailwind classes)

CLAUDE.md Template: Python / FastAPI

# Project: [Your API Name]

## Stack
Python 3.12+ | FastAPI | SQLAlchemy 2.0 | Pydantic v2
Database: PostgreSQL | Cache: Redis | Queue: Celery

## Rules
- ALL function parameters and returns must have type hints
- Use Pydantic models for all request/response schemas
- Async by default — use `async def` for all endpoints
- Routes in /app/api/v1/[resource].py
- Business logic in /app/services/[service].py (not in routes)

## Testing
- pytest + pytest-asyncio | Fixtures in conftest.py
- Run: pytest -xvs | Coverage: pytest --cov=app

## Forbidden
- No raw SQL queries (use SQLAlchemy ORM)
- No print() statements (use structlog)
- No mutable default arguments
- Never commit .env or secrets

CLAUDE.md Template: Go

# Project: [Your Service Name]

## Stack
Go 1.22+ | Chi router | sqlc for queries | pgx for Postgres

## Rules
- Errors: always wrap with fmt.Errorf("%w", err) — never discard
- Interfaces: define where consumed, not where implemented
- Packages: /cmd /internal /pkg structure
- Context: pass ctx as first param, always

## Testing
- Table-driven tests required for all exported functions
- Run: go test ./... -race -count=1

## Forbidden
- No init() functions
- No global mutable state
- No panic() except in main
- No unsafe package without comment explaining why

Claude Code Hooks: 10 Recipes That Save Hours

Hooks are the most underused feature in Claude Code. They run scripts automatically before/after actions — configured once in .claude/settings.json, then they work forever. Here are the 10 I use daily:

1. Security Guard Hook

Blocks destructive commands before they execute. This has saved me from accidental rm -rf at least 3 times:

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo '$TOOL_INPUT' | jq -r '.command' | grep -qE '(rm -rf|git reset --hard|git push.*force|DROP TABLE)' && echo 'BLOCKED: Destructive command' && exit 1 || exit 0"
      }
    ]
  }
}

2. Auto-Formatter Hook

Runs Prettier after every file edit — never commit unformatted code again:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write '$FILE_PATH' 2>/dev/null || true"
      }
    ]
  }
}

3. Session Summary Hook

Auto-generates a handoff document when you stop a session, so tomorrow-you knows exactly where to pick up:

{
  "hooks": {
    "Stop": [
      {
        "command": "echo '## Session $(date +%Y-%m-%d_%H:%M)\n### Files Changed\n' > .claude/last-session.md && git diff --name-only >> .claude/last-session.md"
      }
    ]
  }
}

Subagent Patterns: The 10x Multiplier

Subagents are separate Claude Code instances that handle tasks without polluting your main conversation's context window. If you're not using them, you're leaving massive productivity on the table.

Pattern 1: Codebase Explorer

When you need to understand a large codebase without burning main-conversation tokens:

Use a subagent to explore the /src directory.
Find all API endpoints, their HTTP methods, and what
middleware they use. Report back as a markdown table.
Do NOT modify any files.

The subagent reads dozens of files, uses its own context window, and returns a clean summary. Your main conversation stays lean.

Pattern 2: Parallel File Fixer

When you need the same change across many files (rename a variable, update imports, etc.):

Launch a subagent to rename all instances of
"UserService" to "AccountService" across the entire
/src directory. Update imports, types, and tests.
Run the test suite after changes.

Pattern 3: Security Reviewer

Run a security audit in a subagent before every merge:

Use a subagent to review all files changed in the
current branch (git diff main...HEAD --name-only).
Check for: hardcoded secrets, SQL injection, XSS
vulnerabilities, missing input validation, and
insecure dependencies. Output a security report.

Token Optimization: Cut Your Costs 40%

Claude Code Max costs $100-200/month. If you're burning through your allocation in 2 weeks, these strategies will stretch it to a full month:

1. Slim CLAUDE.md (41% reduction): Every line in your CLAUDE.md is read on every prompt. Cut it from 100 lines to 30 and watch your per-prompt cost drop.
2. Line-range prompting: Instead of "read the file," say "read lines 45-80 of auth.ts." Saves thousands of tokens per file read.
3. Strategic /compact: Don't wait until you hit the limit. Run /compact after every major task completion — it summarizes context and frees tokens.
4. Subagent delegation: If a task touches 10+ files, spawn a subagent. Their tokens don't count against your main conversation.
5. MCP overhead reduction: Each MCP server adds 5-15K tokens at session start. Disconnect servers you're not actively using. Some users report 67K token overhead from MCP alone.
6. Model selection: Use Haiku for exploration/reading, Sonnet for coding, Opus for architecture decisions. Don't use Opus to read files.

Custom Skills: Teach Claude Code New Tricks

Skills are markdown files in .claude/skills/ that extend Claude Code's capabilities. Here's a practical example — a Code Reviewer skill:

# .claude/skills/code-reviewer.md

## Code Review Skill

When asked to review code, follow this checklist:

1. **Correctness**: Does the code do what it claims?
2. **Edge cases**: What inputs could break this?
3. **Performance**: Any N+1 queries, unnecessary re-renders, or O(n^2) loops?
4. **Security**: SQL injection, XSS, hardcoded secrets?
5. **Tests**: Are the changes tested? Are edge cases covered?
6. **Naming**: Are variables/functions named clearly?
7. **DRY**: Is there repeated code that should be extracted?

Output format:
- Start with a 1-line summary (LGTM / Needs Changes / Blocking Issues)
- List issues by severity (Critical > Major > Minor > Nit)
- For each issue, suggest the specific fix

Once this file exists in .claude/skills/, you can invoke it with /review and Claude Code follows your exact review checklist instead of giving generic feedback.

The Three-Tier CLAUDE.md System

For teams, Claude Code supports three levels of context files:

1. Global (~/.claude/CLAUDE.md): Your personal preferences that apply to every project — preferred editor commands, commit message style, communication preferences.
2. Project (.claude/CLAUDE.md): Shared team standards — coding conventions, test requirements, forbidden patterns. Committed to the repo.
3. Local (.claude/local.md): Your personal overrides for this project — gitignored, for things like "I'm working on the auth module this sprint."

Quick Reference: Essential Slash Commands

• /compact — Compress conversation context (use after completing major tasks)
• /clear — Start fresh conversation (nuclear option)
• /model — Switch between Haiku/Sonnet/Opus mid-session
• /cost — See current session cost and token usage
• /help — See all available commands and skills

The Bottom Line

Claude Code is the most powerful agentic coding tool available in 2026. But most developers are using maybe 20% of its capabilities. A proper CLAUDE.md file, a few hooks, and an understanding of subagent patterns will transform it from "fancy autocomplete" into a genuine 10x multiplier.

The templates in this guide are free. If you want the complete set — all 12 stacks, all 10 hooks, 8 skill files, 6 subagent patterns, the token optimization playbook, and 5 end-to-end workflows — the Claude Code Mastery Kit has everything ready to drop into your projects in 15 minutes.