context-forge/.claude/docs/analyze.md

AI orchestration platform with autonomous teams, enhancement planning, migration tools, 25+ slash commands, checkpoints & hooks. Multi-IDE: Claude, Cursor, Windsurf, Cline, Copilot

# Analyze Guide - Context Forge

## What is Analyze?

The `analyze` command is Context Forge's intelligent project scanner that examines existing codebases to generate AI-optimized documentation. It detects frameworks, patterns, architecture, and creates comprehensive context for AI assistants.

## When to Use Analyze

Use the `analyze` command when:
- Adding AI assistance to existing projects
- Documenting legacy codebases
- Onboarding team members or AI assistants
- Auditing code quality and architecture
- Preparing for migrations or enhancements

## Analysis Capabilities

### 1. Framework Detection
- **Frontend**: React, Vue, Angular, Svelte, Next.js
- **Backend**: Express, NestJS, Fastify, Django, Rails
- **Full-Stack**: Next.js, Nuxt, Remix, SvelteKit
- **Mobile**: React Native, Flutter, Ionic
- **Desktop**: Electron, Tauri

### 2. Pattern Recognition
- **Architecture**: MVC, Microservices, Monolithic, Serverless
- **Design Patterns**: Singleton, Factory, Observer, Repository
- **Code Patterns**: Hooks, HOCs, Middleware, Decorators

### 3. Quality Metrics
- **Complexity**: Cyclomatic complexity analysis
- **Maintainability**: Code organization and structure
- **Test Coverage**: Testing patterns and coverage
- **Documentation**: Comment density and quality

## Step-by-Step Workflow

### 1. Basic Analysis

```bash
# Simple analysis
context-forge analyze

# With output directory
context-forge analyze -o ./docs

# Target specific IDEs
context-forge analyze -i claude,cursor
```

### 2. Analysis Phases

#### Phase 1: File System Scan
- Identifies project structure
- Counts files by type
- Detects configuration files
- Maps directory organization

#### Phase 2: Dependency Analysis
- Parses package.json/requirements.txt
- Identifies core dependencies
- Detects dev dependencies
- Maps version constraints

#### Phase 3: Code Analysis
- Detects programming languages
- Identifies frameworks
- Recognizes patterns
- Evaluates complexity

#### Phase 4: Documentation Generation
- Creates CLAUDE.md
- Generates PRPs
- Configures IDE settings
- Sets up automation

### 3. Interactive Configuration

During analysis, you'll configure:

1. **Project Details**
   ```
   ? Project name: my-app
   ? Description: E-commerce platform
   ? Confirm tech stack: React, Node.js, PostgreSQL
   ```

2. **Documentation Depth**
   ```
   ? Documentation level:
   ❯ Comprehensive - Full analysis with examples
     Standard - Balanced documentation
     Minimal - Essential information only
   ```

3. **AI Features**
   ```
   ? Enable features:
   ❯ ◉ Slash commands
     ◉ Hooks
     ◉ Checkpoints
     ◉ AI documentation
   ```

## Analysis Output Types

### 1. Main Context File (CLAUDE.md)
```markdown
# Project: MyApp

## Tech Stack
- Frontend: React 18.2, TypeScript 5.0
- Backend: Express 4.18, Node.js 18
- Database: PostgreSQL 14
- Testing: Jest, React Testing Library

## Architecture
- Pattern: REST API with React SPA
- State Management: Redux Toolkit
- Authentication: JWT with refresh tokens

## Key Patterns
- Custom hooks for data fetching
- Repository pattern for data access
- Middleware for authentication
```

### 2. Project Requirement Prompts (PRPs)
```
PRPs/
├── architecture-overview.md
├── implementation-patterns.md
├── testing-strategy.md
└── deployment-guide.md
```

### 3. IDE Configurations
```
.claude/
├── commands/
│   ├── run-dev.md
│   ├── run-tests.md
│   └── check-types.md
├── hooks/
│   ├── pre-commit.py
│   └── post-merge.py
└── project.json
```

## Advanced Analysis Features

### 1. Deep Analysis Mode

```bash
# Comprehensive analysis with AI insights
context-forge analyze --deep

# Includes:
# - Detailed code quality metrics
# - Security vulnerability scanning
# - Performance bottleneck detection
# - Architectural recommendations
```

### 2. AI-Powered Insights

```bash
# Enable AI analysis (requires API key)
context-forge analyze --ai-insights

# Provides:
# - Code smell detection
# - Refactoring suggestions
# - Pattern recommendations
# - Optimization opportunities
```

### 3. Comparative Analysis

```bash
# Compare with best practices
context-forge analyze --compare

# Shows:
# - Industry standard comparisons
# - Framework-specific recommendations
# - Missing patterns or practices
# - Upgrade suggestions
```

## Framework-Specific Analysis

### 1. React Projects
```bash
context-forge analyze --framework react

# Detects:
# - Component patterns (class/functional)
# - State management (Redux, Context, Zustand)
# - Routing setup
# - Build configuration
# - Testing patterns
```

### 2. Node.js APIs
```bash
context-forge analyze --framework node

# Analyzes:
# - API structure (REST/GraphQL)
# - Middleware usage
# - Database patterns
# - Authentication methods
# - Error handling
```

### 3. Full-Stack Applications
```bash
context-forge analyze --full-stack

# Examines:
# - Frontend-backend integration
# - API contracts
# - Shared types/interfaces
# - Build processes
# - Deployment configuration
```

## Analysis Customization

### 1. Scope Control
```bash
# Analyze specific directories
context-forge analyze --include src,lib

# Exclude paths
context-forge analyze --exclude node_modules,dist,coverage

# Limit file types
context-forge analyze --extensions js,ts,jsx,tsx
```

### 2. Output Formats
```bash
# JSON report
context-forge analyze --format json > analysis.json

# Markdown report
context-forge analyze --format markdown

# HTML dashboard
context-forge analyze --format html --open
```

### 3. Performance Options
```bash
# Parallel analysis (faster)
context-forge analyze --parallel

# Limit file count
context-forge analyze --max-files 5000

# Skip large files
context-forge analyze --skip-large
```

## Integration Patterns

### 1. CI/CD Integration
```yaml
# GitHub Actions
- name: Analyze Codebase
  run: |
    npx context-forge analyze --ci
    git add .claude CLAUDE.md
    git commit -m "Update AI context"
```

### 2. Pre-commit Hooks
```bash
# .git/hooks/pre-commit
#!/bin/bash
context-forge analyze --quick --check-only
```

### 3. Scheduled Analysis
```bash
# Cron job for weekly analysis
0 0 * * 0 cd /path/to/project && context-forge analyze --auto
```

## Common Patterns and Solutions

### 1. Monorepo Analysis
```bash
# Analyze entire monorepo
context-forge analyze --monorepo

# Analyze specific package
cd packages/api && context-forge analyze --scope package

# Generate unified docs
context-forge analyze --monorepo --unified
```

### 2. Legacy Code Analysis
```bash
# Enhanced pattern detection
context-forge analyze --legacy

# Include deprecated patterns
context-forge analyze --include-deprecated

# Generate migration suggestions
context-forge analyze --suggest-migrations
```

### 3. Microservices Analysis
```bash
# Analyze service mesh
context-forge analyze --microservices

# Map service dependencies
context-forge analyze --service-map

# Generate API documentation
context-forge analyze --api-docs
```

## Quality Metrics Explained

### 1. Complexity Score
- **Low (0-10)**: Simple, maintainable code
- **Medium (11-20)**: Moderate complexity
- **High (21+)**: Consider refactoring

### 2. Maintainability Index
- **A (80-100)**: Highly maintainable
- **B (60-79)**: Moderately maintainable
- **C (40-59)**: Difficult to maintain
- **D (0-39)**: Very difficult to maintain

### 3. Test Coverage
- **Excellent (>80%)**: Well tested
- **Good (60-80%)**: Adequate testing
- **Fair (40-60%)**: More tests needed
- **Poor (<40%)**: Insufficient testing

## Troubleshooting

### 1. Detection Issues
```bash
# Force framework detection
context-forge analyze --force-detect

# Manually specify frameworks
context-forge analyze --frameworks react,express

# Debug detection process
context-forge analyze --debug
```

### 2. Performance Problems
```bash
# For large codebases
context-forge analyze --stream

# Reduce memory usage
context-forge analyze --low-memory

# Skip resource-intensive checks
context-forge analyze --fast
```

### 3. Output Issues
```bash
# Verify without writing
context-forge analyze --dry-run

# Force overwrite
context-forge analyze --force

# Backup existing files
context-forge analyze --backup
```

## Best Practices

### 1. Regular Analysis
- Run weekly for active projects
- Run after major changes
- Run before releases

### 2. Team Collaboration
- Share analysis reports
- Track metrics over time
- Use insights for planning

### 3. Continuous Improvement
- Address detected issues
- Implement suggestions
- Monitor trends

## Integration with Other Commands

### 1. Analyze → Enhance
```bash
# First understand current state
context-forge analyze

# Then plan improvements
context-forge enhance
```

### 2. Analyze → Migrate
```bash
# Analyze current stack
context-forge analyze

# Plan migration based on analysis
context-forge migrate
```

### 3. Continuous Workflow
```bash
# Regular analysis cycle
context-forge analyze        # Understand
context-forge enhance       # Improve
context-forge analyze       # Verify
```

## Next Steps

After analysis:

1. **Review Generated Documentation**
   - Check CLAUDE.md accuracy
   - Validate detected patterns
   - Confirm tech stack

2. **Enable AI Features**
   - Test slash commands
   - Configure hooks
   - Set up checkpoints

3. **Plan Improvements**
   - Address quality issues
   - Implement suggestions
   - Track metrics

4. **Share Knowledge**
   - Distribute docs to team
   - Create onboarding guides
   - Update regularly