Stop Cramming Everything Into CLAUDE.md: The Complete Guide to Claude Code's 5 Customization Layers

If you've been using Claude Code for any length of time, you've probably discovered CLAUDE.md — the markdown file that loads into every conversation as persistent context. You added your coding standards, your PR checklist, your deployment procedure, your commit message format. All of it. One file. Done.

Stop Cramming Everything Into CLAUDE.md: The Complete Guide to Claude Code's 5 Customization Layers

This post is based on the following video:

https://youtube.com/watch?v=xuZ2meWfcKg

TL;DR

  • Claude Code has five distinct customization layers — CLAUDE.md, Skills, Sub Agents, Hooks, and MCP Servers — each solving a different problem at a different context window cost.
  • The most common mistake is cramming everything into CLAUDE.md, wasting tokens on irrelevant rules every single session.
  • A simple decision matrix (Always? / Sometimes? / Isolated? / Automatic? / External?) tells you exactly where each piece of configuration belongs.
  • All five layers compose together — a well-configured project uses all of them simultaneously without conflict.

The Problem Most Developers Are Ignoring

If you've been using Claude Code for any length of time, you've probably discovered CLAUDE.md — the markdown file that loads into every conversation as persistent context. You added your coding standards, your PR checklist, your deployment procedure, your commit message format. All of it. One file. Done.

It works. But it's quietly costing you.

That deployment procedure is sitting in context while you're fixing a typo. Your PR review checklist is consuming tokens while you're debugging a race condition. Claude Code's own system prompt already uses roughly 50 instruction slots before your CLAUDE.md is even read — research suggests frontier LLMs reliably follow approximately 150–200 instructions before quality degrades uniformly. You're working with roughly 100–150 remaining slots, and a bloated CLAUDE.md burns through them fast.

The good news: Claude Code gives you five distinct customization mechanisms. Each loads differently. Each costs differently. And most developers are only using one of them.

The Five Layers

1. CLAUDE.md — Always-On Instructions

CLAUDE.md is your project's company handbook. It loads at the start of every session, every time, no exceptions. This is where your non-negotiables live:

  • Always use TypeScript strict mode
  • Use PNPM, never npm
  • Never modify the database schema directly
  • Branch naming convention: type/TICKET-description

What makes it powerful is its hierarchical cascade — similar to CSS specificity. An enterprise-level file applies to everyone in your org, a personal ~/.claude/CLAUDE.md follows you across all projects, a project-level file is shared via version control, and a local override file is just for you on this specific project. More specific always wins.

As of recent versions, Claude also builds its own memory automatically, writing observed patterns and conventions to a memory directory and loading them back next session.

The rule: If Claude should always know it, put it in CLAUDE.md. But remember — everything here consumes context every session, whether it's relevant or not.

2. Skills — On-Demand Expertise

A skill is a markdown file (SKILL.md) that teaches Claude how to do something specific. Unlike CLAUDE.md, only the skill's description lives in context at all times. The full instructions load only when Claude determines they're relevant.

.claude/ └── skills/ ├── pr-review/ │ └── SKILL.md ├── deploy/ │ └── SKILL.md └── commit-message/ └── SKILL.md

You say "Review this PR" and Claude automatically loads your PR review skill. You say "Deploy to staging" and your deployment checklist activates. You don't type a slash command — Claude reads your request, compares it against all available skill descriptions, and activates the ones that match.

Skills can also be slash commands. Anthropic merged commands and skills — a file at .claude/commands/ and a skill at .claude/skills/ both create the same slash command. Skills can include supporting files too: templates, reference docs, scripts. The SKILL.md stays focused on core instructions while detailed reference material lives in separate files that Claude reads only when needed.

Skills stored in your project's .claude/skills/ directory get shared with your entire team through version control. Everyone who clones the repo gets the same skills automatically.

The rule: If Claude should know it sometimes, make it a skill.

3. Sub Agents — Isolated Context Workers

Sub agents are a Claude Code-only feature for spawning parallel Claude instances with completely isolated context windows. This is the answer to one of the most-cited frustrations among practitioners: context pollution — Claude "becoming dumber after compacting" as a long session fills up.

When you ask Claude to research a codebase, it can delegate to an Explore sub agent. That agent reads dozens of files, searches directories, analyzes architecture. All that verbose output stays in the sub agent's context window. Only the relevant summary returns to your main conversation.

Claude Code ships with three built-in sub agents out of the box:

AgentModelAccessBest For
ExploreHaiku (fast)Read-onlySearching, analyzing
PlanInherits yoursRead-onlyResearch during plan mode
General-purposeInherits yoursAll toolsComplex multi-step tasks

You can build your own. Create a markdown file in .claude/agents/ with frontmatter that specifies name, description, tool restrictions, and model selection:

---
name: code-reviewer
description: Reviews code for quality, security, and adherence to project standards.
tools: Read, Grep, Glob
model: sonnet
memory: project
---
You are a senior code reviewer...

Sub agents can even have persistent memory — a code reviewer that remembers patterns it's seen across sessions, a debugger that builds up knowledge about common issues in your codebase.

The rule: If it should run in isolation with its own context, use a sub agent.

4. Hooks — Deterministic Event Automation

Hooks are fundamentally different from everything else. Skills add knowledge. Sub agents delegate tasks. Hooks fire on events automatically, deterministically. No hoping the LLM makes the right choice.

A hook is a shell command that executes at a specific point in Claude Code's lifecycle:

PreToolUse → fires before Claude runs a tool PostToolUse → fires after a tool completes SessionStart → fires when a session begins Stop → fires when Claude finishes responding

There are 15+ event types in total. Here's the pattern for a security guard hook:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "check-destructive.sh"
      }]
    }]
  }
}

Your check-destructive.sh script checks every bash command before Claude runs it. If it contains rm -rf, exit code 2 — blocked. The command never executes.

A post-tool-use hook matching file write/edit tools can run Prettier on every file Claude touches. Every file, every time. Consistent formatting without even thinking about it.

The critical distinction: Skills are request-driven. They activate when you ask for something. Hooks are event-driven. They fire on every matching event regardless of what you asked for. You don't hope Claude remembers to lint. The hook guarantees it.

The rule: If it should happen automatically on every matching event, use a hook.

5. MCP Servers — External Tool Integrations

MCP (Model Context Protocol) is an open-source standard for connecting AI tools to external services. It's the universal adapter between Claude Code and the rest of your stack.

# Connect a server with a single command
claude mcp add github npx @anthropic/mcp-server-github
claude mcp add sentry npx @anthropic/mcp-server-sentry

Once connected, MCP tools appear alongside Claude's built-in tools. You can use them inside hooks, inside skills, inside sub agents. The whole system composes together.

Real-world example: With a JIRA MCP server configured, a /ticket slash command can:

  1. Fetch the ticket and read acceptance criteria
  2. Search the codebase for related files
  3. Create a feature branch
  4. Implement the feature
  5. Update the ticket status to "In Review"
  6. Create a PR linked back to the ticket

All from one command, without leaving your terminal.

There are 100+ official servers in the MCP registry covering GitHub, Sentry, Postgres, Figma, Slack, Linear, and more.

The rule: If Claude needs external tools or data, connect an MCP server.

The Decision Matrix

flowchart TD
    A[New configuration or rule] --> B{Should Claude always know it?}
    B -->|Yes| C[CLAUDE.md]
    B -->|No| D{Should Claude know it sometimes?}
    D -->|Yes| E[Skill]
    D -->|No| F{Should it run in isolation?}
    F -->|Yes| G[Sub Agent]
    F -->|No| H{Should it happen automatically on events?}
    H -->|Yes| I[Hook]
    H -->|No| J{Does Claude need external tools?}
    J -->|Yes| K[MCP Server]

Context Window Cost at a Glance

LayerContext CostWhen It Loads
CLAUDE.mdHighEvery session, always
SkillsLowDescription only; full content on demand
Sub AgentsZeroRuns in its own separate context
HooksZeroRuns outside Claude's context entirely
MCP ServersModerateTool schemas load dynamically

What a Well-Configured Project Looks Like

Rather than a single bloated CLAUDE.md, a production setup distributes responsibility across all five layers:

CLAUDE.md handles your always-on standards: use PNPM, TypeScript strict mode, never mutate the database directly, branch naming conventions.

Skills handle task-specific expertise: a PR review skill with your team's checklist, a deployment skill with your step-by-step procedure, a commit skill with your message format.

Sub Agents handle delegation: a read-only code reviewer, a researcher that explores documentation without cluttering your main context, a test writer that runs in isolation.

Hooks handle automation: auto-format every file Claude touches, block destructive shell commands, run the test suite after every edit.

MCP connects external services: GitHub for pull requests, Sentry for error monitoring, Postgres for data queries, JIRA for ticket workflows.

Each handles its own specialty. They don't compete — they compose.

Where to Start

Run /init in your project to bootstrap a CLAUDE.md. That's your foundation. Then:

  • The next time you repeat yourself → write a skill
  • The next time you want guardrails → add a hook
  • The next time you need isolation → create a sub agent
  • The next time you need external data → connect an MCP server

The five features aren't alternatives. They're a stack. Used together, they transform Claude Code from a smart chat interface into a fully orchestrated development system.

Citations