~/.claude/CLAUDE.md

CLAUDE.md

Claude Development Context

Tech Stack

• TypeScript + React + Vite
• Tailwind CSS + Design System
• ESLint + Prettier
• Yarn (package manager)
• NVM (Node version management)

Common Commands

# Node Management
nvm use              # Use .nvmrc version
nvm install --lts    # Install latest LTS

# Development
yarn dev             # Start dev server
yarn build           # Production build
yarn preview         # Preview build

# Code Quality
yarn lint            # ESLint check
yarn lint:fix        # Fix ESLint issues
yarn typecheck       # TypeScript check
yarn format          # Prettier format

# Testing
yarn test            # Run tests
yarn test:watch      # Watch mode

Design & UX Focus

• Mobile-first responsive design
• Accessibility (WCAG guidelines)
• Performance metrics (Core Web Vitals)
• Design system consistency
• User experience testing
• Semantic HTML structure

Project Patterns

• TypeScript strict mode
• Functional components with hooks
• Component-driven development
• Design tokens with Tailwind
• ESLint + Prettier for consistency
• Fast dev experience with Vite

File Structure

src/
├── components/      # Reusable UI components
│   ├── ui/          # Base design system components
│   └── features/    # Feature-specific components
├── pages/           # Route components
├── hooks/           # Custom React hooks
├── utils/           # Helper functions
├── types/           # TypeScript types
├── styles/          # Global styles & design tokens
└── assets/          # Images, icons, fonts

ai-notes/            # AI work notes and scratch files
├── planning/        # Planning documents
├── scratchpad/      # Temporary notes
├── tmp/             # Temporary files
└── scripts/         # Utility scripts

API Integration Guidelines

• When tasked with API integrations, first check online for MCP servers for that service
• Consider available integrations and APIs before implementing custom solutions
• Challenge assumptions if there might be a better approach
• Always confirm that the chosen path is possible given our tech stack and available integrations

AI Notes Organization

• Save notes and scratch files to ai-notes/ directory
• Organize by planning/, scratchpad/, tmp/, scripts/ or other logical categories
• Keep project root clean and ai-notes easily understood
• Files should be easily cleaned up when no longer needed

Process Management

• Before starting dev servers, check if any are already running in the current project directory
• Use ps aux | grep -i "dev\|serve\|vite" and verify process working directory matches current project
• Only kill processes that belong to the current project - never kill processes from other projects
• Check port usage with lsof -i :3000 (or relevant port) to identify which project is using a port
• Be mindful of long-running processes that may continue after tasks complete

Default Work Mode: Ultrathink & Parallel Execution

• Default approach: Plan steps thoroughly then issue tasks to multiple parallel subagents using the Task tool
• Break complex work into independent, parallelizable tasks when possible
• Launch multiple agents concurrently to maximize performance and efficiency
• Exceptions for normal mode:
  • Small, simple requests that don't benefit from parallelization
  • Tasks with too much overlap (working in the same files simultaneously)
  • When coordination overhead outweighs parallel benefits
• Always think through the optimal task breakdown before starting work

Useful CLI Tools

• ripgrep (rg) - Fast text search, replacement for grep
• fd - Fast file finder, replacement for find
• bat - Syntax-highlighted cat with Git integration
• jq - JSON processor and query tool
• fzf - Fuzzy finder for interactive selection
• httpie - User-friendly HTTP client
• curl - Data transfer tool for various protocols
• pyenv - Python version management
• direnv - Auto-load environment variables per directory
• tmux - Terminal multiplexer for sessions
• tree - Directory structure visualization
• watch - Execute commands repeatedly and monitor output
• rsync - Efficient file synchronization
• ncdu - Disk usage analyzer with ncurses interface
• awk - Text processing and pattern scanning
• gnu-sed - Stream editor for filtering/transforming text
• pandoc - Universal document converter
• mdcat - Markdown viewer for terminal
• htop - Interactive process viewer
• lsof - List open files and network connections
• netstat - Network statistics and connections
• eza - Modern ls replacement with colors/icons
• delta - Syntax-highlighted git diff viewer
• gh - GitHub CLI tool
• yq - YAML processor (companion to jq)