Before You Begin

Executive Summary

Configuration Knowledge — Cannot Be Reasoned From First Principles

CLAUDE.md hierarchy: user-level (personal, not shared), project-level (version-controlled, shared with team), directory-level (scoped to one directory).

Exam trap: a team member not receiving instructions because they live in user-level config.

Path-specific rules in .claude/rules/ with YAML frontmatter apply glob patterns across the entire codebase. Directory-level CLAUDE.md cannot do this — it is directory-bound.

-p flag: mandatory for all CI/CD pipelines. Without it, the job hangs indefinitely.

TASK STATEMENT 3.1

CLAUDE.md Hierarchy

LevelLocationVersion-Controlled?Shared with Team?
User-level~/.claude/CLAUDE.mdNoNo — personal only
Project-level.claude/CLAUDE.md or root CLAUDE.mdYesYes — team-wide standards live here
Directory-levelSubdirectory CLAUDE.md filesYesApplies only in that directory

The Exam's Favourite Trap

A new team member is not receiving instructions that Developer A follows perfectly. Both work on the same repository. Root cause: the instructions are in Developer A's user-level config, not in the project-level config. The new developer's clone does not include them. Fix: move the instructions to .claude/CLAUDE.md and commit.

Modular Organisation

  • Use @import syntax to reference external files from CLAUDE.md.
  • Use the .claude/rules/ directory for topic-specific rule files (testing.md, api-conventions.md, deployment.md).
  • Use the /memory command to verify which memory files are currently loaded — the primary debugging tool for inconsistent behaviour across sessions.

TASK STATEMENT 3.2

Custom Slash Commands and Skills

LocationScopeUse For
.claude/commands/Project — shared via version controlTeam-wide slash commands everyone receives
~/.claude/commands/Personal — not sharedPersonal workflow commands
.claude/skills/Project — SKILL.md with frontmatterOn-demand task-specific workflows

Skill Frontmatter Options

# .claude/skills/review/SKILL.md --- context: fork # isolates verbose output from main conversation allowed-tools: # prevents destructive actions - Read - Grep - Glob argument-hint: "Path to review (e.g. src/auth/)" --- Perform a thorough code review of the specified path...

Skills vs CLAUDE.md — Know the Difference

Skills = on-demand, task-specific workflows. Invoked when needed.

CLAUDE.md = always-loaded, universal standards. Applied automatically to every interaction.

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

TASK STATEMENT 3.3

Path-Specific Rules

# .claude/rules/testing.md --- paths: ["**/*.test.tsx", "**/*.spec.ts"] --- All test files must follow these conventions: - Use describe/it blocks with descriptive names - Mock external dependencies at the module level - Assert on behaviour, not implementation details

Key Advantage Over Directory-Level CLAUDE.md

  • Glob patterns match files spread across the entire codebase — **/*.test.tsx catches every test file regardless of directory.
  • Directory-level CLAUDE.md only applies to files in that one directory — useless for conventions that span 50+ directories.
  • Path-scoped rules load only when editing matching files, reducing irrelevant context and token usage.

TASK STATEMENT 3.4

Plan Mode vs Direct Execution

ModeUse WhenExamples
Plan ModeComplex, large-scale, or architectural tasks where multiple valid approaches exist.Restructure monolith into microservices. Migrate logging library across 30 files.
Direct ExecutionWell-understood changes with clear, limited scope.Fix null pointer exception in single function. Add a date validation conditional.

A common and effective hybrid pattern: use plan mode for investigation and design, then switch to direct execution for implementation once the approach is confirmed.

The Explore subagent isolates verbose discovery output from the main conversation and returns summaries, preventing context window exhaustion during multi-phase tasks.

TASK STATEMENT 3.5

Iterative Refinement

Technique Hierarchy

  1. Concrete input/output examples (2 to 3 before/after pairs) — beat prose descriptions every time. The model generalises from examples more reliably than from abstract instructions.
  2. Test-driven iteration — write tests first, share failures to guide improvement.
  3. Interview pattern — have Claude ask clarifying questions before implementing.

Batching vs Sequencing Feedback

Single message: when fixes interact with each other — changing one affects others.

Sequential iteration: when issues are independent — fixing one does not affect others.

TASK STATEMENT 3.6

CI/CD Integration

The -p Flag — Memorise This

The -p flag runs Claude Code in non-interactive (print) mode. Without it, the CI job hangs indefinitely waiting for interactive input. This is the most commonly tested fact in this task statement.

# CI pipeline — correct usage claude -p "Analyse this PR for bugs and security issues" \ --output-format json \ --json-schema ./schemas/review-output.json # This hangs indefinitely — missing -p flag claude "Analyse this PR for bugs and security issues"

Session Context Isolation for Review

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 own decisions. Always use an independent review instance for code review.

Incremental Review Context

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 in the review system.

Hands-On Build Exercise

Build: Complete Claude Code Configuration

  • Set up a project with CLAUDE.md hierarchy — project-level and directory-level.
  • Create a .claude/rules/ directory with glob patterns for test files and API convention files.
  • Create a custom skill with context: fork for verbose codebase analysis.
  • Write a CI script that uses the -p flag with JSON output and a json-schema.
  • Verify that a new team member cloning the repository receives all project-level instructions automatically.
  • Test plan mode on a multi-file refactor and direct execution on a single bug fix.