Cheatsheet 2 — Claude Code Configuration Decisions

Domain 3 (20%). The highest-density recall material on the exam. If you memorize one page, memorize this one.

The paths

Path	Scope	Version-controlled?	What goes here
`~/.claude/CLAUDE.md`	User — all your projects	❌ No	Personal preferences that shouldn't affect teammates
`CLAUDE.md` (repo root) or `.claude/CLAUDE.md`	Project — everyone on the repo	✅ Yes	Team-wide conventions, always relevant
`<subdir>/CLAUDE.md`	That directory's subtree	✅ Yes	Conventions truly local to one directory
`.claude/rules/<topic>.md`	Project, scoped by `paths:`	✅ Yes	Topic conventions that apply by file pattern, across directories
`.claude/commands/<name>.md`	Project slash command `/name`	✅ Yes	Repeatable team workflows
`~/.claude/commands/<name>.md`	User slash command `/name`	❌ No	Your personal workflows
`.claude/skills/<name>/SKILL.md`	Project skill	✅ Yes	On-demand procedures loaded only when invoked
`.mcp.json` (repo root)	Project MCP servers	✅ Yes — committed	Team-shared servers, secrets via `${ENV_VAR}`
`~/.claude.json`	User MCP servers	❌ No	Personal servers

One Markdown file per slash command. There is no commands array, and no .claude/config.json.

The decision table

The requirement	The answer
Conventions every teammate needs, always	Project `CLAUDE.md`
Personal style preference, don't impose on the team	`~/.claude/CLAUDE.md`
Conventions for all test files wherever they live	`.claude/rules/testing.md` with `paths:` globs
Conventions for one directory's subtree only	That directory's `CLAUDE.md`
Long shared context you want composed in	`@import ./docs/whatever.md` from CLAUDE.md
Verify what's actually loaded	`/memory`
Repeatable workflow the whole team runs	`.claude/commands/<name>.md` (committed)
Repeatable workflow only you run	`~/.claude/commands/<name>.md`
Verbose procedure that shouldn't pollute the main context	Skill with `context: fork`
Restrict what a skill may do	`allowed-tools` in SKILL.md frontmatter
Tell the user what arguments a skill takes	`argument-hint` in SKILL.md frontmatter
MCP servers the team shares	`.mcp.json`, committed, secrets as `${ENV_VAR}`
MCP server just for you	`~/.claude.json`
Give a CI run project conventions	`CLAUDE.md` — it's read in headless mode too

`.claude/rules/` with path scoping

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

# Testing conventions

- React components: React Testing Library, never Enzyme.
- One assertion concern per test; no snapshot tests for logic.
- Mock at the network boundary with MSW, not by stubbing modules.

🎯 Why rules beat a subdirectory CLAUDE.md: test files live in many directories. A paths: glob matches them wherever they are and loads nothing when you're working elsewhere. A subdirectory CLAUDE.md would need duplicating per directory and would miss any new one.

SKILL.md frontmatter

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

# Steps
1. Read the current schema from db/schema.sql
...

Field	Effect
`context: fork`	Runs in an isolated context; the verbose middle doesn't enter the main conversation
`allowed-tools`	Scopes the skill to these tools only
`argument-hint`	Shown to the user when invoking

Skills vs CLAUDE.md: skills are on-demand (loaded when invoked); CLAUDE.md is always loaded. Anything not always relevant belongs in a skill or a path-scoped rules file, not in CLAUDE.md.

Plan mode vs direct execution

Use plan mode	Use direct execution
Large scale of change	Small, well-defined edit
Multiple viable approaches	One obvious approach
Architectural decisions	Mechanical change
Multi-file coordination	Single file

Four triggers, in one line: large scale · multiple approaches · architectural · multi-file.

CI / headless

Need	Flag
Non-interactive run	`-p` / `--print`
Machine-parseable result	`--output-format json`
Constrain the output shape	`--json-schema`

claude -p "Review the staged diff against .claude/rules/ and report findings." \
  --output-format json \
  --json-schema ./ci/review-schema.json

🚫 Non-existent flags and env vars that appear as distractors: CLAUDE_HEADLESS, --batch, --ci, --non-interactive, a commands array in .claude/config.json, parallel: true.

Session mechanics

Situation	Mechanism
Same session, context filling, history still valid	`/compact`
Returning to a task, workspace unchanged	`--resume <session-name>`
Try a variant without losing the original	`fork_session`
Old tool results are now stale	Fresh session + a structured summary

Two facts that decide items on their own

~/.claude/CLAUDE.md is not version-controlled. Anything the team must have cannot go there.
The session that generated the code is worse at reviewing it. Review needs a fresh, independent context — not more thinking in the same one.