Chapter 05

Claude Code Config

Where a config file lives decides who it reaches — plus plan mode, CI with -p, and session forking.

D3guide part i

5.1

Three levels of CLAUDE.md

Where the file sits decides who it reaches. That is the whole mechanism.

Narrowing scope, inward. The middle one is the only level a teammate inherits.

5.2–5.3

Split it up: @path imports and .claude/rules/

One monolithic file loads everything, always. Both alternatives exist to stop that.

	`.claude/rules/*.md` + `paths:`	directory `CLAUDE.md`
loads when	Claude edits a file matching the glob	Claude works inside that directory
best for	conventions spread across many directories — tests, migrations	conventions tied to one place and needed nowhere else
organised by	topic: `testing.md`, `api-conventions.md`, `deployment.md`	location
saves	context — irrelevant rules never load	context, within its directory

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

Tests must use describe/it blocks.
Use data factories instead of hardcoding.
Do not mock the database — use a test database.

@path imports

Coding standards are in @./standards/coding-style.md — no space after @, relative paths resolve against the file that contains the import, and nesting stops at 5 levels deep.

Why bother

Each package imports only the standards it needs. Same text, one copy, referenced from wherever it applies.

5.4–5.5

Slash commands and skills

Reusable prompts invoked as /name. Skills are the same idea with configuration on top.

context: forkruns in an isolated subagent — verbose output never lands in the main session

allowed-toolsrestricts the toolset — a review skill that cannot write cannot delete your files

argument-hintprompts for the argument when invoked bare

.claude/commands/ is the legacy form and still works; .claude/skills/*/SKILL.md is current.

---
context: fork
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: "Path to the directory to analyze"
---

Analyze the code structure in the specified directory.

Skill

Invoked on demand for a specific job — review, analysis, generation. Costs nothing until called.

CLAUDE.md

Always loaded. For standards and conventions that apply to everything you do in the repo.

Project skills live in the repo and ship to everyone on clone; the copies under~/.claude/ are yours alone — give personal variants different names so you do not shadow the team's.

5.6

Plan mode vs direct execution

Plan mode reads and proposes; it changes nothing. The question is whether the change is understood yet.

Plan mode

Dozens of files · several plausible approaches · an architectural choice · unfamiliar codebase · a library migration touching 45+ files. Explores with Read, Grep, Glob and produces a plan you approve. No side effects.

Direct execution

Single-file fix with a clear stack trace · adding one validation check · any change that is already unambiguous.

Combined is the normal case: plan → you approve → execute the approved plan.

The Explore subagent is the context tool that pairs with this: it reads widely, returns a summary, and keeps the verbose output out of the main window so a multi-phase task does not run out of room.

5.9

Claude Code in CI

Non-interactive means one flag. Everything else in a pipeline follows from it.

claude -p--print, no input wait

→

--output-format jsonmachine readable

→

--json-schemavalidated shape

→

parseinline PR comments

-p processes the prompt, prints to stdout, exits. It is the only correct way to run in a pipeline.

Fresh instance for review

The session that wrote the code is worse at reviewing it — it still holds its own reasoning and will not challenge it. Review from an independent instance.

Re-review after new commits

Pass the prior review in as context and instruct it to report onlynew or unresolved issues — otherwise it repeats every comment.

5.7–5.8 · 5.10

Resume, fork, compact, memory

Four different things people confuse: continuing context, branching it, compressing it, and persisting it.

A fork inherits everything up to the branch point, then the two sides never see each other again.

--resume namecontinues a named session with its saved context — tool results may be stale if files moved since

fork_sessiontwo independent branches off one shared investigation — for comparing approaches

/compactsummarises history to free the window — and loses exact numbers, dates, specifics

/memoryopens CLAUDE.md to persist notes and conventions across sessions

Recall in 60 seconds

Three levels: user (~/.claude/, never shared) · project (in VCS, everyone) · directory (that folder only).
Team standards in the user-level file is the classic mistake — nobody else receives them.
.claude/rules/ + paths: loads a rule only when a matching file is edited. Best for conventions scattered across dirs.
@path imports: no space after @, resolved relative to the containing file, max nesting 5.
Skill = on demand, context: fork isolates it, allowed-tools constrains it. CLAUDE.md = always loaded.
Plan mode for breadth or ambiguity; direct execution for a clear single-file fix.
CI is always -p / --print. CLAUDE_HEADLESS and --batch do not exist.
Review with a separate instance; on re-review, report only new or unresolved issues.