How to Configure Claude Code with CLAUDE.md: The Complete Guide

You clone a repository, fire up Claude Code, and it ignores every convention your team agreed on. No naming standards. No test patterns. Wrong error handling everywhere. Your colleague swears it works perfectly on their machine.

The culprit is almost always the same thing: configuration sitting in the wrong place. Claude Code reads CLAUDE.md files from three distinct levels, and confusing those levels is the single most common misconfiguration people hit. The exam leans on this hard.

The three-level CLAUDE.md hierarchy

Three levels. Each scoped differently.

User-level lives in your home directory. Not version-controlled. A new team member clones the repository and they never see it. That gap causes more debugging sessions than anyone wants to admit.

Project-level lives inside the repository itself, either at .claude/CLAUDE.md or as a CLAUDE.md at the repo root. Both work. Both travel with git. Clone the repo and you have the instructions — nothing else to set up.

Directory-level files scope to their own directory and nothing else. Drop a /packages/api/CLAUDE.md packed with REST conventions into the API package and those rules activate when you work there. Switch to frontend components two directories over? Gone. Invisible.

The new-team-member trap

You will see this on nearly every practice exam. Developer A has been on the team for months — Claude Code follows all conventions perfectly. Developer B joins, clones the repo, and the output is all over the place.

Developer A stored conventions in ~/.claude/CLAUDE.md (user-level) instead of .claude/CLAUDE.md (project-level). That is always the answer. Move the instructions to project-level and the problem disappears. On the exam, "new team member" plus "inconsistent behaviour" is your cue to check configuration scoping.

Modular organisation with @import

Past a few dozen lines, a single CLAUDE.md file turns into a maintenance headache. The @import syntax breaks it apart:

# .claude/CLAUDE.md
@import ./standards/naming-conventions.md
@import ./standards/error-handling.md
@import ./standards/testing-requirements.md

Each package imports only what applies. API package gets API conventions. Frontend package gets component conventions. No duplication, no drift.

Path-specific rules in .claude/rules/

Neither root CLAUDE.md nor directory-level files handle one scenario well: conventions tied to a specific file type scattered across dozens of directories. Test files co-located with source files are the textbook example — and a real pain to manage without this feature.

The .claude/rules/ directory fixes this with topic-specific rule files and YAML frontmatter for path scoping:

# .claude/rules/testing.md
---
paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
---
# Test Conventions

- Use describe/it blocks with descriptive sentence-style names
- Each test must cover at least one happy path and one error case
- Use factory functions for test data, not inline literals
- Mock external services at the module boundary

Edit a file matching **/*.test.ts and these rules load automatically. Edit a React component and they stay out of the way. One file, every test directory in the codebase.

Why not shove test conventions into root CLAUDE.md? Because that file loads for every session regardless of what you are working on. Your Terraform rules burn tokens while you write React components. Path-specific rules only activate when relevant — better for token budgets, better for signal-to-noise.

When to use which approach

Hooks: automating behaviour around tool calls

Hooks are shell commands that fire in response to Claude Code events. They live in settings.json — not CLAUDE.md, which trips people up — and trigger at specific lifecycle points:

• PreToolUse — runs before a tool executes. Validation gates, logging, blocking dangerous operations.
• PostToolUse — runs after a tool executes. Linting, formatting, notifications.
• Notification — fires on Claude Code notifications. Slack alerts, desktop pings, whatever suits your workflow.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Tool about to execute: Bash'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ]
  }
}

The matcher field targets specific tools by name. Leave it out and the hook fires on every single tool call — probably not what you want. Same principle as programmatic enforcement: deterministic control that the model cannot talk its way around.

MCP server configuration

MCP (Model Context Protocol) servers give Claude Code access to external tools and data sources. Configuration goes in .claude/settings.json at the project level or ~/.claude/settings.json at the user level:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"],
      "env": {}
    },
    "database": {
      "command": "node",
      "args": ["./mcp-servers/database-server.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/app"
      }
    }
  }
}

Same scoping logic as everything else. Project-level (.claude/settings.json) travels with the repo. User-level (~/.claude/settings.json) stays personal. Configure an MCP server at the project level and everyone who clones the repo gets access to it without lifting a finger.

For the full picture on how MCP works under the hood, see the MCP Servers Explained post.

Permissions and the trust model

Claude Code runs under a permission system that balances capability with safety. The allowedTools setting in settings.json pre-approves specific tools so you skip the approval prompt:

{
  "allowedTools": [
    "Read",
    "Glob",
    "Grep",
    "Write",
    "Edit"
  ]
}

Anything not on that list demands explicit approval per use. This is a security boundary, not a convenience toggle. A read-only analysis workflow has no business having Write or Bash access, and the exam wants you to understand that distinction.

Diagnosing configuration issues

The /memory command shows which configuration files are currently loaded in your session. It does not load anything. Read that sentence twice — purely diagnostic.

When Claude Code behaves differently across team members, /memory is where you start. It reveals whether the CLAUDE.md files, rules, and settings you expect are actually active or quietly missing.

The complete project configuration tree

A well-configured project looks something like this:

Shared configuration is all version-controlled. Personal preferences stay in ~/.claude/. Clone the repo, get the full setup — no tribal knowledge required.

What the exam tests

Domain 2 (Claude Code Configuration & Workflows) carries 20% of the exam weight. Configuration questions follow predictable patterns, and once you know the traps you stop falling for them:

The exam rewards understanding of scoping boundaries. Question describes config not reaching the right people? Trace it to which level it lives at. Question about wasted tokens? Path-specific rules are almost certainly the answer they are after.

For the full Domain 2 curriculum, start with CLAUDE.md Hierarchy and Scoping and work through each task statement. The mock exam includes configuration scenarios drawn from these exact patterns.