Domain 3: Claude Code Configuration & Workflows

Claude Certified Architect (Foundations) — 20% of Exam

Domain 3 Overview

Weight: 20% of total exam score.

Key insight: This is the most configuration-heavy domain. You either know where the files go and what the options do, or you do not. Reasoning alone will not save you here.

3.1 CLAUDE.md Hierarchy

The Three Levels

LevelLocationVersion-ControlledShared via GitScope
User~/.claude/CLAUDE.mdNoNoOnly you
Project.claude/CLAUDE.md or root CLAUDE.mdYesYesEveryone on the project
DirectorySubdirectory CLAUDE.md filesYesYesWhen working in that directory

The Exam's Favourite Trap

A new team member is not receiving instructions.

Root cause: Instructions are in user-level config (~/.claude/CLAUDE.md) instead of project-level (.claude/CLAUDE.md).

New team members cloning the repo do NOT get user-level instructions.

Modular Organisation

@import syntax: Reference external files from CLAUDE.md:

<!-- .claude/CLAUDE.md -->
@import ../docs/api-conventions.md
@import ../docs/testing-standards.md

.claude/rules/ directory: Topic-specific rule files as an alternative to one massive file:

.claude/rules/
  testing.md
  api-conventions.md
  deployment.md

Debugging Tool

/memory command verifies which memory files are loaded. Use when behaviour is inconsistent across sessions.

Practice Scenario

Scenario: Developer A's Claude Code follows API naming conventions perfectly. Developer B (joined last week) gets inconsistent naming. Same repo.

Options:

A) Developer B needs to update their Claude Code version
B) The naming conventions are in user-level config, not project-level
C) Developer B's local model cache is stale
D) The CLAUDE.md file has a syntax error

Correct: B. User-level config (~/.claude/CLAUDE.md) is not shared via git. Move instructions to .claude/CLAUDE.md for team-wide application.

Check Questions

1. Where should team-wide coding standards live?

Answer: Project-level: .claude/CLAUDE.md or root CLAUDE.md (version-controlled, shared via git).

2. A developer's personal preferences should go where?

Answer: User-level: ~/.claude/CLAUDE.md (not version-controlled, not shared).

3.2 Custom Slash Commands and Skills

Directory Structure

LocationScopeShared
.claude/commands/ProjectYes (version-controlled)
~/.claude/commands/PersonalNo
.claude/skills/ with SKILL.mdProjectYes
~/.claude/skills/PersonalNo

Skill Frontmatter Options

---
name: codebase-analysis
description: Analyse codebase structure and patterns
context: fork           # Runs in isolated sub-agent context
allowed-tools:          # Restricts available tools
  - Read
  - Grep
  - Glob
argument-hint: "path to analyse"  # Prompts for parameters
---
OptionPurpose
context: forkRuns in isolated sub-agent. Verbose output stays contained. Main conversation stays clean.
allowed-toolsPrevents destructive actions during skill execution
argument-hintPrompts developer for required parameters when invoked without arguments

Key Distinction

TypeLoadingUse For
SkillsOn-demand (invoked when needed)Task-specific workflows
CLAUDE.mdAlways loaded automaticallyUniversal standards

Do not put task-specific procedures in CLAUDE.md. Do not put universal standards in skills.

Personal Customisation

Create personal variants in ~/.claude/skills/ with different names. Avoids affecting teammates.

Practice Scenario

Scenario: Team wants /review available to everyone. Developer wants personal /brainstorm that produces verbose output.

/review: .claude/commands/review.md (project-scoped, shared)

/brainstorm: ~/.claude/skills/brainstorm/SKILL.md with context: fork (personal, verbose output contained)

3.3 Path-Specific Rules

Configuration

# .claude/rules/testing.md
---
paths: ["**/*.test.tsx", "**/*.spec.ts"]
---
All test files must:
- Use describe/it blocks
- Include at least one assertion per test
- Mock external services, never hit real endpoints in unit tests

Key Advantage Over Directory-Level CLAUDE.md

MechanismMatchesBest For
Path-specific rules (glob patterns)Files across the ENTIRE codebaseTest conventions for **/*.test.tsx spread everywhere
Directory-level CLAUDE.mdFiles in ONE directoryRules specific to one directory

Token Efficiency

Path-scoped rules load ONLY when editing matching files. Reduces irrelevant context compared to always-loaded instructions.

Practice Scenario

Scenario: Test files co-located with source files throughout 50+ directories. Team wants all tests to follow the same conventions.

Options:

A) Path-specific rules with paths: ["**/*.test.tsx"] glob
B) CLAUDE.md in every directory (50+ copies)
C) Single root CLAUDE.md (always loaded, wastes tokens when not testing)
D) Skills (wrong mechanism — these are universal standards, not on-demand workflows)

Correct: A. Glob pattern matches test files everywhere. Loads only when editing test files. No duplication.

3.4 Plan Mode vs Direct Execution

Decision Framework

Use Plan Mode WhenUse Direct Execution When
Complex tasks, large-scale changesWell-understood, limited scope
Multiple valid approaches existCorrect approach is already known
Architectural decisions requiredSingle-file bug fix with clear stack trace
Multi-file modifications (45+ files)Adding a date validation conditional
Need to explore before changing

Explore Subagent

Combination Pattern

Phase 1: Plan mode → investigate and design
Phase 2: Direct execution → implement the planned approach

This hybrid is common in practice and tested on the exam.

Practice Scenario

Classify each task:

TaskModeReasoning
Restructure monolith into microservicesPlanComplex, multiple valid approaches, architectural decisions
Fix null pointer in a single functionDirectClear scope, clear stack trace, known fix
Migrate logging library across 30 filesPlanMulti-file, need to identify all usage patterns first

3.5 Iterative Refinement

Technique Hierarchy

TechniqueWhen to UseEffectiveness
Concrete input/output examples (2-3)Model interprets prose inconsistentlyHighest — beats prose every time
Test-driven iterationWrite tests first, share failuresHigh — objective success criteria
Interview patternUnfamiliar domainHigh — surfaces missed considerations

Batch vs Sequential Feedback

StrategyWhen
Single messageFixes interact with each other (changing one affects others)
Sequential iterationIssues are independent (fixing one does not affect others)

Practice Scenario

Scenario: A developer describes a code transformation in prose. Claude Code interprets it differently each time.

First technique to try: Concrete input/output examples. Show 2-3 before/after examples. The model generalises from examples more reliably than from prose descriptions.

3.6 CI/CD Integration

The -p Flag

# WRONG: Hangs waiting for interactive input
claude "Analyse this PR"

# CORRECT: Non-interactive mode
claude -p "Analyse this PR"

This is Q10 in the sample set. Memorise it.

Structured CI Output

claude -p --output-format json --json-schema schema.json "Review this PR"

Produces machine-parseable findings. Automated systems can post as inline PR comments.

Session Context Isolation

The same Claude session that generated code is LESS effective at reviewing its own changes.

It retains reasoning context that makes it less likely to question its decisions. Use an independent review instance for code review.

Incremental Review Context

When re-running reviews after new commits:

CLAUDE.md for CI

Document testing standards, valuable test criteria, and available fixtures. CI-invoked Claude Code uses this to generate high-quality tests. Without it, test generation produces low-value boilerplate.

Practice Scenario

Scenario: CI pipeline script claude "Analyze this PR" hangs indefinitely. Logs show Claude waiting for input.

Options:

A) Increase the CI timeout
B) Add the -p flag for non-interactive mode
C) Pipe input from /dev/null
D) Run in a Docker container

Correct: B. The -p flag runs Claude Code in print (non-interactive) mode.

Domain 3 Practice Exam

Q1. Developer A follows team conventions. Developer B (new hire) does not. Both use the same repo. Where are the instructions most likely stored?

A) .claude/CLAUDE.md
B) ~/.claude/CLAUDE.md
C) .claude/rules/
D) .claude/commands/

B — User-level config is not shared via git. New team members don't get it.

Q2. A team wants all developers to see the same CLAUDE.md instructions. Where should the file live?

A) ~/.claude/CLAUDE.md
B) .claude/CLAUDE.md (project-level)
C) /etc/claude/CLAUDE.md
D) Each developer's home directory

B — Project-level .claude/CLAUDE.md is version-controlled and shared.

Q3. A team wants a /deploy command available to all developers and a personal /shortcut command for one developer. Where does each go?

A) Both in .claude/commands/
B) /deploy in .claude/commands/, /shortcut in ~/.claude/commands/
C) Both in ~/.claude/commands/
D) /deploy in .claude/skills/, /shortcut in .claude/commands/

B — Shared commands in project .claude/commands/, personal in ~/.claude/commands/.

Q4. Test files are spread across 40 directories. The team wants consistent test conventions applied. What is the best mechanism?

A) CLAUDE.md in each of the 40 directories
B) Path-specific rules with paths: ["**/*.test.tsx"]
C) A single root CLAUDE.md with all test rules
D) A custom skill that enforces test conventions

B — Path-specific rules with glob patterns match files across the entire codebase.

Q5. A task requires migrating from one ORM to another across 60+ files. Should you use plan mode or direct execution?

A) Direct execution — just find and replace
B) Plan mode — need to identify all usage patterns, evaluate migration strategy, then implement
C) Direct execution with a larger context window
D) Plan mode but skip the investigation phase

B — Multi-file migration requires investigation, pattern identification, and strategy before implementation.

Q6. A developer is restructuring 3 lines in a single function to fix a clear bug. Which mode?

A) Plan mode to evaluate alternatives
B) Direct execution
C) Plan mode with Explore subagent
D) Start a new session with summary injection

B — Clear bug, small scope, known fix = direct execution.

Q7. Claude Code interprets a transformation request differently each time despite detailed prose instructions. What technique should be tried first?

A) Add more detailed prose instructions
B) Provide 2-3 concrete input/output examples
C) Use the interview pattern
D) Switch to test-driven iteration

B — Concrete examples beat prose descriptions for consistency.

Q8. A CI pipeline running claude "Review this code" hangs. What is the fix?

A) Increase memory allocation
B) Add the -p flag for non-interactive mode
C) Run with --verbose to see the issue
D) Add a timeout wrapper

B — The -p flag enables non-interactive (print) mode for CI.

Build Exercise

Configure Claude Code for a Team Development Workflow

  1. Create a project-level CLAUDE.md with universal coding standards and testing conventions. Verify that instructions placed at the project level are consistently applied across all team members.
  2. Create .claude/rules/ files with YAML frontmatter glob patterns for different code areas (e.g., paths: ["src/api/**/*"] for API conventions, paths: ["**/*.test.*"] for testing conventions). Test that rules load only when editing matching files.
  3. Create a project-scoped skill in .claude/skills/ with context: fork and allowed-tools restrictions. Verify the skill runs in isolation without polluting the main conversation context.
  4. Configure an MCP server in .mcp.json with environment variable expansion for credentials. Add a personal experimental MCP server in ~/.claude.json and verify both are available simultaneously.
  5. Test plan mode versus direct execution on tasks of varying complexity: a single-file bug fix, a multi-file library migration, and a new feature with multiple valid implementation approaches. Observe when plan mode provides value.

Domains reinforced: Domain 3 (Claude Code Configuration & Workflows), Domain 2 (Tool Design & MCP Integration)

→ Try related coding exercises

Quick Reference Card

CLAUDE.md HIERARCHY:
  ~/.claude/CLAUDE.md     → personal, NOT shared
  .claude/CLAUDE.md       → project, shared via git
  subdirectory/CLAUDE.md  → directory-scoped

  New hire missing instructions? → Probably in user-level config

PATH-SPECIFIC RULES:
  .claude/rules/testing.md with paths: ["**/*.test.tsx"]
  Loads only when editing matching files
  Glob patterns match across entire codebase

COMMANDS & SKILLS:
  .claude/commands/   → project (shared)
  ~/.claude/commands/ → personal
  Skills: context: fork, allowed-tools, argument-hint
  Skills = on-demand | CLAUDE.md = always-loaded

PLAN MODE:
  Complex/multi-file/architectural → Plan mode
  Simple/clear/single-file → Direct execution
  Common: Plan first, then direct execution

ITERATIVE REFINEMENT:
  Input/output examples > prose descriptions
  Batch feedback when fixes interact
  Sequential when issues are independent

CI/CD:
  -p flag = non-interactive mode (MEMORISE THIS)
  --output-format json for structured output
  Independent review instance (not same session)
  Include prior findings to prevent duplicate comments