# Claude Code Usage Examples

## Overview
Claude Code is Anthropic's official CLI for Claude that helps with software engineering tasks. Here are practical examples.

## Basic Usage

### 1. **Code Review & Analysis**

```bash
# Review a specific file for issues
claude-code /path/to/file.py --task "review this file for bugs and suggest improvements"

# Analyze architecture across multiple files
claude-code src/ --task "analyze the architecture and suggest refactoring opportunities"

# Security audit
claude-code . --task "perform security audit for common vulnerabilities"
```

### 2. **Bug Fixing**

```bash
# Describe the bug and let Claude find/fix it
claude-code . --task "fix the bug where users can't login with special characters in password"

# With specific file hint
claude-code src/auth/ --task "debug the login failure and fix it"

# Ask for root cause analysis
claude-code . --task "find why the async task is hanging and fix it"
```

### 3. **Writing Tests**

```bash
# Generate comprehensive tests
claude-code src/payment.py --task "write pytest tests with 90%+ coverage"

# Integration tests
claude-code src/ --task "write integration tests for the user workflow"

# Edge cases and error handling
claude-code src/validators.py --task "write tests for edge cases and error conditions"
```

### 4. **Refactoring**

```bash
# Improve code quality
claude-code src/utils.py --task "refactor this module to be more maintainable"

# Performance optimization
claude-code src/database.py --task "optimize database queries for performance"

# Type hints and documentation
claude-code src/ --task "add comprehensive type hints and docstrings"
```

### 5. **Documentation**

```bash
# Generate README
claude-code . --task "write a comprehensive README.md with setup and usage"

# API documentation
claude-code src/api/ --task "write OpenAPI documentation for the API"

# Docstrings
claude-code src/ --task "add detailed docstrings to all public functions"
```

## Advanced Examples

### 6. **Feature Implementation**

```bash
# Plan feature implementation
claude-code . --task "design and implement user authentication with JWT tokens"

# Implement specific feature
claude-code src/ --task "add dark mode support to the web UI"

# Database schema changes
claude-code src/models/ --task "add user profile fields and write migrations"
```

### 7. **Debugging with Context**

```bash
# Provide error message
claude-code . --task "
Error: TypeError: Cannot read property 'length' of undefined at line 42
Fix this error in src/parser.js
"

# With stack trace
claude-code . --task "
Debug this stack trace:
  at processData (src/worker.js:15:23)
  at async runJob (src/scheduler.js:45:60)
"
```

### 8. **Code Generation**

```bash
# Generate boilerplate
claude-code . --task "generate a React component for a todo list with add/delete/edit"

# Database models
claude-code src/models/ --task "generate SQLAlchemy models for a blog system"

# CLI tool
claude-code . --task "generate a CLI tool for managing AWS resources"
```

### 9. **Configuration & Setup**

```bash
# Fix configuration issues
claude-code . --task "fix the TypeScript configuration to support ES modules"

# Docker setup
claude-code . --task "create a Dockerfile and docker-compose.yml for this project"

# CI/CD pipeline
claude-code . --task "set up GitHub Actions for testing and deployment"
```

### 10. **Migration & Upgrades**

```bash
# Upgrade dependencies
claude-code . --task "upgrade React from v17 to v18 and fix breaking changes"

# Database migration
claude-code src/ --task "write database migration to add user roles table"

# Version upgrade
claude-code . --task "upgrade Python from 3.9 to 3.12 and fix compatibility issues"
```

## Remux-Specific Examples

### Using Claude Code with Remux

```bash
# Execute code review on remote server
python -m rpipe.client remote.example.com \
  "cat src/main.py | claude-code --task 'review for bugs'"

# Run tests via remux with output audit logging
RPIPE_AUDIT_LOG_DIR=/var/log/rpipe python -m rpipe.daemon &
python -m rpipe.client remote.example.com \
  --policy read_only \
  "pytest tests/ --cov=src"
```

## Tips & Tricks

### 1. **Multi-Step Tasks**

Break complex tasks into steps:
```bash
# Step 1: Understand the issue
claude-code . --task "analyze why tests are failing"

# Step 2: Fix the root cause
claude-code . --task "fix the root cause found in previous analysis"

# Step 3: Verify the fix
claude-code . --task "write tests to ensure the fix works"
```

### 2. **Focused Analysis**

```bash
# Only analyze specific directory
claude-code src/components/ --task "review React components for performance"

# Exclude node_modules
claude-code . --task "review code" --exclude "node_modules,dist,.git"

# Specific file types
claude-code . --task "review" --include "*.py" --exclude "test_*.py"
```

### 3. **Large Codebase Strategy**

```bash
# Start with architecture
claude-code . --task "provide high-level architecture overview"

# Then dive into components
claude-code src/auth/ --task "audit authentication system"
claude-code src/api/ --task "review API design"
claude-code src/database/ --task "optimize database layer"
```

### 4. **Iterative Development**

```bash
# Generate initial version
claude-code . --task "implement basic user authentication"

# Improve it
claude-code . --task "add rate limiting and security hardening to auth"

# Add tests
claude-code . --task "write comprehensive tests for auth system"

# Documentation
claude-code . --task "document authentication API and security considerations"
```

## Real-World Scenarios

### Scenario 1: New Team Member Onboarding

```bash
# Help new dev understand codebase
claude-code . --task "
You are onboarding a new developer.
Explain the project structure, main components, and how to get started.
Create a CONTRIBUTING.md guide.
"
```

### Scenario 2: Legacy Code Modernization

```bash
# Assess modernization needs
claude-code . --task "assess this Python 2.7 codebase for modernization to Python 3.11"

# Plan migration
claude-code . --task "create step-by-step migration plan from Django 2.x to 4.x"

# Execute migration
claude-code . --task "perform Django 2.x to 4.x migration and fix deprecations"
```

### Scenario 3: Performance Bottleneck Investigation

```bash
# Analyze performance
claude-code . --task "
The application is slow. Here are the slow endpoints:
- /api/users - 2000ms average
- /api/posts - 1500ms average
- /api/search - 5000ms average

Analyze the code and suggest optimizations.
"

# Implement fixes
claude-code . --task "implement the performance optimizations from the analysis"
```

### Scenario 4: Security Audit

```bash
# Perform security audit
claude-code . --task "
Perform comprehensive security audit:
- Check for SQL injection vulnerabilities
- Review authentication/authorization
- Identify insecure dependencies
- Check for exposed secrets
"

# Fix issues
claude-code . --task "fix all security vulnerabilities found in the audit"
```

## Integration Examples

### With Git Workflow

```bash
# Before commit - review changes
claude-code --git-staged --task "review staged changes for quality and correctness"

# Generate commit message
claude-code --git-diff main --task "generate a descriptive commit message"
```

### With CI/CD

```bash
# In GitHub Actions
- name: Code Review
  run: claude-code . --task "review code changes for quality"

# In pre-commit hook
claude-code . --task "quick quality check" || exit 1
```

### With Pull Requests

```bash
# Review PR
claude-code . --task "
This is a pull request that:
1. Adds user authentication
2. Implements JWT tokens
3. Adds password reset functionality

Review for security, performance, and code quality.
"
```

## Command Reference

```bash
# Basic syntax
claude-code [PATH] --task "description of what to do"

# Common options
--task "description"           # Task description (required)
--help                         # Show help
--version                      # Show version
--model sonnet                 # Use specific model (haiku/sonnet/opus)
--timeout 300                  # Timeout in seconds
--interactive                  # Interactive mode
--output file.md              # Save output to file

# Advanced options
--context-file context.md     # Provide additional context
--no-edit                     # Don't offer to edit files
--dry-run                     # Show what would be done
```

## Best Practices

1. **Be Specific**: Clear, detailed task descriptions get better results
2. **Provide Context**: Include error messages, logs, or relevant details
3. **Iterate**: Use multi-step approach for complex tasks
4. **Review**: Always review Claude's suggestions before applying
5. **Test**: Run tests after making changes
6. **Document**: Update documentation along with code changes

## Limitations & Workarounds

### Large Codebases
- Problem: Can't analyze entire large codebase at once
- Solution: Analyze component by component

### Real-time Debugging
- Problem: Claude Code can't debug running applications in real-time
- Solution: Provide error logs and stack traces

### External Dependencies
- Problem: Can't modify external packages
- Solution: Create wrapper/shim layer or propose upstream changes

## Resources

- [Claude Code Documentation](https://claude.com/claude-code)
- [Anthropic API Reference](https://docs.anthropic.com)
- [Claude Models](https://www.anthropic.com/models)

## Examples in This Project

This remux project was built using Claude Code:

```bash
# Initial architecture review
claude-code . --task "review the remux architecture design"

# Feature implementation
claude-code . --task "implement pipe support for shell pipelines"
claude-code . --task "implement audit logging infrastructure"
claude-code . --task "implement error recovery with circuit breakers"

# Testing
claude-code . --task "write comprehensive tests for audit logging"

# Documentation
claude-code . --task "write GETTING_STARTED.md guide"
```
