cruxlevel

Claude Architect · study module 2/5

Claude Code Configuration and Workflows

20% of the exam · ~70 min read

Cheat sheet — the night-before version

  • CLAUDE.md hierarchy: user-level ~/.claude/CLAUDE.md, project-level .claude/CLAUDE.md or root CLAUDE.md, directory-level CLAUDE.md in subdirectories
  • User-level config is NOT shared via version control — 'my teammate doesn't get the rule' almost always means it lives in ~/.claude/
  • @import pulls external standards files into CLAUDE.md to keep it modular; .claude/rules/ splits a monolith into topic files (testing.md, api-conventions.md, deployment.md)
  • The /memory command shows which memory files are actually loaded — the diagnostic for inconsistent behavior across sessions
  • Commands: .claude/commands/ = project-scoped, shared via version control. ~/.claude/commands/ = user-scoped, personal
  • Skills live in .claude/skills/ as SKILL.md; frontmatter is HYPHENATED — context: fork, allowed-tools, argument-hint (the Agent SDK's camelCase allowedTools is a different thing)
  • context: fork runs a skill in an isolated sub-agent context so verbose output never pollutes the main conversation
  • Path-scoped rules: .claude/rules/ files with a YAML frontmatter paths field of glob patterns, loaded only when editing matching files — and they beat directory-level CLAUDE.md when a convention spans directories (**/*.test.tsx everywhere vs one folder)
  • Plan mode = large-scale changes, multiple valid approaches, architectural decisions, multi-file. Direct execution = simple, well-scoped, single-file
  • The Explore subagent isolates verbose discovery output and returns summaries, preserving main-conversation context
  • CI: -p (or --print) for non-interactive runs; --output-format json with --json-schema for machine-parseable findings
  • A session that generated code is a weak reviewer of that code — CI review needs an independent instance, not a self-review instruction

What this domain tests

20% — roughly 12 of 60 questions, tied with Prompt Engineering & Structured Output for second-heaviest. First-hand reports call CCAR-F the most memorization-heavy of the four Claude certifications: CLI arguments, file locations, frontmatter keys, parameter values, "you either know it or you don't." This domain is the single densest concentration of that material, because almost every task statement names a specific path or flag.

The split you should expect:

  • Recall items: where user-level versus project-level configuration lives, which directory holds shared slash commands, which frontmatter key isolates a skill's context, which flag makes Claude Code non-interactive, which flag pair produces structured CI output.
  • Judgment items: plan mode versus direct execution for a given change, path-scoped rules versus a subdirectory CLAUDE.md, one message versus sequential messages when iterating on multiple defects.

Three of the six published exam scenarios lean on this domain — more than any other. Scenario 2 (Code Generation with Claude Code) names custom slash commands, CLAUDE.md configurations, and plan-mode-versus-direct-execution explicitly. Scenario 4 (Developer Productivity with Claude) pairs it with tool design. Scenario 5 (Claude Code for Continuous Integration) pairs it with prompt engineering. On a four-scenario draw you are very likely to see at least two Claude Code frames.

Two adjacent topics candidates expect here and won't find: MCP server scoping (.mcp.json versus ~/.claude.json) is tested under Domain 2, Tool Design & MCP Integration; session resume and forking (--resume, fork_session) is tested under Domain 1, task 1.7. Study them — just not for credit here.

Theory outline

1. CLAUDE.md hierarchy, scoping, and modular organization (Task 3.1)

CLAUDE.md is Claude Code's always-loaded instruction memory. Three levels exist, and the exam cares mostly about who each level reaches.

LevelLocationScopeShared with the team?
User~/.claude/CLAUDE.mdThat user, across all their projectsNo — never version-controlled
Project.claude/CLAUDE.md or root CLAUDE.mdEveryone working in the repositoryYes, via version control
DirectoryCLAUDE.md inside a subdirectoryWork happening in that subtreeYes, via version control

The canonical diagnostic scenario: a new team member's Claude Code doesn't follow a convention everyone else's does. The cause is almost always that the convention was written into someone's user-level ~/.claude/CLAUDE.md, which never left that machine. The fix is to move it to project-level configuration so version control distributes it. Any option involving "ask the new member to copy your file" treats the symptom.

Keeping it modular. Two mechanisms, and they are not interchangeable:

  • @import references an external file from inside CLAUDE.md. Use it to pull only the standards files relevant to a given package — a monorepo's payments package imports the payments and security standards, the web package imports the frontend ones. The maintainer's domain knowledge decides which imports go where.
  • .claude/rules/ is a directory of topic-specific rule files — testing.md, api-conventions.md, deployment.md — used as an alternative to one sprawling CLAUDE.md. (Rules files also support path scoping; that's task 3.3.)

Verification. The /memory command shows which memory files are currently loaded. When behavior is inconsistent across sessions or a rule appears to be ignored, /memory is the diagnostic step — it turns "Claude isn't following my instructions" into "that file was never loaded."

Exam angle: the guide frames every 3.1 skill as a diagnosis, not a description. Expect stems that describe broken behavior and ask for the cause, where the correct answer names a scoping level.

2. Custom slash commands and skills (Task 3.2)

Slash commands — reusable prompts invoked by name.

LocationScope
.claude/commands/Project-scoped; shared with the team via version control
~/.claude/commands/User-scoped; personal, not shared

Same shared-versus-personal split as CLAUDE.md, same trap: "the whole team should be able to run /review-pr" means .claude/commands/, in the repository.

Skills live in .claude/skills/ as SKILL.md files with frontmatter configuration. Three frontmatter options the guide names explicitly — memorize the exact spelling, all hyphenated:

Frontmatter keyEffect
context: forkRuns the skill in an isolated sub-agent context so its output does not pollute the main conversation
allowed-toolsRestricts which tools the skill may use during execution (e.g., limiting file write operations to prevent destructive actions)
argument-hintPrompts the developer for required parameters when they invoke the skill without arguments

context: fork is the one to understand, not just memorize. Use it for skills that produce verbose output (a codebase analysis) or exploratory context (brainstorming alternatives) — the work happens in a forked sub-agent context and only the result comes back, so the main session's context window stays clean. Same instinct as the Explore subagent in section 4.

Personal customization without stepping on teammates: create a variant in ~/.claude/skills/ under a different name. Editing the shared project skill changes everyone's behavior; a user-scoped copy with its own name changes only yours.

Skills versus CLAUDE.md — the distinction the guide draws:

LoadingContent
CLAUDE.mdAlways loadedUniversal standards that apply to all work
SkillsInvoked on demandTask-specific workflows you only sometimes need

A workflow used in 5% of sessions belongs in a skill. Putting it in CLAUDE.md taxes every session's context for a rare benefit.

Exam angle: the hyphenated skill frontmatter (allowed-tools) versus the Agent SDK's camelCase allowedTools (task 1.3) is exactly the kind of near-collision this exam exploits. They are different surfaces with different spellings. Know both.

3. Path-specific rules for conditional convention loading (Task 3.3)

Files in .claude/rules/ can carry YAML frontmatter with a paths field containing glob patterns. The rule then loads only when Claude is editing files matching those globs — for example, paths: ["terraform/**/*"] activates infrastructure conventions only during infrastructure work.

Two payoffs, and the exam tests both:

  • Less irrelevant context and lower token usage. Conventions that don't apply to the current file never enter the window.
  • Conventions that span directories. This is the decisive advantage over directory-level CLAUDE.md files. Test files scattered throughout a codebase can't be covered by one subdirectory CLAUDE.md, but **/*.test.tsx as a path glob catches every one of them regardless of location.

The decision rule:

Convention shapeMechanism
Applies to everything in one directory subtreeDirectory-level CLAUDE.md
Applies to a file type scattered across the codebasePath-scoped rule with a glob
Applies universally to all workProject-level CLAUDE.md
Personal preference, all your projectsUser-level ~/.claude/CLAUDE.md

Exam angle: whenever a stem says the files are "spread throughout the codebase" or "regardless of directory," the glob-pattern rule is the answer and the subdirectory CLAUDE.md is the distractor.

4. Plan mode versus direct execution (Task 3.4)

The guide draws this line by change shape, not by difficulty or by developer preference.

Use when
Plan modeComplex tasks: large-scale changes, multiple valid approaches, architectural decisions, multi-file modifications
Direct executionSimple, well-scoped changes — a single validation check added to one function, a single-file bug fix with a clear stack trace, a date validation conditional

The purpose of plan mode is safe codebase exploration and design before committing to changes, which is what prevents costly rework. Named examples on the plan-mode side: restructuring a microservice, a library migration affecting 45+ files, choosing between integration approaches with different infrastructure requirements. The common thread is that a wrong first move is expensive to unwind.

The Explore subagent is the context-management half of this task statement: it isolates verbose discovery output and returns summaries, preserving the main conversation's context. Use it for verbose discovery phases so a multi-phase task doesn't exhaust the context window before implementation starts.

They compose. The guide explicitly endorses plan mode for investigation, then direct execution for implementation — plan the library migration, then execute the planned approach. "Plan mode or direct execution" as a permanent either/or is a false frame the exam sets up so you can knock it down.

Exam angle: a stem citing a file count ("45+ files"), an architectural fork, or "several reasonable approaches" points at plan mode. A stem citing a clear stack trace and one file points at direct execution. Options offering plan mode for a one-line fix are testing whether you over-apply the heavyweight tool.

5. Iterative refinement for progressive improvement (Task 3.5)

Four named techniques. Each has a distinct trigger — the exam picks a trigger and asks for the matching technique.

Concrete input/output examples. When prose descriptions are interpreted inconsistently, 2–3 concrete input/output examples are the most effective way to communicate the expected transformation. This also applies at edge-case granularity: to fix null-value handling in a migration script, give a specific test case with example input and expected output.

Test-driven iteration. Write the test suite first — covering expected behavior, edge cases, and performance requirements — then iterate by sharing test failures to guide progressive improvement. The failures carry precise, checkable signal that a prose complaint doesn't.

The interview pattern. Have Claude ask questions to surface considerations the developer may not have anticipated before implementing — cache invalidation strategies, failure modes. Reach for it in unfamiliar domains, where the risk is not that Claude codes badly but that you specified badly.

Batching versus sequencing fixes — the subtle one:

ProblemsHow to send them
Interacting (fixes affect each other)All issues in a single detailed message, so Claude can reconcile them together
IndependentFix sequentially, one at a time

Get the direction right: interacting → one message; independent → sequential. Sending interacting problems one at a time invites each fix to undo the last.

6. Integrating Claude Code into CI/CD pipelines (Task 3.6)

The most recall-dense task statement in the domain. Memorize the flags.

FlagPurpose
-p (or --print)Non-interactive mode for automated pipelines — prevents CI hangs waiting on interactive input
--output-format jsonEmits machine-parseable structured output
--json-schemaEnforces a specific structure on that output

The intended CI combination is --output-format json with --json-schema, producing structured findings a pipeline can post as inline pull-request comments without brittle text parsing.

CLAUDE.md is the context channel for CI. A CI-invoked Claude Code run has no human to explain the project. Documenting testing standards, valuable test criteria, and available fixtures in CLAUDE.md is what raises test-generation quality and cuts low-value output.

Session context isolation — the conceptual item in an otherwise mechanical task statement. The same session that generated code is less effective at reviewing its own changes than an independent review instance, because it carries its generation reasoning forward and is disinclined to question decisions it just made. In CI, the reviewer should be a separate invocation. (Domain 4, task 4.6, tests the same principle from the prompt-architecture side.)

Two workflow refinements the guide names:

  • Re-running review after new commits: include the prior review findings in context and instruct Claude to report only new or still-unaddressed issues. Otherwise every re-run re-posts the same comments and developers stop reading them.
  • Test generation: provide the existing test files in context so the generated suite doesn't duplicate scenarios already covered.

Both are the same idea: a CI job is stateless, so any continuity it needs must be handed to it explicitly.

Worked problems

Problem 1. A team lead wrote the repository's API conventions into ~/.claude/CLAUDE.md months ago. Everyone on the original team follows them. A new engineer joins, and their Claude Code sessions ignore the conventions entirely. What is the cause and fix?

A. The new engineer needs to run /memory to load the file B. The conventions live in user-level configuration, which is not shared via version control — move them to project-level configuration (.claude/CLAUDE.md or root CLAUDE.md) C. The new engineer's Claude Code version is out of date D. The conventions should be converted into a skill so they load on demand

Approach: The distinguishing detail is who is affected — everyone with the original setup is fine, the new person is not. That pattern means the instruction never travelled. User-level configuration applies only to that user and is not version-controlled, so a new clone gets nothing.

Why the others fail: A misreads /memory — it reports which memory files are loaded, a diagnostic, not a way to load a file that doesn't exist on that machine. C invents a version problem with no supporting symptom. D makes always-applicable API conventions opt-in, which is backwards: universal standards belong in CLAUDE.md, task-specific workflows belong in skills.

Answer: B


Problem 2. A developer builds a codebase-analysis skill that produces several thousand words of exploration output. Every time a teammate runs it, the main conversation fills with raw analysis and later work degrades. Which SKILL.md frontmatter setting addresses this?

A. allowed-tools, restricted to read-only tools B. argument-hint, so the developer scopes the analysis before it runs C. context: fork, so the skill runs in an isolated sub-agent context and only its result returns D. Move the skill to ~/.claude/skills/

Approach: The complaint is context pollution from verbose output — precisely the case the guide gives for context: fork. The skill runs in an isolated sub-agent context, so the exploration burns a forked context window instead of the main one.

Why the others fail: A restricts which tools the skill may call; that limits blast radius, not verbosity. B collects parameters at invocation time and doesn't change where output lands. D changes the skill's scope — who can run it — not its context behavior, and it would also remove it from the team.

Answer: C


Problem 3. A codebase has test files in dozens of directories. The team wants testing conventions applied whenever Claude edits any test file, without loading them during unrelated work. What should they configure?

A. Add the conventions to the root CLAUDE.md B. Put a CLAUDE.md in each directory that contains test files C. A .claude/rules/ file with YAML frontmatter paths globs matching test files, so it loads only when editing them D. A slash command the developer runs before touching tests

Approach: Two requirements — conditional loading and coverage across scattered directories. Path-scoped rules satisfy both: the paths frontmatter takes glob patterns, and a glob matches by file type regardless of location. The guide states this is the advantage of glob rules over directory-level CLAUDE.md.

Why the others fail: A loads the conventions during every session, including work that has nothing to do with tests — the token cost the task statement exists to avoid. B is the named distractor: it works only if test files are confined to specific directories, and it means maintaining dozens of copies. D depends on a human remembering, which is not a configuration mechanism.

Answer: C


Problem 4. An engineer must migrate a library used across 45+ files, choosing between two adapter strategies with different infrastructure implications. How should they run Claude Code?

A. Direct execution, file by file, correcting as they go B. Plan mode to explore the codebase and settle the approach, then direct execution to implement the chosen plan C. Plan mode for the entire migration, including every edit D. A path-scoped rule describing the migration, then direct execution

Approach: The stem hits three plan-mode triggers at once: large-scale change, multiple valid approaches, multi-file modification. But plan mode is for exploration and design before committing to changes — the guide explicitly endorses combining it with direct execution for the implementation phase.

Why the others fail: A commits to a strategy before comparing them, which is the "costly rework" plan mode exists to prevent. C misunderstands the mode: it is a design phase, not a permanent operating mode. D confuses configuration with workflow — rules carry conventions, not one-off migration plans.

Answer: B


Problem 5. A CI job runs Claude Code to review pull requests. It intermittently hangs, and the pipeline parses review text with brittle regular expressions to build inline comments. What configuration fixes both problems?

A. Run with -p (or --print) for non-interactive execution, and use --output-format json with --json-schema for structured findings B. Increase the CI job timeout and improve the regular expressions C. Move the review prompt into a project-scoped slash command D. Run the review inside plan mode so it produces a structured plan

Approach: Two symptoms, two named flags. Hanging in automation is what -p / --print exists to prevent; brittle text parsing is what --output-format json plus --json-schema exists to prevent. This is a straight recall item wearing a scenario costume.

Why the others fail: B accommodates both defects instead of removing them. C makes the prompt reusable but doesn't change interactivity or output format. D produces a plan, not machine-parseable review findings, and doesn't address the hang.

Answer: A


Problem 6. A pipeline generates code with Claude Code, then asks that same session to review its own output. Reviews are shallow and rarely question the design. What is the most effective change?

A. Add "review your work critically and look for mistakes" to the review prompt B. Run the review as an independent Claude Code instance without the generation session's reasoning context C. Raise the review step's token budget D. Have the generating session write tests for its own code first

Approach: The guide's stated principle: a session that produced the code retains its generation reasoning and is less likely to question decisions it just made. The remedy is structural — a separate instance that arrives without that context — not a stronger instruction inside the compromised session.

Why the others fail: A is a prompt patch on a context problem; the reasoning that produced the code is still in the window. C gives the same biased reviewer more room. D is a legitimate iterative-refinement technique (task 3.5) but doesn't remove the self-review bias — the same session still authored both.

Answer: B

Exam traps

  • User-level configuration reaching teammates. ~/.claude/CLAUDE.md, ~/.claude/commands/, and ~/.claude/skills/ are personal and never version-controlled. Any "the team should all get this" requirement means the project-scoped path: .claude/CLAUDE.md or root CLAUDE.md, .claude/commands/, .claude/skills/.
  • Hyphenated skill frontmatter versus camelCase SDK config. Skills use allowed-tools, argument-hint, context: fork. The Agent SDK's coordinator config uses allowedTools. Different surfaces, different spellings — options swap them.
  • /memory misread as a loader. It reports which memory files are loaded. It is a diagnostic for inconsistent behavior, not a way to import configuration.
  • Subdirectory CLAUDE.md for scattered file types. If the stem says the files are spread across the codebase, the answer is a path-scoped .claude/rules/ file with a glob, not a CLAUDE.md per directory.
  • Everything into CLAUDE.md. Always-loaded means always-paid. Universal standards go in CLAUDE.md; occasional task-specific workflows go in skills, invoked on demand.
  • Plan mode for trivial changes. A single-file fix with a clear stack trace is direct execution. Plan mode earns its cost on large-scale, multi-approach, architectural, multi-file work.
  • Treating plan mode and direct execution as mutually exclusive. The endorsed pattern is plan for investigation, then execute the planned approach.
  • Forgetting the Explore subagent. When the problem is verbose discovery exhausting context during a multi-phase task, the answer names Explore — isolate the discovery, return a summary.
  • Batching independent fixes / sequencing interacting ones. It runs the other way: interacting problems go in one detailed message; independent problems are fixed sequentially.
  • Missing -p in CI. Without --print, an automated run can hang on interactive input. Options that raise the timeout are treating a symptom.
  • Stateless CI runs assumed to remember. Re-running review after new commits requires passing the prior findings in and instructing "only new or still-unaddressed"; test generation requires passing existing test files in. Nothing carries over on its own.
  • Self-review in the generating session. The reviewer must be an independent instance. Instructions telling the model to be critical of itself do not remove the generation context.

Prefer being taught? This guide exists as an adaptive tutor course inside Claude Code — your agent teaches it, quizzes your weak spots, and tracks progress. How it works · included in membership (founding: $0)

Now prove it: the Claude Code Configuration and Workflows quiz

Original practice questions on exactly this domain — instant explanations, domain score, and your wrong-answer notebook at the end.

Take the quiz →

Next module: Prompt Engineering and Structured Output