Analyze Project

Analyze Project

Overview

Perform deep analysis of a codebase to understand its architecture, patterns, dependencies, and opportunities for improvement.

Core principle: Understand before changing. Map before navigating.

Trigger: /popkit:project analyze command or when starting work on unfamiliar project

Arguments

Analysis Areas

1. Project Structure

Directory structure, entry points, file counts by type.

2. Technology Stack

Package managers, frameworks (Next.js, React, Vue, Express, FastAPI, Rust), databases (Supabase, Prisma, MongoDB, PostgreSQL).

3. Architecture Patterns

Frontend (component structure, state management, routing), Backend (API design, service layer, database access), Common (error handling, logging, configuration).

4. Code Quality

Linting config, TypeScript strictness, TODO/FIXME comments.

5. Testing Coverage

Test files, test frameworks, coverage reports.

6. Dependencies

Count, outdated packages, security vulnerabilities.

7. CI/CD and DevOps

CI config, Docker, deployment configuration.

Output Format

Markdown Report

# [Project Name] Analysis Report

## Summary

- **Type**: [Web App / API / CLI / Library]
- **Stack**: [Primary technologies]
- **Size**: [Files, Lines of code]
- **Health**: [Good / Needs attention / Critical issues]

## Technology Stack

### Frontend

- Framework: [Next.js 14 / React / Vue / etc.]
- Styling: [Tailwind / styled-components / etc.]
- State: [Redux / Zustand / Context]

### Backend

- Runtime: [Node.js / Python / Rust / Go]
- Framework: [Express / FastAPI / Actix]
- Database: [PostgreSQL / MongoDB / etc.]

### DevOps

- CI/CD: [GitHub Actions / GitLab CI / etc.]
- Deployment: [Vercel / AWS / etc.]
- Container: [Docker / etc.]

## Architecture

### Key Patterns

- [Pattern 1]: [Where used]
- [Pattern 2]: [Where used]

### Entry Points

- Main: `[path]`
- API: `[path]`
- Tests: `[path]`

## Code Quality

| Metric            | Value                | Status       |
| ----------------- | -------------------- | ------------ |
| Linting           | [Configured/Missing] | [OK/Warning] |
| TypeScript Strict | [Yes/No]             | [OK/Warning] |
| Test Coverage     | [X%]                 | [OK/Warning] |
| TODO Comments     | [N]                  | [OK/Warning] |

## Recommendations

### Critical

1. [Issue requiring immediate attention]

### High Priority

1. [Important improvement]

### Nice to Have

1. [Enhancement suggestion]

## Next Steps

1. Run `/generate-mcp` to create project-specific tools
2. Run `/generate-skills` to capture discovered patterns
3. Run `/setup-precommit` to configure quality gates

JSON Output

When --json flag is provided, saves to .claude/analysis.json:

{
  "project_name": "project-name",
  "project_type": "nextjs",
  "analyzed_at": "2026-01-30T00:00:00Z",
  "frameworks": [{ "name": "nextjs", "confidence": 0.95, "version": "14.0.0" }],
  "patterns": [
    {
      "name": "pattern-name",
      "category": "architecture",
      "confidence": 0.85,
      "examples": ["path1", "path2"],
      "description": "Description"
    }
  ],
  "recommended_skills": ["skill1", "skill2"],
  "recommended_agents": ["agent1", "agent2"],
  "commands": {},
  "quality_metrics": {}
}

Skill/Agent Recommendations

Based on detected patterns:

Integration

Called by:

• Manual /analyze-project command
• After /init-project

Informs:

• /generate-mcp - What tools to create
• /generate-skills - What patterns to capture
• /setup-precommit - What checks to configure