Why 90% of Users Only Use CLAUDE.md: Exploring Claude Code’s 7 Customization Methods

Common problems

Scenario 1 – CLAUDE.md bloat : a single CLAUDE.md exceeds 200 lines, mixing architecture, coding standards and deployment steps, which shrinks the effective context window and reduces compliance.

Scenario 2 – Repeating prompts : the same instruction block (e.g., code‑review checklist) is pasted for every request, creating unnecessary repetition.

Scenario 3 – Ignored directory rules : rules such as “do not modify legacy/ ” are only advisory, so Claude may still edit protected files.

Scenario 4 – Missing external integrations : tasks that require Jira, Sentry, databases, etc., must be performed manually because Claude Code has no native connectors.

Scenario 5 – Context exhaustion : large refactorings that involve many files exceed the model’s context window, causing earlier decisions to be forgotten.

Decision framework

Does the rule need to apply to every session or only to a specific scenario ?

If it applies always, is it an advisory instruction (use CLAUDE.md ) or a hard prohibition (use Hooks or Settings )?

If it is scenario‑specific, is it a reusable workflow (use Skills ) or an external‑tool integration (use MCP Servers )?

Does the rule target a particular sub‑directory? If yes, use Rules .

Additional checks:

Need isolated context or parallel execution → Sub‑agents

Need model selection, permissions or environment variables → Settings

Legacy custom commands → Commands (now merged into Skills)

Customization methods

1. CLAUDE.md – Persistent memory

Principle : Loaded automatically at session start and kept in the context for the whole session. It is not a one‑off command but long‑term guidance.

Load order (broad → narrow) :

Organization level – e.g., /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) or /etc/claude-code/CLAUDE.md (Linux).

User level – ~/.claude/CLAUDE.md.

Project level – ./CLAUDE.md or ./.claude/CLAUDE.md.

Local personal level – ./CLAUDE.local.md (git‑ignored).

Files at the same level are concatenated; sub‑directory files are loaded on demand.

Import syntax : @path/to/file (up to four levels) lets you split large rule sets into separate files.

# CLAUDE.md

## 项目架构
本项目是 Spring Boot 3.2 单体，Java 17。
模块结构：api/（接口层）、service/（业务层）、dao/（数据层）

## 编码规范
- 使用 2 空格缩进
- 类名 PascalCase，方法名 camelCase，常量 UPPER_SNAKE_CASE
- Controller 只做参数校验和路由

## 构建与测试
- 构建：`./gradlew build`
- 测试：`./gradlew test`
- Lint：`./gradlew spotlessCheck`

## 引入子规则
@docs/database-conventions.md
@api/rest-standards.md

Anti‑patterns :

File > 200 lines – the context window is consumed, compliance drops.

Vague directives (e.g., “format code”) – Claude cannot infer concrete actions.

Embedding step‑by‑step procedures – should be moved to Skills .

Mitigation : keep CLAUDE.md under 100 lines, use @ imports for detailed policies, and move procedural logic to Skills or Rules.

2. Skills – Reusable workflows

Principle : Defined as SKILL.md files that are loaded only when invoked. They act as “scripts” for repeatable tasks such as code review, deployment checks, or documentation generation.

File layout :

.claude/skills/
└── code-review/
    └── SKILL.md

Front‑matter example (YAML + Markdown body):

---
name: code-review
description: "按团队规范执行 Code Review，检查安全、性能、可读性"
when_to_use: "用户要求 review 代码或提交 PR 前"
argument-hint: "[file-or-pr]"
model: sonnet
effort: high
paths: ["src/**/*.ts"]
allowed-tools: [Read, Grep, Glob, Bash]
---

## Code Review Checklist
1. 安全检查：SQL 注入、XSS、硬编码密钥
2. 性能检查：N+1 查询、大对象循环创建
3. 可读性：方法不超过 30 行、命名自解释

$ARGUMENTS 指定要 review 的文件或 PR。

Useful front‑matter fields : context: fork – run the Skill in an isolated sub‑agent. disable-model-invocation: true – require explicit user call. user-invocable: false – allow only automatic Claude invocation. model: haiku – use a cheaper model for simple tasks.

Dynamic context injection : the syntax !`git diff HEAD` executes a shell command and injects its output before the Skill runs.

Anti‑patterns :

Disabling auto‑invocation for all Skills makes the library invisible.

Skill bodies > 5000 tokens stay in the context after each call, exhausting the window.

Using context: fork for pure guideline Skills adds unnecessary overhead.

Mitigation : keep most Skills auto‑invocable, only set disable-model-invocation for side‑effect‑heavy Skills; split large reference material into auxiliary files and import with @ syntax.

3. Hooks – Lifecycle executors (hard enforcement)

Principle : Hooks run automatically on specific events and can abort operations with exit 2. They are defined in settings.json under the hooks field.

Supported events (most common) : PreToolUse – before a tool runs (e.g., block dangerous commands). PostToolUse – after a tool runs (e.g., auto‑format, lint). SessionStart – when a session is initialized (load env vars, verify dependencies). Stop – after Claude replies (send notifications, log). UserPromptSubmit – after user input (pre‑process, keyword replacement).

Hook types : command, http, mcp_tool, prompt, agent.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write",
        "args": ["${CLAUDE_FILE_PATH}"],
        "timeout": 30
      }]
    }]
  }
}

Exit‑code semantics : 0 – success, continue. 1 – non‑blocking error (logged only). 2 – blocking error; the operation is aborted.

Anti‑patterns :

Using exit 1 to block – the operation still proceeds.

Missing or overly broad matcher – the Hook fires for every tool, causing performance loss.

Embedding large scripts (e.g., 200‑line Python) – should be a Skill or Sub‑agent instead.

Mitigation : return exit 2 (or JSON {"decision":"block"}) for hard blocks, use precise matchers, and keep Hook logic short.

4. Rules – Path‑level conditional rules

Principle : Allows different directories to have distinct rule sets. Useful in monorepos where front‑end and back‑end conventions diverge.

Configuration (placed under .claude/rules/):

---
paths: ["src/api/**", "tests/api/**"]
---
## API 层规范
- Controller 必须有 @Validated 注解
- 返回值统一使用 ResponseEntity 包装
- 异常统一由 @RestControllerAdvice 处理

---
paths: ["src/dao/**", "resources/mapper/**"]
---
## 数据层规范
- 禁止在 DAO 层拼接 SQL，必须使用 MyBatis XML
- 分页使用 PageHelper，避免手写 LIMIT

Anti‑patterns :

Duplicating or contradicting rules between CLAUDE.md and Rules – leads to unpredictable behavior.

Using overly broad paths such as ** – defeats the purpose of path‑specific rules.

Mitigation : keep global advice in CLAUDE.md, and use Rules only for precise, directory‑scoped constraints.

5. Sub‑agents – Isolated mini‑agents

Principle : Creates a dedicated agent with its own context window and tool whitelist, preventing main‑session pollution.

Configuration example ( .claude/agents/security-auditor.md):

---
name: code-reviewer
description: "审查代码质量、安全性和最佳实践"
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: sonnet
maxTurns: 50
isolation: worktree
---
你是一个代码审查专家。分析代码并提供具体、可执行的反馈。重点关注：安全性、性能、可维护性。

Invocation styles :

Natural language – Claude decides when to delegate.

Explicit mention – @code-reviewer 看看 auth 模块的改动.

Session‑level – --agent code-reviewer for the whole session.

Built‑in agents (no custom config needed): Explore (fast Haiku, read‑only), Plan (current model, read‑only), general‑purpose (full tool set).

Anti‑patterns :

Vague description – Claude cannot know when to use the agent.

Re‑creating built‑in agents – wasteful.

Nesting deeper than two levels – adds context overhead without benefit.

Mitigation : write precise descriptions, only create agents for tasks not covered by built‑ins, and limit nesting depth.

6. MCP Servers – External tool integration

Principle : The Model Context Protocol (MCP) lets Claude talk to remote services, local processes, or WebSocket endpoints, overcoming the native limitation of file‑only access.

CLI registration (recommended) :

# Remote HTTP service
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Local stdio process
claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server

JSON configuration ( .mcp.json ) (committed for team sharing):

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {"Authorization": "Bearer ${GITHUB_TOKEN}"}
    },
    "database": {
      "command": "/path/to/db-server",
      "args": ["--config", "config.json"],
      "env": {"DB_URL": "${DB_URL}"}
    }
  }
}

Transport options : http (recommended) – remote services, supports OAuth and auto‑reconnect. stdio – local subprocess communication. ws – WebSocket for push‑style interactions.

Anti‑patterns :

Hard‑coding API keys in .mcp.json – exposes secrets to every clone.

Trusting unverified remote MCP servers – risk of prompt injection; use whitelist fields allowedMcpServers / deniedMcpServers.

Using deprecated SSE transport – switch to http.

Mitigation : store secrets in environment variables, enable whitelist controls, and prefer the http transport.

7. Settings – Global configuration panel

Principle : Central JSON file that controls permissions, model selection, language, environment variables, and UI preferences.

Configuration hierarchy (high → low priority) :

Organization‑managed (cannot be overridden).

CLI arguments (temporary).

Local project ( .claude/settings.local.json, git‑ignored).

Project ( .claude/settings.json, committed).

User ( ~/.claude/settings.json).

All layers merge for permissions (allow/deny lists) instead of overriding.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  },
  "model": "claude-sonnet-4-6",
  "language": "chinese",
  "autoCompactEnabled": true
}

Anti‑patterns :

Editing internal ~/.claude.json directly – may break internal state; use ~/.claude/settings.json instead.

Omitting $schema – loses editor validation.

Placing behavioral directives (e.g., “use 2‑space indent”) in Settings – they belong in CLAUDE.md.

Mitigation : always edit the proper Settings file, keep the schema field for validation, and keep behavior instructions out of Settings.

Typical project layout

my-project/
├── CLAUDE.md                # Global < 100 lines rules
├── .claude/
│   ├── settings.json       # Permissions + Hooks
│   ├── rules/
│   │   ├── api-rules.md    # API‑specific rules
│   │   └── dao-rules.md    # Data‑layer rules
│   ├── skills/
│   │   ├── code-review/
│   │   │   └── SKILL.md    # Code review workflow
│   │   └── deploy-check/
│   │       └── SKILL.md    # Pre‑deploy checklist
│   ├── agents/
│   │   └── security-auditor.md
│   └── mcp.json            # MCP server config
└── .claude/settings.local.json  # Personal overrides (git‑ignored)

Key take‑aways

Claude Code provides seven customization mechanisms, each with a distinct purpose:

CLAUDE.md – advisory, long‑term memory.

Skills – on‑demand, reusable workflows.

Hooks – hard enforcement via exit 2.

Rules – path‑specific advisory constraints.

Sub‑agents – isolated execution and parallelism.

MCP Servers – external data and tool integration.

Settings – global control of model, permissions, env vars.

Putting every rule into a monolithic CLAUDE.md is analogous to stuffing all clothes into a single drawer – everything is present but hard to locate and the drawer quickly overflows. By matching the nature of the requirement to the appropriate mechanism (advice vs. hard rule, global vs. directory‑scoped, reusable workflow vs. external service), teams achieve higher compliance, better performance, and maintainable configurations.