Claude Code Research

Claude Code CLAUDE.md Workshop Exercises

8 min read

Claude Code CLAUDE.md Workshop Exercises

Overview

Hands-on exercises for learning CLAUDE.md best practices. Each exercise builds on previous concepts, progressing from basic to advanced patterns.

Workshop Structure

Exercise 1 - Basic Setup

Time: 15 minutes

Objective

Create your first CLAUDE.md file for a simple Node.js project.

Starting Point

mkdir todo-cli
cd todo-cli
npm init -y
npm install typescript @types/node --save-dev

Task

Create a CLAUDE.md file that includes:

  1. Project description
  2. Available npm scripts
  3. Project structure
  4. Basic coding standards

Starter Template

# Project: 
Purpose: 
 
# Commands
- 
- 
- 
 
# Structure
- 
- 
 
# Standards
- 
-

Success Criteria

  • Claude understands project purpose
  • Commands are concise and clear
  • Structure helps navigation
  • Standards are actionable

Discussion Points

  • Why conciseness matters
  • Token usage awareness
  • Living documentation concept

Exercise 2 - TypeScript Project

Time: 20 minutes

Objective

Enhance CLAUDE.md for a TypeScript React project with testing.

Starting Point

npx create-vite@latest task-manager --template react-ts
cd task-manager
npm install
npm install -D vitest @testing-library/react @testing-library/jest-dom

Task

Create a comprehensive CLAUDE.md that includes:

  1. TypeScript configuration preferences
  2. React component patterns
  3. Testing requirements
  4. Import conventions
  5. State management approach

Requirements Checklist

Must include:
□ TypeScript strict mode rules
□ Component structure pattern
□ Test file naming convention
□ Import organization
□ At least one "bad example"

Bonus Challenges

  1. Add a custom slash command idea
  2. Include performance considerations
  3. Add accessibility requirements

Expected Outcome Example

# Task Manager App
Stack: React 18, TypeScript 5.2, Vite, Zustand
 
# TypeScript
- strict: true
- No any types
- Explicit return types
- Interface > Type for objects
 
# Components
Structure:
- FC with explicit props
- Props interface above component
- Hooks at top
- Early returns for guards
 
❌ Bad:
export default function Button({onClick, children}: any) {...}
 
✅ Good:
interface ButtonProps {
  onClick: () => void
  children: React.ReactNode
}
 
export const Button: FC<ButtonProps> = ({ onClick, children }) => {...}
 
# Testing
- *.test.tsx adjacent to component
- Coverage target: 80%
- Test user behavior, not implementation
- Mock with MSW
 
# Imports
1. React/Next
2. Third-party libs
3. @/ aliases
4. Relative imports
5. Types last
 
# State
- Zustand for global
- useState for local
- React Query for server

Exercise 3 - Team Collaboration

Time: 20 minutes

Objective

Set up CLAUDE.md files for team collaboration with personal preferences.

Scenario

You’re working on a team project with:

  • Shared coding standards
  • Different developer preferences
  • CI/CD requirements
  • Multiple environments

Task

Create three files:

  1. CLAUDE.md - Team standards (git tracked)
  2. CLAUDE.local.md - Personal preferences (gitignored)
  3. .claude/commands/review.md - Custom review command

Team Requirements

The team has agreed on:
- ESLint + Prettier
- Conventional commits
- PR requires 2 approvals
- 90% test coverage
- No console.logs in production

Personal Preferences Examples

Choose your preferences:
- npm vs yarn vs pnpm
- 2 spaces vs 4 spaces vs tabs
- Single vs double quotes
- Semicolons vs no semicolons
- Testing: watch mode vs single run

Custom Command Template

Create .claude/commands/review.md:

Review the code in $ARGUMENTS for:
1. TypeScript strict compliance
2. Test coverage
3. Performance implications
4. Security concerns
5. Accessibility requirements
 
Output format:
## ✅ Looks Good
- 
 
## ⚠️ Suggestions
- 
 
## ❌ Must Fix
-

Advanced Challenge

Add import statements to modularize configuration:

# CLAUDE.md
@./docs/api-standards.md
@./docs/component-guidelines.md
@~/.claude/personal-shortcuts.md

Exercise 4 - Advanced Patterns

Time: 25 minutes

Objective

Implement advanced CLAUDE.md patterns for a monorepo project.

Setup

mkdir acme-platform
cd acme-platform
npx create-turbo@latest

Monorepo Structure

acme-platform/
├── apps/
│   ├── web/          # Next.js app
│   └── api/          # Express API
├── packages/
│   ├── ui/           # Shared components
│   ├── types/        # Shared TypeScript types
│   └── utils/        # Shared utilities
└── CLAUDE.md         # Root configuration

Tasks

1. Root CLAUDE.md

Create hierarchical configuration:

# Monorepo: ACME Platform
Tool: Turborepo
Package manager: pnpm
 
# Global Commands
- install: pnpm install
- dev: turbo dev
- build: turbo build
- test: turbo test
 
# Architecture Rules
- 
- 
- 
 
# Import package configs
@./packages/ui/CLAUDE.md
@./packages/types/CLAUDE.md
@./apps/web/CLAUDE.md
@./apps/api/CLAUDE.md

2. Package-Specific CLAUDE.md

Create at least two package-specific files:

packages/ui/CLAUDE.md:

# Package: @acme/ui
Purpose: Shared React components
 
# Exports
- Components from src/index.ts
- Styles as CSS modules
- Types included
 
# Component Rules
- 
-

apps/web/CLAUDE.md:

# App: Web Frontend
Framework: Next.js 14 App Router
 
# Features
- 
- 
 
# Routes
- 
-

3. Performance Optimization

Add context management:

# Performance
- Max context: 3 levels
- Exclude: node_modules, .next, dist
- Focus: Current package
 
# Smart Loading
When working on:
- UI: Load only @acme/ui
- API: Load only @acme/api
- Types: Load all packages

Success Metrics

  • Each package has specific rules
  • No duplicate information
  • Clear command structure
  • Performance considered
  • Imports used effectively

Exercise 5 - Real World Scenario

Time: 30 minutes

Objective

Create a production-ready CLAUDE.md for an e-commerce platform.

Scenario

You’re building an e-commerce platform with:

  • Next.js frontend
  • Node.js/Express API
  • PostgreSQL database
  • Redis caching
  • Stripe payments
  • Real-time inventory updates
  • Multi-language support
  • SEO requirements

Requirements

Technical Stack

  • TypeScript everywhere
  • tRPC for type-safe API
  • Prisma for database
  • Bull for job queues
  • Socket.io for real-time

Business Requirements

  • PCI compliance for payments
  • GDPR compliance for EU
  • 99.9% uptime SLA
  • <3s page load time
  • Support 10k concurrent users

Your Task

Create a comprehensive CLAUDE.md that covers:

  1. Architecture Overview
  2. Development Workflow
  3. Security Requirements
  4. Performance Guidelines
  5. Testing Strategy
  6. Deployment Process
  7. Monitoring and Alerts

Evaluation Criteria

## Excellent (90-100%)
- Covers all requirements
- Concise yet complete
- Good/bad examples
- Performance aware
- Security focused
 
## Good (70-89%)
- Most requirements covered
- Generally concise
- Some examples
- Basic security mentions
 
## Needs Improvement (<70%)
- Missing key requirements
- Too verbose or too brief
- No examples
- Security/perf overlooked

Bonus Features

Add these for extra credit:

  1. Incident response procedure
  2. Feature flag strategy
  3. A/B testing setup
  4. Internationalization rules
  5. SEO checklist

Solutions and Discussion

Solution Principles

1. Conciseness vs Completeness

# ❌ Too Verbose
Our application uses the Next.js framework version 14 with the new App Router 
feature for building the frontend user interface...
 
# ✅ Balanced
Frontend: Next.js 14 (App Router), React 18, TypeScript
API: Express 5, tRPC, PostgreSQL + Prisma

2. Structure and Organization

# ✅ Well Organized
# Stack
Frontend: Next.js, React Query, Zustand
Backend: Express, Prisma, Redis
 
# Commands
- dev: turbo dev
- test: turbo test --filter=$PACKAGE
- db:push: cd packages/db && prisma db push
 
# Patterns
- API: RESTful + tRPC for types
- Auth: NextAuth with JWT
- Errors: Consistent error codes

3. Actionable Instructions

# ❌ Vague
Follow best practices for security
 
# ✅ Specific
Security:
- Input: Zod validation on all endpoints
- Auth: JWT in httpOnly cookies
- CORS: Whitelist production domains
- Secrets: process.env only, never hardcode

Common Pitfalls to Avoid

  1. Information Overload

    • Don’t explain what TypeScript is
    • Don’t document language features
    • Focus on project-specific patterns

  2. Outdated Information

    • Review CLAUDE.md weekly
    • Update after major changes
    • Remove deprecated patterns

  3. Missing Context

    • Include “why” for non-obvious choices
    • Document team decisions
    • Explain workarounds

  4. Poor Organization

    • Use clear headings
    • Group related items
    • Consistent formatting

Advanced Tips

Progressive Enhancement

Start simple, add complexity as needed:

# Version 1 (Day 1)
- TypeScript strict mode
- Test files: *.test.ts
 
# Version 2 (Week 1)
- TypeScript strict mode
- Test files: *.test.ts adjacent to source
- Mock API calls with MSW
- Coverage target: 80%
 
# Version 3 (Month 1)
- [Previous content]
- E2E tests in /e2e with Playwright
- Performance budget: <3s load time
- Bundle size limit: 200KB

Living Documentation

Use the # key liberally:

  • Discovered a gotcha? Add it
  • Found a better pattern? Update it
  • Team made a decision? Document it

Team Collaboration

# In PR Reviews
"Added to CLAUDE.md: API rate limit pattern"
 
# In Slack
"Updated CLAUDE.md with new deployment process"
 
# In Standups
"Let's update CLAUDE.md with the auth changes"

Workshop Takeaways

  1. CLAUDE.md is Code

    • Treat it like production code
    • Review in PRs
    • Test its effectiveness

  2. Measure Impact

    • Track token usage
    • Monitor Claude’s accuracy
    • Gather team feedback

  3. Iterate Constantly

    • Start minimal
    • Add based on needs
    • Remove what’s not working

  4. Think in Patterns

    • Identify repetitive questions
    • Document once, benefit always
    • Share across projects

Additional Resources

Next Steps

  1. Create CLAUDE.md for your current project
  2. Share with your team
  3. Iterate based on usage
  4. Contribute examples back to community

Remember: The best CLAUDE.md is one that evolves with your project and team needs.

Graph View

Backlinks