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

Flag	Description
--json	Output structured JSON instead of markdown, save to .claude/analysis.json
--quick	Quick summary only (5-10 lines)
--focus <area>	Focus analysis: arch, deps, quality, patterns

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:

Pattern	Recommended Skill	Priority
nextjs + vercel-config	project:deploy	high
prisma OR drizzle	project:db-migrate	high
supabase	project:supabase-sync	medium
docker-compose	project:docker-dev	medium
feature-flags	project:feature-toggle	low

Pattern	Recommended Agent
Large codebase (>100 files)	performance-optimizer
React/Vue components	accessibility-guardian
API routes	api-designer
Security-sensitive	security-auditor
Low test coverage	test-writer-fixer

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