Claude Code Config Guide: 5 Options (CLAUDE.md, MCP, Hooks, Skills, Permissions)

1. Identity configuration (CLAUDE.md)

Claude Code reads a CLAUDE.md file at startup. The file acts as a project specification that tells Claude the build and test commands, code‑style conventions, architectural decisions, and common pitfalls.

Four configuration scopes are supported, ordered from highest to lowest priority:

Managed – system configuration directory, organization‑wide directives, shared by all users.

Project – ./CLAUDE.md, team‑shared project settings, versioned in git.

User – ~/.claude/CLAUDE.md, personal preferences, private to the user.

Local – ./CLAUDE.local.md, personal overrides for a specific project, not committed.

Typical content (recommended to stay under 200 lines) includes build/test commands, code‑style rules, architecture notes, workflow conventions, and known gotchas. Information that Claude can infer automatically (e.g., language type) should be omitted.

2. MCP tool extension

MCP (Model Context Protocol) enables Claude Code to connect to external services such as GitHub, databases, and Slack. The default runtime can only read local files and run commands, so MCP expands the reachable boundary.

Supported transport methods:

HTTP – recommended for remote services; supports authentication and encryption.

Stdio – launches a local process via command line.

SSE – deprecated; migrate to HTTP.

Example commands to add a server:

# HTTP server (recommended)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Authenticated HTTP
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Stdio local server
claude mcp add --transport stdio --env DB_URL=xxx db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://localhost/mydb"

Scope flags (default local) control where the definition is stored:

# Local (default, only self)
claude mcp add --scope local server-name

# Project (shared via git)
claude mcp add --scope project server-name

# User (global)
claude mcp add --scope user server-name

Manual configuration via .mcp.json:

{
  "mcpServers": {
    "github": {"type": "http", "url": "https://api.githubcopilot.com/mcp/"},
    "database": {"type": "stdio", "command": "npx", "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"]},
    "slack": {"type": "http", "url": "https://mcp.slack.com/anthropic", "headers": {"Authorization": "Bearer ${SLACK_TOKEN}"}}
  }
}

Environment variables can be referenced with ${VAR_NAME} or ${VAR_NAME:-default}.

3. Hooks mechanism

Hooks allow custom logic to run before or after tool execution, enabling fully automated workflows.

Hook lifecycle:

SessionStart → UserPromptSubmit → PreToolUse → [PermissionRequest] →
Tool Execution → PostToolUse/PostToolUseFailure → Stop → SessionEnd

Common hook events: PreToolUse – before tool runs; can block execution (e.g., validate command safety). PostToolUse – after successful tool; cannot block (e.g., run lint/format). PostToolUseFailure – after tool failure; cannot block (e.g., send notification). UserPromptSubmit – when user submits a prompt; can block (e.g., filter sensitive info).

Example hook configuration (JSON):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": ".claude/hooks/validate-bash.sh"}]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type": "command", "command": "npm run lint", "timeout": 30}]
    }]
  }
}

Sample Bash hook ( .claude/hooks/quality-check.sh) that runs ESLint on changed TypeScript files and blocks the operation on errors:

#!/bin/bash
# Read tool input
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
if [[ "$FILE_PATH" =~ \.(ts|tsx)$ ]]; then
  if ! npx eslint "$FILE_PATH" --fix; then
    jq -n '{hookSpecificOutput:{hookEventName:"PostToolUse",decision:"block",reason:"ESLint found issues that could not be auto‑fixed"}}'
    exit 0
  fi
fi
exit 0

4. Skills and Subagents

Skills are reusable workflow templates; Subagents are specialized agents that actually perform the work.

Typical skill file (YAML) stored under .claude/skills/:

---
name: code-reviewer
description: Review code for best practices and potential issues
allowed-tools: Read, Grep, Glob
disable-model-invocation: false
user-invocable: true
---
1. Check for common security vulnerabilities
2. Verify error handling is comprehensive
3. Ensure code follows project conventions
4. Identify potential performance issues

Provide specific line references and suggestions.

Dynamic context injection uses the !`command` syntax. Example PR‑summary skill:

---
name: pr-summary
description: Summarise pull‑request changes
---
## PR Context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Files: !`gh pr diff --name-only`

Summarise this PR...

Difference: Skills define *what* to do; Subagents define *who* does it (e.g., a security‑review expert).

5. Permissions and security

Fine‑grained permission rules let Claude execute safe commands automatically while blocking dangerous ones.

Permission JSON example:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "additionalDirectories": ["../shared-config/"]
  }
}

Sandbox configuration (recommended for production):

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "filesystem": {
      "allowWrite": ["//tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowUnixSockets": ["/var/run/docker.sock"]
    }
  }
}

After configuring permissions, safe commands run without confirmation, dangerous commands are blocked, and sensitive files are protected.

6. Core recap and action checklist

Key points

CLAUDE.md is the central project spec (keep < 200 lines, include only non‑inferable information).

Configuration hierarchy: Managed → Project → User → Local (higher priority overrides lower).

Hooks automate pre‑ and post‑tool actions (e.g., lint, safety checks, notifications).

MCP extends Claude to external services (GitHub, databases, Slack, internal APIs).

Skills package reusable workflows; Subagents specify the executor.

Permissions and sandbox enforce security boundaries.

Suggested actions

Individual developer : create ~/.claude/CLAUDE.md, add a project‑level CLAUDE.md, configure basic MCP servers (e.g., GitHub), and enable a lint hook.

Team lead : add .claude/settings.json with shared permissions and hooks, create a .claude/skills/ directory, and version‑control the configs.

Enterprise : enforce Managed settings, restrict allowed MCP servers, enable allowManagedHooksOnly, and audit configurations regularly.

Gradually expand from the simple CLAUDE.md file to the full suite of MCP, Hooks, Skills, and sandboxed permissions to achieve a smooth, secure, and collaborative AI‑assisted development experience.