Claude Code CLI Practical Guide

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Run Claude Code to start the wizard
claude

# Create new project directory
mkdir my-project
cd my-project

# Initialize Claude Code
claude init

# Create specs directory for project specifications
mkdir -p specs

# Create initial project specification
# See specs/01-init.md below for detailed template

# 1. Code Review Agent
Plan("Review pull request #123 for code quality and best practices")

# 2. Architecture Agent
Task(architect, "Design microservices architecture for user management")

# 3. Testing Agent
Task(testing, "Create comprehensive test suite for authentication module")

# 4. Documentation Agent
Task(documentation, "Generate API documentation from OpenAPI spec")

> Task(performance-analyzer, "Find performance issues in src/components/")
> Done (45 tool uses • 125.3k tokens • 2m 15s)

Results:
- Large bundle size (2.3MB minified)
- Missing code splitting
- Unoptimized images in assets/
- Memory leaks in 3 components
- Inefficient re-renders in dashboard

> I need to add a DELETE /api/users/:id endpoint

# Claude Code automatically:
1. Checks existing user routes
2. Identifies patterns used
3. Finds related models and middleware
4. Looks for authentication requirements

> Task(api-designer, "Plan DELETE /api/users/:id endpoint following existing patterns")

# Sub-agent returns:
- Endpoint structure
- Required middleware
- Error handling patterns
- Database operations needed
- Response format

> Now implement the endpoint following the plan:
1. Add route to src/routes/users.ts
2. Create controller method in src/controllers/userController.ts
3. Add validation middleware
4. Update API documentation
5. Add error handling for user not found

> Analyze src/components/Dashboard.tsx for refactoring opportunities

# Claude Code identifies:
- Multiple responsibilities (data fetching, rendering, state management)
- Repeated UI patterns
- Large hook dependencies
- Potential for component splitting

> Task(refactor-planner, "Create refactoring plan for Dashboard.tsx")

# Sub-agent provides:
- Component breakdown structure
- Hook extraction plan
- State management improvements
- Testing strategy

> Execute refactoring:
1. Extract Header component (lines 1-150)
2. Extract Sidebar component (lines 151-300)
3. Extract useDashboardData hook (lines 301-500)
4. Extract Charts section (lines 501-800)
5. Update parent Dashboard component
6. Add tests for new components

> Memory usage increases by 50MB after navigating between routes

# Step 1: Initial analysis
> Task(memory-analyzer, "Find memory leak sources")

# Sub-agent investigation:
- Checks useEffect cleanup
- Looks for event listeners not removed
- Searches for setInterval/setTimeout not cleared
- Analyzes component mounting/unmounting

# Step 2: Targeted investigation
> Focus on src/components/DataVisualizer.tsx (identified as leak source)

# Step 3: Fix implementation
> Add cleanup to DataVisualizer component:
- Clear chart instances on unmount
- Remove event listeners
- Cancel pending API calls

# Launch parallel sub-agents
> Task(frontend, "Implement user profile page UI")
> Task(backend, "Create user settings API endpoints")
> Task(database, "Add user preferences table schema")

# Main agent coordinates:
- Wait for all sub-agents to complete
- Review results together
- Create integration plan
- Test full workflow

# Phase 1: Analysis
> Task(realtime-analyzer, "Assess current chat architecture for WebSocket integration")

# Phase 2: Implementation
> Based on analysis, implement in stages:
1. Add WebSocket server support
2. Update client for real-time messages
3. Add typing indicators
4. Implement online status
5. Add message read receipts

# Each phase gets its own context with clean slate

# Step 1: Specification
> Task(spec-writer, "Create detailed payment processing specification")

# Step 2: Implementation
> Use specification as guide:
- Follow defined API contracts
- Implement described error cases
- Meet specified performance requirements
- Add required logging and monitoring

# Step 3: Validation
> Task(tester, "Validate implementation against specification")

# Problem: Agent asks about information you already provided

# Solution: Use explicit context management
/clear          # Start fresh when context is polluted
Ctrl+O          # Check current context size
/compact        # Compress when near limit

# Re-state critical information
"Remember: We're using PostgreSQL, not MongoDB"

# Problem: File not found, permission denied, command fails

# Debug steps:
1. Check current working directory
2. Verify file exists with Read tool
3. Check permissions before execution
4. Use absolute paths for clarity

# Example:
> Check if the file exists first
Read("src/config/database.ts")
# Then make changes

# Problem: Sub-agent output too generic or incomplete

# Solutions:
1. Be more specific in task description
2. Provide examples of expected output format
3. Set clear constraints and requirements
4. Use iterative refinement

# Example:
[FAIL] "Analyze the code"
[PASS] "Analyze src/auth/ for security vulnerabilities.
   Report: severity level, exact location, fix suggestions.
   Format: markdown table with columns: file, issue, severity, fix."

# Before complex task
/clear

# Group related requests
> Read all auth files, then make changes to all

# Use sub-agents for large analyses
> Task(analyzer, "Review entire codebase for security issues")

# Bad: Multiple separate reads
Read("src/controllers/user.ts")
Read("src/models/user.ts")
Read("src/middleware/auth.ts")

# Good: Batch operations
> Read all authentication-related files

# Use search instead of reading full files
> Search for TODO comments in src/
> Find all console.log statements

# Simple tasks: Use Haiku (faster, cheaper)
claude config set model claude-3-haiku-20240307

# Complex reasoning: Use Sonnet (default)
claude config set model claude-3-5-sonnet-20241022

# Advanced tasks: Use Opus (most capable)
claude config set model claude-3-opus-20240229

/clear          # Clean slate for new task
Ctrl+O          # Check context size

[FAIL] "Improve the auth system"
[PASS] "In src/auth/login.ts, add rate limiting to prevent brute force attacks.
   Use Redis for storing attempt counts.
   Add 5 attempts per 15 minutes window.
   Return HTTP 429 when limit exceeded."

# Include:
- Exact file paths
- Error messages
- Current vs expected behavior
- Technology stack
- Constraints (what NOT to change)
- Success criteria

# For complex analysis or parallel work
Task(analyzer, "Find security vulnerabilities in auth system")
Task(tester, "Create comprehensive tests for new feature")

# For context isolation
Task(researcher, "Look up latest Node.js security best practices")

# Start with broad request
> Add authentication

# Refine with specifics
> Add JWT authentication to express API
> Use bcrypt for password hashing
> Include rate limiting and input validation

# Launch multiple parallel analyses
Task(linter, "Find all ESLint violations and fix automatically")
Task(security, "Scan for security vulnerabilities and report findings")
Task(performance, "Identify performance bottlenecks and optimization opportunities")
Task(testing, "Find files lacking test coverage and suggest test cases")

# Then coordinate the fixes

# Systematic approach:
1. Profile the page load time
2. Identify bottlenecks
3. Implement optimizations
4. Measure improvements

# Use appropriate tools for each step

# 1. Write your spec once
cat > specs/user-auth.md << 'EOF'
# User Authentication Feature

## Description
Add JWT authentication to the Node.js Express API.

## Implementation Steps
1. Create authController with register/login endpoints
2. Add JWT middleware for protected routes
3. Update user model with password hashing
4. Add validation and error handling
5. Write tests for all auth flows

## Success Criteria
- Users can register and login
- JWT tokens work for protected routes
- Passwords are properly hashed
EOF

# 2. Execute it (multiple times if needed)
claude
> @specs/user-auth.md

# 3. If something is WRONG - don't ask for edits!
# Update the spec instead
echo "4. Add rate limiting to login endpoint" >> specs/user-auth.md

# 4. Execute again with updated spec
claude
> @specs/user-auth.md

# 5. Repeat until done in one or several short prompt-execution cycles

# Create initial project specification
cat > specs/01-init.md << 'EOF'
# Project: [Project Name]

## Overview
[Brief description of what you're building]

## Technology Stack
- Language/Framework: [e.g., Node.js + Express, React + TypeScript]
- Database: [e.g., PostgreSQL, MongoDB]
- API: [e.g., REST, GraphQL]

## Project Structure
src/
├── components/
├── services/
├── utils/
├── types/
└── tests/

## Development Rules
- Use TypeScript strict mode
- Write tests for all new features
- Follow ESLint configuration
- Commit messages follow conventional format

## Getting Started
1. Run `npm install`
2. Set up environment variables (see .env.example)
3. Run `npm run dev` to start development server
4. Run `npm test` to run tests
EOF

# Example: specs/user-authentication.md
cat > specs/user-authentication.md << 'EOF'
# User Authentication Feature

## Description
Implement JWT-based user authentication with registration, login, and logout.

## Requirements

### API Endpoints
- POST /api/auth/register
- POST /api/auth/login
- POST /api/auth/logout
- GET /api/auth/profile

### Implementation Details

#### Database Schema
```sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

# Create project context file
cat > CLAUDE.md << 'EOF'
# Project Context for Claude Code

## Project Overview
This is a [project type] application built with [technologies].

## Development Rules
- Always use TypeScript strict mode
- Run tests before committing
- Follow ESLint configuration
- Use conventional commit messages
- Write tests for new features

## Architecture Patterns
- Service layer for business logic
- Controller layer for API endpoints
- Middleware for cross-cutting concerns
- Types folder for TypeScript interfaces

## Testing Requirements
- Unit tests for all services
- Integration tests for API endpoints
- Minimum 90% code coverage
- Use Jest for testing framework

## Common Commands
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run test` - Run tests
- `npm run lint` - Run linter
- `npm run type-check` - TypeScript type checking

## Working with Specs/
When implementing features:
1. Read the specification in specs/[feature-name].md
2. Follow the implementation prompts exactly
3. Update the spec with any changes made
4. Mark completed items with [x]
EOF

# For each new feature:

# 1. Create specification
echo "# Feature Name" > specs/feature-name.md
# Add detailed requirements and prompts (see template above)

# 2. Review and approve specification
# Get feedback from team if needed

# 3. Implement using Claude Code
claude
> Follow the prompts in specs/feature-name.md step by step

# 4. Testing and linting
npm run test
npm run lint
npm run type-check

# 5. Code review
# Review changes with team
# Address feedback

# 6. Squash merge with changelog
git checkout main
git pull
git merge --squash feature-branch
git commit -m "feat: add feature name

- Implementation details
- Test coverage added
- Documentation updated"
git push

# Install Context7 MCP server
npm install -g @context7/mcp-server

# Configure Claude Code to use Context7
claude config add mcp-server context7

# Get latest API documentation
> Use Context7 to get Express.js authentication patterns

# Get best practices for testing
> Search Context7 for Jest testing patterns and examples

# Get framework-specific guidance
> Use Context7 for React hooks best practices

# Search for specific topics
> Context7 search "JWT authentication Node.js"

# Get API reference
> Context7 get-reference "express.js middleware"

# Find examples
> Context7 examples "TypeScript generics"

# Enable YOLO mode
claude --yolo

# Or for specific commands
claude --yolo "refactor this entire module"

# Enter plan mode
Shift+Tab

# Review the generated plan
# Make adjustments if needed
# Approve or modify the plan
# Execute with confidence

# Week 1: Basic Project Setup
- Create simple project
- Learn basic Claude Code commands
- Write first spec file
- Complete first PR

# Week 2: Feature Implementation
- Implement user authentication
- Learn context management
- Use plan mode effectively
- Write tests

# Week 3: Debugging and Optimization
- Troubleshoot common issues
- Optimize prompts
- Learn from mistakes
- Refine workflow

# Week 4: Integration and Review
- Combine multiple features
- Participate in code review
- Document your process
- Prepare for team work

# Daily (15-30 minutes)
1. Review yesterday's work
2. Plan today's tasks
3. Work on one small feature
4. Write tests and documentation
5. Commit and reflect on learning

# Weekly (2-3 hours)
1. Complete one full feature
2. Review code quality
3. Optimize prompts
4. Update documentation
5. Plan next week's work