Claude Code Workflows

A complete Claude Code configuration showcase demonstrating the CLAUDE.md hierarchy, skills with context isolation, commands for quick actions, plan mode triggers, and TDD iteration patterns. Meta-project: Claude Code configuring Claude Code.

Built as a case study for the Claude Certified Architect — Foundations certification, demonstrating mastery of Domain 3 (Claude Code Configuration & Workflows) and Domain 4 (Prompt Engineering & Structured Output).

The Core Idea

Configuration has a hierarchy with clear audiences:

~/.claude/CLAUDE.md          → Personal preferences (editor, style, communication)
.claude/CLAUDE.md            → Team standards (coding rules, review policy, deployment)
src/CLAUDE.md                → Module-specific patterns (API conventions, error handling)
tests/CLAUDE.md              → Test-specific rules (AAA pattern, coverage, mocking)

And the distinction between commands and skills is architectural:

Commands	Skills
Single step	Multi-step reasoning
No isolation needed	context: fork for isolation
Pass/fail result	Judgment-based analysis
/format, /lint, /test	/review, /refactor, /tdd

Configuration Architecture

Three-Level Hierarchy (ADR-001)

Level	File	Audience	Content
User	~/.claude/CLAUDE.md	Individual developer	Editor prefs, communication style
Project	.claude/CLAUDE.md	Whole team	Coding standards, review policy, deploy rules
Directory	src/CLAUDE.md, tests/CLAUDE.md	Module users	API patterns, test conventions

Anti-pattern avoided (AP-18): Personal preferences NEVER go in project-level config. Team standards NEVER go in user-level config. Each layer has a clear audience.

Commands (Quick, No Isolation)

Command	What it does	Gate
/format	Runs prettier	Files changed count
/lint	Runs eslint	Error count = 0
/test	Runs jest with coverage	All pass AND coverage >= 80%
/typecheck	Runs tsc --noEmit	Error count = 0

Each is a single action with a numeric pass/fail criterion. No exploration, no multi-step reasoning, no context pollution.

Skills (Complex, Isolated)

Skill	Tools Allowed	Isolation	Purpose
/review	Read, Grep, Glob	Forked, read-only	Code review with explicit criteria
/refactor	Read, Edit, Grep, Glob	Forked, no Bash	Guided refactoring
/migrate	All tools	Forked, plan mode	Large-scale migration
/tdd	All tools	Forked	Test-driven development cycle

Anti-pattern avoided (AP-14): Complex operations that need exploration or could pollute the session ALWAYS use skills with context: fork. They never run as commands.

Anti-pattern avoided (AP-7): The /review skill runs in a forked context with read-only tools. It cannot access the generator's reasoning. Session isolation prevents confirmation bias.

Rules Directory

Modular, topic-specific rules loaded via @import:

• typescript.md — Type strictness, naming, imports
• testing.md — AAA pattern, coverage thresholds, mock boundaries
• security.md — No hardcoded secrets, parameterized queries, input validation

TDD Skill (ADR-004)

The /tdd skill encodes a strict iteration cycle with measurable gates:

1. Write failing test    → test MUST fail (red)
2. Implement minimum     → max 50 lines, no `any`
3. Verify               → tests pass + coverage >= 80% + 0 type errors
4. Refine               → if complexity > 8 or > 30 lines, extract

Anti-pattern avoided (AP-8): Every step has a numeric threshold. No "make it work" or "looks good."

What This Demonstrates

Certification Domain	How It's Demonstrated
D3: Claude Code Config	Three-level CLAUDE.md hierarchy, commands vs skills, plan mode triggers, rules directory, @import
D4: Prompt Engineering	Explicit measurable criteria in every command/skill, TDD with numeric gates, no vague instructions
D2: Tool Design	Correct built-in tool selection (Read/Edit/Grep/Glob), allowed-tools restrictions on skills

Project Structure

claude-code-workflows/
├── .claude/
│   ├── CLAUDE.md              # Team standards (project-level)
│   ├── commands/              # Quick single-step actions
│   │   ├── format.md
│   │   ├── lint.md
│   │   ├── test.md
│   │   └── typecheck.md
│   ├── skills/                # Complex operations with isolation
│   │   ├── review/SKILL.md   # Read-only, forked
│   │   ├── refactor/SKILL.md # No Bash, forked
│   │   ├── migrate/SKILL.md  # Plan mode, forked
│   │   └── tdd/SKILL.md      # TDD cycle, forked
│   └── rules/                # Topic-specific rules (@import)
│       ├── typescript.md
│       ├── testing.md
│       └── security.md
├── src/                       # Sample TypeScript project
│   ├── CLAUDE.md             # Directory-level: API patterns
│   ├── auth/                 # Auth module
│   └── api/                  # API routes with validation
├── tests/                     # Sample tests
│   ├── CLAUDE.md             # Directory-level: test rules
│   ├── auth.test.ts
│   └── api.test.ts
└── docs/
    ├── user-claude-md-example.md   # What belongs at user level
    ├── when-to-use-what.md         # Quick reference
    └── adr/                        # Decision records

Anti-Patterns This Project Avoids

#	Anti-Pattern	How We Avoid It
AP-7	Same-session self-review	/review skill uses context: fork with read-only tools
AP-8	Vague instructions	Every command/skill has numeric thresholds, no "be thorough"
AP-14	Commands for complex tasks	Review, refactor, migrate are skills with context isolation
AP-18	Personal prefs in project config	Personal prefs in user-level example only, never in .claude/

License

CC-BY-NC-4.0 — Portfolio demonstration. View, fork, and learn freely. Commercial use not permitted.