Chapter 07 — Claude Code Configuration

Domain 3: Claude Code Configuration & Workflows (20%) — task statements 3.1, 3.2, 3.3, 3.4

This is the most fact-dense chapter in the book. Domain 3 items frequently hinge on which file, at which exact path, and the published sample questions use fabricated paths as distractors. Learn the strings, not just the concepts.

1. The CLAUDE.md hierarchy

📎 Three levels, and the distinction between them is examinable.

Level	Path	Scope	Shared via version control?
User	`~/.claude/CLAUDE.md`	Every project you work on, your machine only	No
Project	`.claude/CLAUDE.md` or `./CLAUDE.md` (repo root)	This repository, everyone who clones it	Yes
Directory	`CLAUDE.md` inside a subdirectory	That subtree	Yes

🎯 The most-tested fact: user-level is not shared

~/.claude/CLAUDE.md lives in your home directory. It is not in the repository and therefore cannot be shared with the team.

So any item phrased as "the team should all get these conventions automatically" → project-level, committed. And any item phrased as "this developer prefers X but the team hasn't standardized on it" → user-level.

⚠️ The trap runs both ways. An option suggesting personal preferences go in the committed project file is wrong too — you'd be imposing your habits on everyone.

Precedence

More specific wins. Directory-level overrides project-level, which overrides user-level, with the levels combining rather than wholly replacing each other. For the exam, the useful form is: the most specific applicable file's guidance takes priority.

📎 `@import` syntax

CLAUDE.md can pull in other files:

# Project conventions

@import ./docs/api-conventions.md
@import ./docs/testing-standards.md

🎯 Why it's tested: it lets you keep one entry point while the actual content lives in maintainable, separately-owned files. If an item asks how to compose CLAUDE.md from several existing documents without duplicating them, the answer is @import.

📎 `.claude/rules/` — topic files

Rather than one enormous CLAUDE.md, split guidance into topic files under .claude/rules/:

.claude/rules/
├── terraform.md
├── testing.md
└── api-design.md

📎 `/memory` — verify what's loaded

The /memory slash command shows which memory files are currently loaded. 🎯 This is the answer to any item about diagnosing configuration: "the team added conventions but the agent doesn't seem to follow them — how do you confirm the file is being read?" → /memory.

⚠️ Note that "the agent isn't following CLAUDE.md" has two very different causes, and /memory distinguishes them: either the file isn't loaded (a configuration problem, fixed by path correction) or it's loaded and being ignored (a content problem — the guidance is vague, or it's competing with too much other always-loaded text).

2. Path-specific rules — `.claude/rules/` with `paths:` frontmatter

Task statement 3.3. 🎯🎯 This is the subject of a published sample question and one of the highest-yield facts in Domain 3.

Rules files support YAML frontmatter with a paths: glob list, so the rule applies only to matching files:

---
paths: ["**/*.test.tsx", "**/*.test.ts"]
---

# Test conventions

- Use React Testing Library, never Enzyme.
- Query by accessible role, not by test ID, unless no role applies.
- One assertion per test where practical; name the test after the behaviour.

---
paths: ["terraform/**/*"]
---

# Terraform conventions

- Every resource carries the standard tag set.
- No hardcoded region strings; use the region variable.
- Modules are versioned by git tag, never by branch.

🎯 Why this beats a subdirectory CLAUDE.md

The discriminator in the stem is where the affected files live.

Situation	Correct mechanism
Convention applies to files spread across many directories (test files sitting next to their components, all `.tf` files anywhere)	`.claude/rules/` with `paths:` globs
Convention applies to everything in one subtree	A `CLAUDE.md` in that directory works

For cross-cutting file types, a subdirectory CLAUDE.md fails structurally: you'd have to place a copy in every directory containing a test file, and keep them all in sync. A single rules file with paths: ["**/*.test.tsx"] covers all of them and lives in one place.

⚠️ The distractors on this item: put the conventions in the root CLAUDE.md (loads for every interaction, diluting context with test rules while the developer is editing infrastructure code), or create a CLAUDE.md in each test directory (unmaintainable duplication).

3. Slash commands

📎 One Markdown file per command:

Path	Scope
`.claude/commands/`	Project — committed, available to everyone who clones the repo
`~/.claude/commands/`	User — personal, all your projects, not shared

.claude/commands/
├── review-pr.md
├── add-endpoint.md
└── migrate-schema.md

.claude/commands/review-pr.md becomes /review-pr.

🎯 The team-sharing item

The published sample question: a team wants a standardized set of custom commands available to every developer. The answer is Markdown files in .claude/commands/ in the repository.

The distractors are instructive:

🚫 A commands array in .claude/config.json — this does not exist. Fabricated surface (Chapter 01 §5).
❌ ~/.claude/commands/ — user-level, per-machine, not shared. Each developer would have to create them individually.
❌ Documenting the prompts in a wiki for people to paste — not a mechanism at all.

Same fork, same answer, every time: team-wide → project directory, committed. Personal → home directory. This applies identically to CLAUDE.md, commands, skills, and MCP config. It's one rule with four applications.

4. Skills

Task statement 3.2. 📎 Skills live in .claude/skills/<skill-name>/SKILL.md, with personal variants in ~/.claude/skills/.

📎 SKILL.md frontmatter — know these three fields

---
name: migrate-schema
description: Generate and apply a reversible database migration from a schema change description.
context: fork
allowed-tools: Read, Write, Edit, Bash
argument-hint: <description of the schema change>
---

# Schema migration

1. Read the current schema from `db/schema.sql`.
2. Write a forward migration and a matching rollback in `db/migrations/`.
3. Run the migration against the local test database and verify it applies cleanly.
4. Report the migration filename and the rollback command.

Field	What it does	🎯 Exam relevance
`context: fork`	Runs the skill in a forked context, isolating its work from the main conversation	The answer when a skill does verbose exploration whose intermediate output shouldn't pollute the main session
`allowed-tools`	Restricts which tools the skill may use	Least privilege applied to skills (Reflex 4)
`argument-hint`	Tells the user (and the model) what argument the skill expects	Discoverability and correct invocation

🎯 Skills vs CLAUDE.md — the load-timing distinction

This is the conceptual core of the section:

	CLAUDE.md	Skills
When loaded	Always — every interaction	On demand — only when invoked/selected
Context cost	Paid on every request	Paid only when used
Right for	Conventions that apply broadly: code style, architecture rules, what to never do	Procedures for specific occasional tasks: a migration workflow, a release checklist

The rule: always-relevant guidance → CLAUDE.md. Occasional procedures → skills.

⚠️ The failure mode the exam probes: teams put long task-specific procedures in CLAUDE.md, so every interaction carries instructions for the schema-migration workflow even when the developer is fixing CSS. That's context dilution — real cost, no benefit. If a stem describes a bloated CLAUDE.md with procedures that only sometimes apply, the fix is to move those procedures into skills.

5. The full configuration decision table

🎯 Learn this table. A meaningful share of Domain 3 items are a single lookup in it.

I want to…	Mechanism	Exact path
Give the whole team project conventions	Project CLAUDE.md	`.claude/CLAUDE.md` or `./CLAUDE.md`
Keep my own preferences across all projects	User CLAUDE.md	`~/.claude/CLAUDE.md`
Apply a convention to one subtree	Directory CLAUDE.md	`<subdir>/CLAUDE.md`
Apply a convention to a file type spread across directories	Rules file with globs	`.claude/rules/<topic>.md` + `paths:` frontmatter
Compose CLAUDE.md from existing docs	Import	`@import ./path/to/doc.md`
Share a repeatable prompt with the team	Project slash command	`.claude/commands/<name>.md`
Keep a personal shortcut	User slash command	`~/.claude/commands/<name>.md`
Package a multi-step procedure, loaded only when needed	Skill	`.claude/skills/<name>/SKILL.md`
Isolate a skill's verbose work from the main context	Skill frontmatter	`context: fork`
Restrict what a skill can do	Skill frontmatter	`allowed-tools:`
Give the team the same MCP servers	Project MCP config	`.mcp.json` (committed)
Add a personal MCP server	User MCP config	`~/.claude.json`
Check which memory files are actually loaded	Slash command	`/memory`

6. Worked examples

Example 1 — cross-cutting conventions

A team has testing conventions that apply to all test files. Test files live alongside the components they test, distributed across dozens of directories. The team wants Claude to follow these conventions when working on test files, without loading them during unrelated work. What should the architect configure?

A. A rules file in .claude/rules/ with paths: frontmatter matching the test file glob. B. Add the testing conventions to the root CLAUDE.md. C. Create a CLAUDE.md in each directory that contains test files. D. Add the conventions to ~/.claude/CLAUDE.md.

Answer and reasoning

Two constraints in the stem: files are spread across directories, and the conventions should not load during unrelated work. Path-scoped rules satisfy both — one file, glob-matched, loaded only when the matched files are in play.

B — Root CLAUDE.md is always loaded, violating the second constraint. Test conventions would consume context while the developer edits infrastructure code.
C — Satisfies scoping but is unmaintainable: dozens of duplicated files to keep in sync, and every new component directory needs another one.
D — User-level, so it isn't shared with the team, and it's still always-loaded.

Reflex applied: match the mechanism's scope to the shape of what it governs — file type, not directory.

Example 2 — team-wide commands

A team wants a set of standardized custom slash commands available to every developer working in a repository. What is the correct approach?

A. Create a Markdown file per command in .claude/commands/ and commit it to the repository. B. Define a commands array in .claude/config.json. C. Have each developer add the commands to ~/.claude/commands/. D. Document the prompts in the team wiki for developers to copy.