Claude Code Configuration & Workflows — Complete Lesson

The Core Concept

Claude Code reads CLAUDE.md files from multiple locations and merges them into a single instruction set. The level at which you place a file determines who receives it — and whether it travels with the codebase via version control.

Configuration Hierarchy

my-project/
├── CLAUDE.md                   # ← project-level, committed to git
├── .claude/
│   ├── CLAUDE.md               # ← alternative project-level location
│   ├── rules/
│   │   ├── testing.md          # ← topic-specific rules
│   │   ├── api-conventions.md
│   │   └── deployment.md
│   ├── commands/               # ← project-scoped slash commands
│   └── skills/                 # ← project-scoped skills
└── src/
    └── payments/
        └── CLAUDE.md           # ← directory-level, payments only

~/.claude/CLAUDE.md             # ← user-level, NEVER committed

Modular Organisation with @import

Large CLAUDE.md files become hard to maintain. The @import syntax lets you split into focused topic files and include only what's relevant per package.

# Project Root CLAUDE.md

## Universal Standards
All code must be TypeScript strict mode.
All API endpoints require input validation.

## Imported Standards
@import .claude/rules/testing.md
@import .claude/rules/api-conventions.md

---
# src/payments/CLAUDE.md  (directory-level, payments team)

## Payment Service Standards
Always use idempotency keys for payment calls.
Never log raw card numbers or CVV values.

## Payment-Specific Imports
@import ../../.claude/rules/pci-compliance.md

• Use .claude/rules/ directory for topic-specific files as an alternative to a single large CLAUDE.md
• Use @import to selectively include relevant standards per package — a payments package imports PCI rules, a frontend package imports UI conventions
• Diagnose "teammate not receiving instructions" by checking whether the file is at user-level vs project-level
• Use /memory command to verify exactly which CLAUDE.md files are loaded in the current session

Exam Traps for Task 3.1

🔨 Implementation Task

Exam Simulation — Task 3.1

The Core Concept

Custom slash commands are Markdown templates stored as files — they can be shared team-wide or kept personal. Skills are more powerful: they run in their own context and support frontmatter configuration that controls isolation, tool access, and how they prompt for arguments.

Slash Commands: Scoping

Skills: Frontmatter Configuration

Skills use YAML frontmatter at the top of the SKILL.md file. Four frontmatter keys the exam tests:

---
name: architecture-review
description: Reviews system architecture and returns a focused summary
context: fork          # ← runs in isolated subagent context
allowed-tools:           # ← restricts which tools can run
  - read_file
  - search_code
  - Grep
argument-hint: "path/to/module"  # ← prompts for arg if missing
---

Review the architecture of the module at {{args}}.

Analyse:
1. Dependency structure and circular imports
2. Public API surface — is it minimal?
3. Separation of concerns violations

Return a concise summary with top 3 findings.

Exam Traps for Task 3.2

🔨 Implementation Task

Exam Simulation — Task 3.2

The Core Concept

Files in .claude/rules/ support YAML frontmatter with a paths field. When a paths field is present, the rules load only when Claude is editing files matching those glob patterns. This conditional loading reduces irrelevant context and token usage.

Glob Patterns and Rule Files

---
paths:
  - "**/*.test.tsx"       # all test files, any directory
  - "**/*.spec.ts"        # all spec files, any directory
  - "tests/**/*"          # anything in a tests/ directory
---

## Testing Standards
Always use React Testing Library, not Enzyme.
Test user behaviour, not implementation details.
Mock external API calls using msw.
Each test file must have at least one edge-case test.
Snapshot tests require an inline comment explaining intent.

---
paths:
  - "terraform/**/*"     # all terraform files
  - "**/*.tf"             # any .tf file anywhere
---

## Terraform Standards
All resources require name, environment, and team tags.
Never hardcode AWS account IDs — use data sources.
Remote state must use S3 backend with DynamoDB lock table.

• Use path-specific rules for conventions that apply to a file type across directories (test files, migration files, infrastructure files)
• Use directory-level CLAUDE.md for conventions that apply to a domain or service (payments service, admin panel) regardless of file type
• Path rules reduce token usage by loading only when editing matching files — infrastructure rules don't load during frontend work

Exam Traps for Task 3.3

🔨 Implementation Task

Exam Simulation — Task 3.3

The Core Concept

Plan mode lets Claude explore a codebase and propose an approach before making any changes. It prevents costly rework on complex tasks where choosing the wrong implementation approach means undoing a lot of work. Direct execution is appropriate when the task is well-scoped, the correct approach is clear, and the change is small.

Decision Framework

• Use plan mode for exploration, then switch to direct execution once the approach is confirmed — the combination is more powerful than either alone
• Plan mode prevents "costly rework" — the exam phrase for situations where the wrong initial approach would require undoing many changes
• Direct execution is fine for well-understood, single-file, clearly-scoped tasks — plan mode would add overhead without benefit

The Explore Subagent

During a multi-phase task, the Explore subagent isolates verbose discovery output. Rather than flooding the main session with file-by-file analysis, the Explore subagent does the discovery and returns a structured summary. This preserves context window space for the implementation phase.

Exam Traps for Task 3.4

🔨 Implementation Task

Exam Simulation — Task 3.4

The Core Concept

When Claude's output is inconsistent with what you want, the problem is often underspecified expectations. Iterative refinement is about progressive specification: start with what you have, identify exactly where the gap is, and communicate the correction with enough precision that Claude can generalise it to novel cases.

Refinement Techniques

# Instead of: "Format the dates consistently"
# → Too vague. Claude will pick a format arbitrarily.

# Do this: provide concrete input/output pairs
"""
The transformation should work like this:

Input:  { "created": "2024-01-15T14:30:00Z" }
Output: { "created": "Jan 15, 2024 at 2:30 PM UTC" }

Input:  { "created": 1705329000 }
Output: { "created": "Jan 15, 2024 at 2:30 PM UTC" }

Input:  { "created": null }
Output: { "created": "Unknown" }

Apply this transformation to all date fields in the response.
"""

Exam Traps for Task 3.5

🔨 Implementation Task

Exam Simulation — Task 3.5

The Core Concept

Claude Code is designed for interactive use by default — it waits for user input when it needs clarification. In CI pipelines, there is no user. Without the correct flag, the pipeline hangs indefinitely waiting for input that will never come.

CI/CD CLI Flags

# ✓ Non-interactive: process and exit
claude -p "Analyze this pull request for security issues"

# ✓ Structured JSON output for automated parsing
claude -p "Review for security issues" \
  --output-format json \
  --json-schema review-schema.json

# Result: machine-parseable JSON for inline PR comments
# {
#   "findings": [
#     {"file": "auth.ts", "line": 42, "severity": "high", "message": "..."},
#   ]
# }

# ✗ WRONG — hangs waiting for interactive input
claude "Analyze this pull request for security issues"

Batch API vs Real-Time: The Critical Trade-off

The Message Batches API offers 50% cost savings but with up to 24-hour processing time and no guaranteed latency SLA. The exam tests whether you know which workflows can tolerate async processing and which cannot.

Exam Traps for Task 3.6

🔨 Implementation Task

Exam Simulation — Task 3.6