Claude Code Configuration & Workflows: Architect Exam Domain 3

Lesson 4 of the Claude Certified Architect – Foundations course. Domain 3 carries 20% of the exam (~12 questions) and covers Claude Code as a team platform: configuration hierarchy, conditional rules, skills, mode selection, iterative refinement, and CI/CD. Two exam scenarios — "Code Generation with Claude Code" and "Claude Code for CI" — draw primarily from this lesson.

Previous: Lesson 3 — Tool Design & MCP

Back to Course Overview

The CLAUDE.md Hierarchy

Three levels, and the exam will test whether you know what's shared:

The classic diagnostic scenario: a new team member isn't getting the team's instructions. Root cause: the instructions live in someone's user-level file instead of project level. Debug tool: the /memory command shows exactly which memory files are loaded in the current session.

Keeping project config maintainable:

• @import syntax references external files, so each package's CLAUDE.md can pull in just the standards relevant to it
• .claude/rules/ holds focused topic files (testing.md, api-conventions.md, deployment.md) instead of one monolith

Path-Scoped Rules: Conditional Convention Loading

Rules files in .claude/rules/ accept YAML frontmatter with a paths field of glob patterns:

---
paths: ["**/*.test.tsx"]
---
All tests use React Testing Library; no snapshot tests; ...

The rule loads only when editing matching files — less irrelevant context, fewer tokens. The killer use case: conventions for files spread across the codebase (test files sitting next to their components). A directory-level CLAUDE.md can't follow them; a glob rule can. When a scenario mentions "same conventions regardless of location," the answer is path-scoped rules, not per-directory CLAUDE.md files and not hoping Claude infers the right section of a monolithic file.

Slash Commands and Skills

Commands: .claude/commands/ (project — version-controlled, everyone gets it on clone/pull) vs ~/.claude/commands/ (personal).

Skills: .claude/skills/ with a SKILL.md supporting three frontmatter options the exam names explicitly:

• context: fork — run the skill in an isolated sub-agent context so verbose output (codebase analysis, brainstorming) doesn't pollute the main conversation
• allowed-tools — restrict tool access during skill execution (e.g., file writes only, no Bash)
• argument-hint — prompts the developer for required parameters when invoked bare

Personal variants: copy a skill into ~/.claude/skills/ under a different name so you don't shadow the team version.

Skills vs CLAUDE.md in one line: skills are on-demand invocation for task-specific workflows; CLAUDE.md is always-loaded universal standards.

Plan Mode vs Direct Execution

The judgment matrix:

Plan mode buys safe exploration and design before changes, preventing costly rework. Do not pick "start direct and switch to plan mode if complexity emerges" when the complexity is already stated in the requirements — that's a recurring distractor.

Related: the Explore subagent isolates verbose discovery output and returns summaries, preserving the main conversation's context budget during multi-phase tasks.

Iterative Refinement Techniques

Four named patterns:

1. Concrete input/output examples (2–3) when prose descriptions of a transformation are interpreted inconsistently — the single most effective clarifier.
2. Test-driven iteration — write the test suite first (expected behavior, edge cases, performance), then iterate by sharing failures.
3. The interview pattern — have Claude ask you questions before implementing in an unfamiliar domain, surfacing considerations (cache invalidation, failure modes) you hadn't specified.
4. Batched vs sequential fixes — report multiple issues in a single detailed message when the fixes interact; fix sequentially when they're independent.

Claude Code in CI/CD

The flags and facts Domain 3 tests verbatim:

• -p / --print — non-interactive mode. Without it, a pipeline invocation hangs waiting for input. (CLAUDE_HEADLESS=true and --batch do not exist — they're distractor bait.)
• --output-format json + --json-schema — machine-parseable structured findings, e.g., for posting inline PR comments.
• CLAUDE.md provides project context to CI runs — testing standards, fixture conventions, review criteria. Documenting what makes a test valuable measurably reduces low-value generated tests.
• Session context isolation: the session that generated code is worse at reviewing it than an independent instance — it retains its own reasoning and won't question its decisions. Spin up a fresh instance for review (full treatment in Lesson 5).
• Re-review hygiene: include prior findings in context and instruct Claude to report only new or still-unaddressed issues, avoiding duplicate PR comments. Same idea for test generation: provide existing test files so it doesn't duplicate covered scenarios.

claude -p "Review this diff for security and correctness issues" \
  --output-format json \
  --json-schema review-findings.schema.json

Hands-On Exercise

1. Set up a repo with project CLAUDE.md + two .claude/rules/ files (paths: ["src/api/**/*"], paths: ["**/*.test.*"]); verify conditional loading with /memory.
2. Create a project skill with context: fork and allowed-tools; confirm its verbose output stays out of the main session.
3. Run the same refactor once in plan mode and once direct; note where plan mode caught a dependency you'd have broken.
4. Wire claude -p with --output-format json into a CI job and parse the findings.

Decision Cheat Sheet: Where Does Configuration Live?

Domain 3 questions are mostly "where does this belong?" in disguise. This table resolves nearly all of them:

Read the scenario for two signals: who needs it (one person → user scope; the team → project scope) and when it applies (always → CLAUDE.md; on matching files → rules; on demand → commands/skills).

Worked Exam Question

Your team's monorepo has a 1,900-line root CLAUDE.md mixing React conventions, Terraform standards, API guidelines, and deployment procedures. Developers report Claude inconsistently applies the right section, and token usage is high in every session. What is the best restructuring?

• A. Split the content into focused files under .claude/rules/ with glob-scoped frontmatter (e.g., paths: ["terraform/**/*"]) so each rule loads only when relevant files are edited.
• B. Reorder the monolith so the most-used conventions appear first, exploiting position effects.
• C. Convert the whole file into a skill that developers invoke at session start.
• D. Duplicate the full CLAUDE.md into each package directory so context is always nearby.

Answer: A. The problem is two-fold — inconsistent application (Claude must infer which section applies) and constant token cost (everything loads always). Path-scoped rules fix both mechanically: matching files trigger their rules, nothing else loads. Option B still loads 1,900 lines everywhere; C makes universal standards opt-in, guaranteeing drift; D multiplies the token problem by the package count.

Key Takeaways for the Exam

• User config isn't shared; project config is; /memory diagnoses loading issues.
• Path-scoped glob rules beat directory CLAUDE.md for scattered file types.
• context: fork isolates, allowed-tools restricts, argument-hint prompts.
• Plan mode for stated complexity; direct for well-scoped fixes; never "wait and see" when complexity is explicit.
• CI: -p, --output-format json, --json-schema, CLAUDE.md as context, independent instance for review.

Next: Lesson 5 — Prompt Engineering & Structured Output

Frequently Asked Questions

Where should team-wide slash commands be stored?

In .claude/commands/ inside the project repository. Commands there are version-controlled, so every developer receives them automatically on clone or pull — no onboarding steps, no drift between machines. The ~/.claude/commands/ directory serves the opposite need: personal commands that should not ship to teammates. Exam distractors here include putting command definitions inside CLAUDE.md (which holds instructions, not commands) and a "commands" array in a config JSON, which does not exist.

When should I use plan mode instead of direct execution?

Use plan mode when the scenario states architectural complexity upfront: changes spanning dozens of files, multiple valid implementation approaches, service boundary decisions, or large migrations. Plan mode buys safe exploration and design before any file changes, preventing expensive rework. Use direct execution for well-scoped changes — a single-file fix with a clear stack trace. The recurring trap answer is "start direct and switch to plan mode if it gets complex": when complexity is already stated in the requirements, deferring the decision just schedules the rework.

Which flags run Claude Code in a CI pipeline?

The -p (or --print) flag runs Claude Code non-interactively — it processes the prompt, writes the result to stdout, and exits, which is what stops pipeline jobs from hanging on interactive input. Pair it with --output-format json and --json-schema when downstream automation must parse the findings, for example posting review comments inline on a pull request. CLAUDE_HEADLESS environment variables and a --batch flag appear in exam options but are invented features.