CCA Domain 3: Claude Code Configuration and Workflows

⚠ Often-missed — Directory CLAUDE.md Doesn't Override, It Adds · Gap

A team lead assumes a src/api/CLAUDE.md file replaces the root CLAUDE.md for that subtree — it doesn't. Both load; the directory file's guidance simply takes precedence where the two conflict. If the root file says "use 4-space indentation" and the directory file is silent on indentation, the root rule still applies inside src/api/. Debugging "inconsistent" agent behaviour across directories almost always means checking /memory to see the full accumulated stack, not assuming one file replaced another.

3.2 — Commands, Skills & Frontmatter · Core

• .claude/commands/ (project, committed) → available to every developer on clone/pull. ~/.claude/commands/ (user) → personal, not shared.
• Name-collision precedence: if the same command name exists at both scopes, the user-scoped version wins for that individual — letting someone personally override a shared command without touching the team file.
• Skills live in .claude/skills/ with a SKILL.md supporting frontmatter: context: fork runs a skill in an isolated sub-agent (keeps verbose output like codebase analysis or exploratory brainstorming out of the main session); allowed-tools is a security boundary restricting what the skill may call (e.g. read-only); argument-hint prompts the developer for required parameters when invoked bare.
• Why context: fork matters beyond tidiness. A codebase-mapping skill that runs inline leaves its entire exploration trail — every file it opened, every dead end — sitting in the main session's context, competing for the model's attention on every subsequent turn. Forking it means only the skill's final summary re-enters the main conversation; the exploration noise is discarded with the sub-agent.
• CLAUDE.md = always loaded (universal standards) vs skills = on-demand (task-specific workflow).
• Personal skill customisation goes in ~/.claude/skills/ under a different name — the same name would just be shadowed by user-scope precedence, not coexist alongside the team version.
• There is no .claude/config.json commands array and no other hidden registration mechanism — a team-wide command that should be available to everyone on clone only ever goes in .claude/commands/, committed to the repo. Putting it in CLAUDE.md instead confuses context (always-loaded background) with a command (explicitly invoked action).

3.3 — Path-Specific Rules for Conditional Conventions · Core

• Files in .claude/rules/ carry YAML frontmatter with a paths glob, so a rule loads only when editing matching files — irrelevant conventions cost zero context when nothing matches.
• **/*.test.tsx matches at any depth; *.test.tsx matches only the current root directory — always use ** for depth.
• No precedence system — multiple matching rules all activate simultaneously on the same file.
• Beats directory-level CLAUDE.md when a convention must apply to a file type scattered across the tree (test files co-located with the components they test) — a directory CLAUDE.md is bound to one subtree and can't cover files spread everywhere.
• Rules activate based on the file currently being edited, not session-start state — they don't persist once you switch to a different file.
• Two rules can both match one file with no conflict resolution needed — a **/*.tsx rule and a **/*.test.tsx rule both load for Button.test.tsx simultaneously; they're additive, not competing, so write each rule narrowly for its own concern instead of trying to make one rule cover everything.

3.4 — Plan Mode vs. Direct Execution · Core

• Decision criterion is complexity and rework risk — NOT file count.
• Plan mode: large-scale changes, multiple valid approaches, architectural decisions (a library migration touching 45+ files, monolith → microservices, service mesh adoption) — explore and design before committing to changes, because a blocking dependency discovered mid-implementation costs far more to unwind than the same dependency surfacing during an explicit planning pass.
• Direct execution: simple, well-scoped, single-concern changes with a clear fix (one validation check, a single-file bug fix with a clear stack trace, a config-key rename). The signal is that there's essentially one reasonable way to make the change, and it touches a single, known location.
• Use the Explore subagent for verbose discovery (e.g. scanning 250+ files) — it isolates noisy exploration and returns a clean summary, preserving the main session's context window. This is the same context-isolation principle as context: fork for skills (3.2) applied to plan-mode investigation.
• Combine the two: plan the investigation (choose the migration strategy), then switch to direct execution to implement the chosen plan.
• Trap answer: "start direct, switch to plan if it gets complex" — wrong when the complexity is already known up front; that answer only fits situations where complexity is discovered mid-task, not stated in the request.

3.5 — Iterative Refinement Techniques · Core

• Concrete input/output examples beat prose when results come out inconsistent — 2–3 examples of the exact transformation communicate a rule that repeated re-description doesn't.
• Test-driven iteration: write the test suite first (expected behaviour, edge cases, performance), then iterate by sharing the exact failing test (input, expected, actual) to guide each fix.
• The interview pattern: have Claude ask you questions first, before implementing in an unfamiliar domain — it surfaces considerations you hadn't anticipated (cache-invalidation strategy, failure modes, eviction policy). This works because the questions come from Claude's model of what could go wrong, not from a checklist you'd have to write yourself.
• Bundle interacting fixes in one detailed message; keep independent problems sequential. The test is whether fix A changes the code structure where fix B needs to land — if it does, sending them one at a time risks the second fix landing against code the first fix already restructured.

3.6 — CI/CD Integration · Core

• -p / --print is required in pipelines — without it Claude Code waits for interactive input and the job hangs. There is no --batch flag and no CLAUDE_HEADLESS env var — those are distractor answers.
• --output-format json + --json-schema enforce structured, machine-parseable output for posting inline PR comments — no brittle regex over prose. The schema guarantees consistent field names (file, line, severity, message) run after run, which is what makes automated comment-posting reliable in the first place.
• --max-turns caps how many agentic-loop iterations a CI invocation may take before it's forced to stop — a safety backstop for pipeline runtime, distinct from (and layered on top of, never a replacement for) the stop_reason-driven loop termination from Domain 1.1.
• --permission-mode plan runs Claude Code in a read-only planning mode inside CI — useful for a "propose changes, don't apply them" review step that still needs the full codebase context.
• Multi-pass for 14+ files (single pass causes attention dilution — inconsistent depth, even self-contradiction across files).
• Use an independent review instance — the same session that generated the code retains its generation reasoning and reviews its own work less critically; a fresh instance catches more.
• Feed prior findings back in so Claude reports only new/unaddressed issues on reruns; supply existing test files so test-generation doesn't duplicate scenarios.
• CLAUDE.md provides project context to CI-invoked Claude Code — testing standards, fixture conventions, review criteria — improving quality without any code changes.
• Session context isolation matters in CI too. The instance that just generated a fix is a worse reviewer of that same fix than a fresh one invoked separately — see Domain 4.6 for why the bias is structural, not a depth-of-reasoning problem.

⚠ Often-missed — Structural File Editing · Gap

For JSON / structured data, use read_file + write_file — Claude understands the data structure natively, which is safer than text-based search-replace that can silently corrupt nesting or quoting.

CLI Cheatsheet · Core

-p · --output-format json · --json-schema · --max-turns · --permission-mode plan · /memory · /compact · /branch · /btw · /context

• /memory — inspect which CLAUDE.md files are currently loaded, at every hierarchy level; the diagnostic tool for "why is behaviour inconsistent."
• /compact — compress conversation history to reclaim context mid-session (see Domain 5.4 for the risk of dropped exact values).
• /context — show current context-window usage; check this before deciding whether a scratchpad or a fresh session is warranted.

Exam reflexes for Domain 3

• "CI pipeline hangs" → missing -p flag (not --batch, not CLAUDE_HEADLESS).
• "Team standards location" → .claude/CLAUDE.md (always, committed) — never ~/.claude/CLAUDE.md.
• "Cross-directory conventions by file type" → .claude/rules/ with a paths glob.
• "Verbose skill output polluting context" → context: fork.
• "Personal override of a shared command" → same name in ~/.claude/commands/ wins for that user.
• "Large PR review inconsistent" → multi-pass (per-file + integration) for 14+ files.
• "Complexity known upfront across many files" → plan mode, not direct execution.
• "Prose instructions produce inconsistent output" → switch to 2–3 concrete I/O examples.
• "Multiple fixes that interact" → bundle in one message; independent fixes stay sequential.
• "Editing JSON/structured config" → read_file + write_file, not text search-replace.
• "Two rules match the same file" → both load — no precedence system, additive by design.
• "CI review instance is the same one that wrote the code" → use an independent instance; the bias is structural.
• "Sub-package needs only some of the team standards" → @import the specific .claude/rules/*.md files it needs.
• "Directory CLAUDE.md seems to silently override the root file" → it doesn't — both load; the directory file only wins on direct conflicts.
• "Read-only proposal step inside a pipeline" → --permission-mode plan, still with full codebase context.