Domain 3: Claude Code Configuration & Workflows (20%)

Weight: 20% of scored content

This domain covers how to configure Claude Code for team development workflows: CLAUDE.md file hierarchy, custom slash commands and skills, path-specific rules, plan mode vs. direct execution, iterative refinement techniques, and CI/CD integration.

Task Statement 3.1: Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization

The CLAUDE.md Hierarchy

CLAUDE.md files provide project context and instructions to Claude Code. They're loaded based on a hierarchy:

Key Behaviors

• User-level settings apply only to that user and are not shared via version control — use for personal preferences
• Project-level is the main configuration — coding standards, testing conventions, architectural guidelines
• Directory-level files provide additional context when Claude is working in that specific directory

@import for Modular Configuration

Use @import to reference external files, keeping CLAUDE.md modular rather than monolithic:

# CLAUDE.md
@import .claude/rules/testing.md
@import .claude/rules/api-conventions.md
@import .claude/rules/deployment.md

Each package's CLAUDE.md can selectively import only the standards files relevant to its domain, based on the maintainer's knowledge.

.claude/rules/ Directory

An alternative to subdirectory CLAUDE.md files. Rule files in .claude/rules/ can use YAML frontmatter with glob patterns for conditional activation (see Task Statement 3.3).

Splitting Large Configurations

Instead of one massive CLAUDE.md, split into focused topic-specific files: - .claude/rules/testing.md — test conventions and fixtures - .claude/rules/api-conventions.md — API design standards - .claude/rules/deployment.md — deployment procedures

Diagnosing Configuration Issues

If a new team member isn't receiving certain instructions, check whether those instructions are in ~/.claude/CLAUDE.md (user-level, personal) rather than .claude/CLAUDE.md (project-level, shared). User-level settings don't propagate to other team members.

Use the /memory command to verify which memory files are loaded and diagnose inconsistent behavior across sessions.

Connection to Other Domains

• MCP server configuration → see Tool Design & MCP Integration
• Path-specific rules → see Task Statement 3.3

Task Statement 3.2: Create and configure custom slash commands and skills

Slash Commands

Project-scoped commands are automatically available to all developers who clone or pull the repository.

Skills

Skills live in .claude/skills/ with a SKILL.md file. They support frontmatter configuration:

---
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: "Provide the file path to analyze"
---

# Code Analysis Skill

Analyze the provided file for potential issues...

Key Frontmatter Options

When to Use Skills vs. CLAUDE.md

Personal Skill Customization

Create personal variants in ~/.claude/skills/ with different names to customize behavior without affecting teammates. This lets you experiment with alternative approaches without team-wide impact.

Connection to Other Domains

• context: fork relates to session isolation → see Agentic Architecture & Orchestration
• Iterative refinement → see Task Statement 3.5

Task Statement 3.3: Apply path-specific rules for conditional convention loading

The Problem

You have one codebase with multiple convention zones: React components use functional style with hooks, API handlers use async/await with specific error handling, test files follow a universal pattern regardless of location. Directory-level CLAUDE.md files can't handle conventions that span many directories (like test files spread everywhere).

.claude/rules/ with Glob Patterns

Rule files can include YAML frontmatter with paths fields containing glob patterns:

---
paths:
  - "src/api/**/*"
---

# API Conventions
- All handlers must use async/await
- Wrap database calls in try/catch with specific error types
- Return standardized error response objects

---
paths:
  - "**/*.test.tsx"
  - "**/*.test.ts"
---

# Testing Conventions
- Use React Testing Library for component tests
- Mock external API calls, never make real requests
- Follow AAA pattern: Arrange, Act, Assert

How Path-Scoped Rules Work

Rules load only when editing matching files. This reduces irrelevant context and token usage — API conventions don't load when you're editing React components, and vice versa.

Why Glob Patterns Beat Directory-Level CLAUDE.md

For conventions that apply by file type regardless of directory location (e.g., all test files, all config files), glob-pattern rules are the right choice. Directory-level CLAUDE.md files are bound to a single directory and can't handle files spread throughout the codebase.

Exam tip: If a question describes conventions that apply to a file type (like test files) scattered across many directories, the answer is .claude/rules/ with glob patterns — not subdirectory CLAUDE.md files.

Connection to Other Domains

• CLAUDE.md hierarchy → see Task Statement 3.1
• CI/CD configuration → see Task Statement 3.6

Task Statement 3.4: Determine when to use plan mode vs direct execution

Plan Mode

Designed for complex tasks involving: - Large-scale changes across many files - Multiple valid approaches requiring architectural decisions - Multi-file modifications with dependency considerations

Plan mode enables safe codebase exploration and design before committing to changes, preventing costly rework when dependencies are discovered late.

Direct Execution

Appropriate for simple, well-scoped changes: - Single-file bug fix with a clear stack trace - Adding a date validation conditional - Straightforward refactoring with known patterns

The Explore Subagent

Use the Explore subagent to isolate verbose discovery output and return summaries to the main conversation. This preserves main conversation context during multi-phase tasks.

Combining Both Approaches

For complex projects, use plan mode for investigation and direct execution for implementation: 1. Plan mode: Explore the codebase, map dependencies, design the approach 2. Direct execution: Execute the planned approach with confidence

Decision Criteria

Connection to Other Domains

• Task decomposition strategies → see Agentic Architecture & Orchestration
• Context management during exploration → see Context Management & Reliability

Task Statement 3.5: Apply iterative refinement techniques for progressive improvement

Input/Output Examples Beat Prose Descriptions

When natural language descriptions produce inconsistent results, concrete input/output examples are the most effective way to communicate expected transformations:

Input: "Meeting at 3pm EST on 1/15"
Expected output: {"time": "15:00", "timezone": "EST", "date": "2025-01-15"}

Input: "Let's sync tomorrow morning"
Expected output: {"time": null, "timezone": null, "date": "relative:tomorrow"}

Test-Driven Iteration

1. Write test suites covering expected behavior, edge cases, and performance requirements first
2. Share test failures with Claude to guide progressive improvement
3. Iterate until tests pass

This is more effective than describing what you want — test failures give Claude precise, actionable feedback.

The Interview Pattern

Have Claude ask questions to surface considerations the developer may not have anticipated before implementing. This works especially well in unfamiliar domains:

Developer: "Add caching to our API endpoints"
Claude: "Before implementing, I have some questions:
- What's your cache invalidation strategy?
- Should cache be per-user or shared?
- What failure mode do you want when cache is unavailable?
- Are there endpoints that should never be cached?"

Sequential vs. Parallel Issue Resolution

Connection to Other Domains

• Few-shot prompting → see Prompt Engineering & Structured Output
• Validation-retry loops → see Prompt Engineering & Structured Output

Task Statement 3.6: Integrate Claude Code into CI/CD pipelines

Running Claude Code in CI

The -p (or --print) flag runs Claude Code in non-interactive mode — essential for automated pipelines. Without it, Claude Code waits for interactive input and hangs indefinitely.

# Correct: non-interactive mode for CI
claude -p "Analyze this pull request for security issues"

# Will hang: no -p flag means it waits for input
claude "Analyze this pull request for security issues"

Structured Output for CI

Use --output-format json with --json-schema to produce machine-parseable structured output for automated posting as inline PR comments:

claude -p "Review this PR" \
  --output-format json \
  --json-schema '{"type": "object", "properties": {"findings": {"type": "array"}}}'

Session Context Isolation

The same Claude session that generated code is less effective at reviewing it — the model retains its reasoning context from generation, making it less likely to question its own decisions. Use an independent review instance for higher-quality feedback.

Avoiding Duplicate Comments

When re-running reviews after new commits, include prior review findings in context and instruct Claude to report only new or still-unaddressed issues. This prevents duplicate comments that erode developer trust.

Test Generation Best Practices

• Provide existing test files in context so Claude doesn't suggest scenarios already covered
• Document testing standards, valuable test criteria, and available fixtures in CLAUDE.md
• This improves test generation quality and reduces low-value test output

CLAUDE.md for CI Context

CLAUDE.md serves as the mechanism for providing project context (testing standards, fixture conventions, review criteria) to CI-invoked Claude Code instances. The CI runner reads the same CLAUDE.md that developers use.

Connection to Other Domains

• Structured output via tool_use → see Prompt Engineering & Structured Output
• Multi-pass review architectures → see Prompt Engineering & Structured Output