Claude Code Configuration & Workflows cheat sheet

CLAUDE.md hierarchy (3.1)

• Load order: broadest → most specific; CLAUDE.local.md loads after CLAUDE.md at the same level.
• Conflict handling: files are concatenated, never overridden. "Claude may pick one arbitrarily" on a real conflict.
• Enforcement: CLAUDE.md is guidance, not enforcement — for a rule that must hold every time, use settings.json or a hook.
• Exam trap: new teammate gets inconsistent behaviour after cloning → conventions are almost always sitting in someone's ~/.claude/CLAUDE.md instead of project-level.

@ import syntax

• Directive is a bare @path on its own line — no @import keyword in current docs (the exam guide calls the feature "@import" anyway).
• Max recursion depth: 4 hops (older docs said 5).
• Skips markdown code spans/fenced blocks — backtick a path to mention without importing.
• Cross-worktree personal prefs: import a home-directory file, e.g. @~/.claude/my-project-instructions.md.

settings.json precedence (separate system from CLAUDE.md!)

managed > CLI args > local > project > user (strict — a deny at any level can't be overridden by any other level)

• /init — generates/improves CLAUDE.md from codebase analysis.
• /memory — diagnostic only, shows loaded files, never triggers loading.
• Recommended size: under 200 lines per CLAUDE.md.

Slash commands & skills (3.2)

• Scoping: .claude/ = project (git-shared); ~/.claude/ = personal.
• $ARGUMENTS — all args; auto-appended as ARGUMENTS: <value> if unreferenced.
• $N / $ARGUMENTS[N] — positional, 0-based ($0 = first arg).
• !`cmd` — runs shell command pre-send; placeholder becomes real output.
• context: fork — isolated subagent context, no parent history; pair with agent: (Explore/Plan/general-purpose, default general-purpose).
• allowed-tools — current docs: pre-approves for the invoking turn only (NOT a restriction). Exam-guide answer: restricts tool access. Real boundary: disallowed-tools.
• argument-hint — autocomplete hint, e.g. [issue-number].
• disable-model-invocation: true — user-only invocation, description hidden from context.
• user-invocable: false — Claude-only invocation, hidden from / menu.
• Skill(name) exact match / Skill(name *) prefix match — permission rule syntax.
• MCP prompts as commands: /mcp__servername__promptname.
• Decision rule: CLAUDE.md = always-loaded standards; skills = on-demand task workflows.

Path-specific rules (3.3)

---
paths: ["terraform/**/*", "**/*.tf"]
---

• Lives in .claude/rules/*.md, discovered recursively.
• No paths field → loads at launch, same priority as .claude/CLAUDE.md.
• Brace expansion: src/**/*.{ts,tsx}.
• ~/.claude/rules/ = personal, applies to every project; loads before project rules → project rules win on conflict.
• Use over directory CLAUDE.md when a file type is scattered across many directories (e.g. co-located tests).
• Use over root CLAUDE.md when the convention shouldn't burn tokens on unrelated file types.

Plan mode vs direct execution (3.4)

• Enter: Shift+Tab · /plan prefix · claude --permission-mode plan.
• Restricts: edits, until plan approved (exception: bypassPermissions sessions).
• Approve options: "Yes, use auto mode" / "Yes, manually approve edits" / "No, keep planning".
• Ctrl+G — edit the plan directly in your text editor.
• Approving exits plan mode into the chosen mode; Shift+Tab again leaves without approving.
• Project default: permissions.defaultMode: "plan" in .claude/settings.json.

• Decision rule: ambiguity, not difficulty. Multi-approach/architectural/multi-file → plan. Clear stack trace, single fix → direct.
• Explore subagent: read-only (Write/Edit denied); thoroughness quick/medium/very thorough; skips CLAUDE.md + git status (unlike every other subagent).
• Workflow: Explore → Plan → Implement → Commit.

Iterative refinement (3.5)

• /compact <instructions> — targeted summary mid-session.
• --fork-session (with --continue/--resume) or /branch — compare divergent fixes.
• /rewind — restores code/conversation/both; does not track Bash-made changes.
• Writer/Reviewer pattern — independent session reviews without the writer's reasoning bias.

CI/CD integration (3.6)

• -p / --print — non-interactive mode. The most tested fact in Domain 3.
• --output-format: text (default) / json (+ total_cost_usd, cost breakdown) / stream-json (NDJSON).
• --json-schema — validated output in print mode; lands in structured_output field with --output-format json.
• --bare — skips hooks/skills/plugins/MCP/auto-memory/CLAUDE.md; reproducible; will become -p default.
• dontAsk mode — deny-by-default, for locked-down CI.
• Piped stdin cap: 10MB. SIGTERM on -p → aborts turn, runs SessionEnd hooks, exit 143.
• Session isolation: same session that wrote code reviews it worse (retains self-justifying reasoning) — use an independent claude -p invocation to review.
• Incremental review: feed prior findings back in; report only new/unaddressed issues.
• CLAUDE.md in CI: loads exactly as interactive — the way to supply testing standards, fixtures, review criteria.
• Batch API: 50% cheaper, up to 24h, no latency SLA → never for pre-merge (blocking) checks; fine for nightly/weekly.
• GitHub Actions: built on Agent SDK; @claude mention (default trigger_phrase); app needs read & write on Contents/Issues/Pull requests; claude_args = full CLI passthrough; action --max-turns default 10.
• CI gate idea: fail on non-empty plugin_errors / mcp_server_errors in the stream-json system/init event.

Known exam-guide vs current-docs divergences

See research/divergences/domain-3.md for full detail. Quick list:

• allowed-tools restricts (exam guide) vs pre-approves (current docs; disallowed-tools is the real boundary).
• "@import syntax" (exam guide's name) vs bare @path, no keyword (current docs).
• @ import depth: 4 hops now (was 5 in older docs).
• Slash commands and skills are one merged system in current docs; the exam guide still frames them as two separate features.
• Positional arguments ($N) are 0-based in current docs.
• Permission modes now also include auto and dontAsk, beyond the plan/direct binary the exam guide frames.