Kairox Arch Prep
STUDY NOTES · LESSON 7 OF 12 · 7 MIN READ

A map of Claude Code configuration

Where every Claude Code setting lives — CLAUDE.md, path rules, settings and permissions, commands, skills, subagents, hooks and MCP — shown as one map.

In 30 seconds

  • Ask two questions: is it for the team or just me, and is it guidance or enforcement?
  • Team guidance lives in committed CLAUDE.md files and path-specific rules; personal guidance in user-level files.
  • Permissions and hooks enforce; CLAUDE.md only guides.
  • Repeated work becomes commands or skills; specialised helpers become subagents.

The map

Where Claude Code configuration lives
PurposeShared with the team (committed)Just you
InstructionsCLAUDE.md at the root; CLAUDE.md in subdirectories (loaded when Claude reads files there); .claude/rules/ with paths patterns~/.claude/CLAUDE.md (all projects); CLAUDE.local.md (this project, git-ignored)
Permissions and settings.claude/settings.json.claude/settings.local.json; ~/.claude/settings.json
Reusable work.claude/commands/, .claude/skills/, .claude/agents/The same folders under ~/.claude/
External tools.mcp.json (no secrets inside)Your user-level MCP configuration

Guidance: keep it short and scoped

Everything in CLAUDE.md is loaded into context, so a long file full of history dilutes the rules that matter. Keep the root file to build commands, conventions and architecture notes. Put area-specific guidance next to the code it describes, or in a path-specific rule that loads only when Claude touches matching files. Imports with @path help organise files, but imported content still loads at launch.

Enforcement: permissions and hooks

Permission rules allow, ask for, or deny tools and commands. Hooks run your own commands at points in Claude Code's lifecycle.

Hook points around a tool call in Claude CodePreToolUse hookinspect the inputblock or allowTool runsEdit, Write, Bash…PostToolUse hookformat · lint · logallowedblocked → never runs
PreToolUse can inspect and block a call; PostToolUse runs after it, which suits formatters, linters and logging.

A PreToolUse hook can inspect what Claude is about to do and block it — for example, any write to migrations/. For a real guarantee, cover every route to the action, including shell commands. A PostToolUse hook is the right place for a formatter, because it runs after every edit without anyone remembering to ask.

Reusable work

A routine the team types many times a day becomes a project command or skill that anyone can invoke by name. A specialised helper with its own instructions and a narrow tool list — a test writer, a security reviewer — becomes a subagent that the main session can delegate to.

Plan before risky changes

For a wide change in unfamiliar code, plan mode lets Claude explore and propose without editing files, so you approve the approach before anything changes. Between unrelated tasks, clear the session; for one long task, compact it.

Part of Domain 3: Claude Code Configuration & Workflows (20% of the exam). Explanations are our own, checked against Anthropic's documentation on November 22, 2026.

Common traps

TrapWhy it failsDo this instead
Personal preferences in the root CLAUDE.mdImposes them on the whole teamUse ~/.claude/CLAUDE.md or CLAUDE.local.md
"Never edit migrations" in CLAUDE.mdGuidance, not enforcementDeny rules plus a PreToolUse hook
Area rules in the root fileLoaded for every taskSubdirectory CLAUDE.md or .claude/rules with paths

Check yourself

Two original practice questions on this lesson. Try them before opening the answers.

Check yourself 1

Scenario: Claude Code for continuous integration

You must guarantee that Claude Code never edits files under migrations/ in a repository, regardless of what it is asked. Which mechanism is most reliable?

  1. A. A clear rule in the root CLAUDE.md explaining that migrations must never be edited
  2. B. A CLAUDE.md inside migrations/ that warns Claude whenever it works in that folder
  3. C. A PostToolUse hook that alerts the team in chat whenever a migration file changes
  4. D. Enforced controls: deny rules and a PreToolUse hook covering every write path, shell included
Show answer and explanation

Answer: D. CLAUDE.md content is guidance the model usually follows; hooks and permission rules are enforced by the harness. The guarantee only holds if every route to a write is covered — edit and write tools and shell commands — so a PreToolUse hook that inspects tool input and blocks matches, plus deny rules (and, for full certainty, read-only file permissions for the agent process). A PostToolUse alert fires after the damage is done.

Check yourself 2

Scenario: Code generation with Claude Code

API handlers under src/api/ follow strict validation and error-format rules that are irrelevant elsewhere in a large repository. You want those rules in context only when Claude works on API files. What should you use?

  1. A. An @import in the root CLAUDE.md that pulls in a separate api-rules.md file
  2. B. A rules file in .claude/rules/ with a paths pattern matching src/api/ files
  3. C. A PreToolUse hook that prints the API rules whenever any file is edited
  4. D. A section at the top of the root CLAUDE.md headed "API rules (only for src/api)"
Show answer and explanation

Answer: B. Path-specific rules in .claude/rules/ with a paths field load conditionally, when Claude reads files matching the pattern, which is exactly conditional convention loading. A root CLAUDE.md section and an @import both load at launch for every session, whatever the task, and a hook on every edit is noisy and fires for files outside src/api/.

Keep going