Chapter 5: Claude Code — Configuration and Workflows

Documentation: Claude Code | Memory / CLAUDE.md | Skills | MCP | Hooks | Sub-agents | GitHub Actions | Headless

5.1 The CLAUDE.md Hierarchy

CLAUDE.md is the instruction file(s) for Claude Code. There is a three-level hierarchy:

1. User-level: ~/.claude/CLAUDE.md
   - Applies only to that user
   - NOT shared via VCS
   - Personal preferences and working style

2. Project-level: .claude/CLAUDE.md or a root CLAUDE.md
   - Applies to all project contributors
   - Managed via VCS
   - Coding standards, testing standards, architectural decisions

3. Directory-level: CLAUDE.md in subdirectories
   - Applies when working with files in that directory
   - Conventions specific to that part of the codebase

Common mistake: a new team member does not receive project instructions because they were placed in ~/.claude/CLAUDE.md (user-level) instead of .claude/CLAUDE.md (project-level).

5.2 @path Syntax (File Imports)

CLAUDE.md can reference external files using @path, making configuration modular:

# Project CLAUDE.md

Coding standards are described in @./standards/coding-style.md
Test requirements are in @./standards/testing-requirements.md
Project overview is in @README.md and dependencies are in @package.json

Rules for @path:

• Use @ immediately before the file path (no space)
• Relative and absolute paths are supported
• Relative paths are resolved relative to the file that contains the import
• Maximum import nesting depth is 5

This avoids duplication and lets each package include only relevant standards.

5.3 The .claude/rules/ Directory

.claude/rules/ is an alternative to a monolithic CLAUDE.md, used to organize rules by topic:

.claude/rules/
  testing.md          -- testing conventions
  api-conventions.md  -- API conventions
  deployment.md       -- deployment rules
  react-patterns.md   -- React patterns

Key feature: YAML frontmatter with paths for conditional loading:

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

For API files, use async/await with explicit error handling.
Each endpoint must return a standard response wrapper.

---
paths: ["**/*.test.tsx", "**/*.test.ts"]
---

Tests must use describe/it blocks.
Use data factories instead of hardcoding.
Do not mock the database—use a test database.

How it works:

• A rule is loaded only when Claude Code edits a file matching the paths pattern
• This saves context and tokens—irrelevant rules are not loaded
• Glob patterns let you apply conventions by file type regardless of location (ideal for tests scattered across the codebase)

When to use .claude/rules/ with paths vs directory-level CLAUDE.md:

• .claude/rules/ with paths — when conventions apply to files spread across many directories (tests, migrations)
• Directory-level CLAUDE.md — when conventions are tied to a specific directory and are not needed elsewhere

5.4 Custom Slash Commands and Skills

Note: in the current Claude Code version, custom commands (.claude/commands/) are unified with skills (.claude/skills/). Both formats create /name commands. The exam guide references .claude/commands/—that format is still supported.

Slash commands are reusable prompt templates invoked via /name:

.claude/commands/ format (legacy, supported):

.claude/commands/
  review.md        -- /review -- standard code review
  test-gen.md      -- /test-gen -- test generation

.claude/skills/ format (current):

.claude/skills/
  review/SKILL.md  -- /review -- with frontmatter configuration
  test-gen/SKILL.md

Project commands (.claude/commands/ or .claude/skills/):

• Stored in VCS and available to everyone when cloning the repo
• Ensure consistent workflows across the team

User commands (~/.claude/commands/ or ~/.claude/skills/):

• Personal commands not shared via VCS
• For individual workflows

5.5 Skills — .claude/skills/

Skills are advanced commands configured via SKILL.md frontmatter:

---
context: fork
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: "Path to the directory to analyze"
---

Analyze the code structure in the specified directory.
Output a report on dependencies and architectural patterns.

Frontmatter parameters:

When to use a skill vs CLAUDE.md:

• Skill — on-demand invocation for a specific task (review, analysis, generation)
• CLAUDE.md — always-loaded general standards and conventions

Personal skills (~/.claude/skills/):

• Create personal variants under different names so you don't affect teammates

5.6 Planning Mode vs Direct Execution

Planning mode:

• The model only investigates and plans; it does not make changes
• Uses Read, Grep, Glob to explore the codebase
• Produces an implementation plan that the user approves
• Safe exploration with no side effects

When to use planning mode:

• Large changes (dozens of files)
• Multiple plausible approaches (microservices: how to define boundaries?)
• Architectural decisions (which framework? what structure?)
• Unfamiliar codebase (you must understand before changing)
• Library migrations affecting 45+ files

When to use direct execution:

• Single-file fixes with a clear stack trace
• Adding one validation check
• Well-understood, unambiguous changes

Combined approach:

1. Planning mode for investigation and design
2. User approves the plan
3. Direct execution to implement the approved plan

Explore subagent — a specialized subagent for exploring the codebase:

• Isolates verbose output from the main context
• Returns only a summary
• Prevents context-window exhaustion in multi-phase tasks

5.7 The /compact Command

/compact is a built-in command for compressing context:

• Summarizes prior history to free up the context window
• Used in long investigation sessions when the context fills up with verbose tool output
• Risk: exact numeric values, dates, and specific details can be lost during summarization

5.8 The /memory Command

/memory is a built-in command for managing memory between sessions:

• Opens the CLAUDE.md file for editing, allowing you to save notes, preferences, and context
• Information persists across sessions and is automatically loaded on startup
• Useful for storing project conventions, user preferences, frequently used commands, and current work context
• Alternative to re-explaining the same instructions in every session

5.9 Claude Code CLI for CI/CD

The -p (or --print) flag:

claude -p "Analyze this pull request for security issues"

• Non-interactive mode: processes the prompt, prints to stdout, exits
• Does not wait for user input
• The only correct way to run Claude in CI/CD pipelines

Structured output for CI:

claude -p "Review this PR" --output-format json --json-schema '{"type":"object",...}'

• --output-format json — output in JSON
• --json-schema — validate output against a schema
• The result can be parsed to automatically post inline PR comments

Session context isolation: The same Claude session that generated code is often less effective at reviewing it (the model retains its reasoning context and is less likely to challenge its own decisions). Use an independent instance for review.

Preventing duplicate comments: When re-reviewing after new commits, include prior review results in context and instruct Claude to report only new or unresolved issues.

5.10 fork_session and Session Management

--resume <session-name> resumes a named session:

claude --resume investigation-auth-bug

• Continues a prior conversation with saved context
• Useful for long investigations across multiple sessions
• Risk: if files changed since the prior session, tool results may be stale

fork_session creates an independent branch from shared context:

Codebase investigation
         |
    fork_session
    /           \
Approach A:      Approach B:
Redux            Context API

• Both forks inherit context up to the branch point
• Afterwards, they diverge independently
• Useful for comparing approaches or testing strategies

When to start a new session instead of resuming:

• Tool results are stale (files changed)
• A lot of time has passed and context has degraded
• It is better to restart with "Here is a short summary of what we found: ..." than to resume with old tool data