psousa50 avatar

codebase-analyzer

Analyzes a project and generates CLAUDE.md and skills with project knowledge

Install

/plugin install codebase-analyzer@psousa50-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add psousa50/claude-plugins.

Contents

Discovered from source

Commands 3

/analyze

Analyze a project's codebase and generate CLAUDE.md and skills with project knowledge.

Analyze the current project and generate CLAUDE.md and relevant skills.

Instructions

Phase 1: Discovery

Run the discovery agent to detect what aspects exist in this project:

  • api
  • database
  • tests
  • frontend
  • backend
  • infrastructure
  • documentation

Phase 2: Analysis

Based on discovery results, run only the relevant analyzers in parallel:

DetectedAgent
apiapi-analyzer
databasedatabase-analyzer
teststests-analyzer
frontendfrontend-analyzer
backendarchitecture-analyzer
infrastructureinfrastructure-analyzer

Always run:

  • architecture-analyzer — overall structure
  • patterns-analyzer — code patterns
  • build-analyzer — build/dev workflow

Phase 3: Generate CLAUDE.md

Create CLAUDE.md in the project root directory (not in .claude/) combining findings:

# Project: [name]

## Overview
[1-2 sentences describing what this project does]

## Tech Stack
[Key technologies and frameworks]

## Architecture
[From architecture-analyzer]

## Directory Structure
[Key folders and their purposes]

## Development
[From build-analyzer - install, run, test, build commands]

## Key Patterns
[From patterns-analyzer - important conventions to follow]

## Key Files
[Critical files for understanding the project]

Phase 4: Report

Summarize:

  • What aspects were detected
  • What skills were generated in .claude/skills/
  • Any notable findings or recommendations

/update-architecture

Update or create ARCHITECTURE.md by exploring the codebase and documenting its structure.

Instructions

Phase 1: Read Current State

Run in parallel:

  • Read ARCHITECTURE.md from the project root (if it exists)
  • Scan the project root for config files, entry points, and directory structure

If ARCHITECTURE.md exists, note its current structure — preserve the same sections and ordering unless the codebase has diverged.

Phase 2: Explore

Run exploration agents in parallel to map the codebase:

  • Server-side: entry points, modules, classes, key abstractions, database schema
  • Client-side: framework, routing, components, state management, hooks
  • Configuration: environment variables, build setup, auth

Focus on structure and relationships, not implementation details. The goal is a map, not a manual.

Phase 3: Diff Against Current

If ARCHITECTURE.md already exists, identify:

  • New — files, modules, routes, or patterns not yet documented
  • Changed — documented items whose role or structure has shifted
  • Removed — documented items that no longer exist
  • Unchanged — skip these entirely

If creating from scratch, skip this phase.

Phase 4: Write ARCHITECTURE.md

Write ARCHITECTURE.md at the project root covering:

  1. One-line overview — what the app is
  2. Tech stack — key technologies (one line)
  3. Directory structure — annotated tree, one-liner per file/folder explaining its role
  4. Data flow — how data moves through the system (pipeline style)
  5. Database schema — tables and relationships (if applicable)
  6. API surface — REST routes and real-time events (if applicable)
  7. Configuration — provider abstractions, env vars, feature toggles
  8. Auth — authentication approach (if applicable)
  9. Key patterns — architectural decisions and conventions

Rules:

  • No code snippets — describe, don't duplicate
  • No implementation details — focus on what each module does, not how
  • Keep it under 150 lines
  • Use consistent formatting: headers, tables, annotated trees

Phase 5: Ensure CLAUDE.md References

Read CLAUDE.md from the project root. Ensure it contains both of these lines:

Read ARCHITECTURE.md before planning features.
Update ARCHITECTURE.md when making changes that affect its content.
  • If CLAUDE.md doesn't exist, create it with those two lines
  • If it exists but is missing either line, add the missing line(s) — don't remove or reorder existing content

Phase 6: Report

Show a brief summary of changes made:

  • Sections added or updated
  • Notable structural changes detected
  • Anything that looked ambiguous and may need manual review

/update

Update existing project skills and CLAUDE.md with the latest codebase information.

Instructions

Phase 1: Check Existing Skills

Read the current state:

  • Check which skills exist in .claude/skills/
  • Read CLAUDE.md from project root if it exists

Phase 2: Discovery

Run the discovery agent to detect current project aspects:

  • api, database, tests, frontend, backend, infrastructure, documentation

Compare with existing skills to identify:

  • Existing — skills that need updating
  • New — aspects detected but no skill exists yet
  • Stale — skills that exist but aspect no longer detected (warn user, don't delete)

Phase 3: Update Skills

For existing skills, run the relevant analyzer and update the skill:

  • Preserve any manual sections marked with <!-- manual --> comments
  • Update auto-generated content with fresh analysis

For new aspects, run the analyzer and create the skill.

For stale skills, warn the user but don't delete (they may have added them manually).

Phase 4: Update CLAUDE.md

Update CLAUDE.md in the project root directory:

  • Refresh all sections with latest information
  • Add sections for newly detected aspects
  • Keep the same structure

Phase 5: Report

Summarize:

  • Skills updated
  • New skills created
  • Stale skills detected (if any)
  • Key changes since last analysis

Agents 9

API Analyzer

Analyze API structure and generate an API skill.

Instructions

Explore the codebase to understand:

  • API architecture (REST, GraphQL, RPC)
  • Route organization and naming
  • Request/response patterns
  • Authentication/authorization approach
  • Error handling patterns
  • Middleware usage
  • API versioning

Look for:

  • Route definitions and handlers
  • Request validation
  • Response formatting
  • Auth middleware
  • Rate limiting
  • API documentation (OpenAPI, Swagger)

Create the folder .claude/skills/api/ and generate SKILL.md inside it:

---
name: api
description: Explains this project's API structure, endpoints, and patterns
---

# API Guide

## Architecture
[REST/GraphQL/RPC and overall structure]

## Endpoints
[Key endpoints and their purposes]

## Authentication
[How auth works]

## Request/Response Patterns
[Common patterns used]

## Error Handling
[How errors are handled and returned]

## Adding New Endpoints
[How to add a new endpoint following project patterns]

Return a summary of the API findings.

Architecture Analyzer

Analyze project architecture and generate an architecture skill.

Instructions

Explore the codebase to understand:

  • Directory structure and organisation
  • Key components/modules and their responsibilities
  • Entry points (main files, index files, app entry)
  • Data flow between components
  • External dependencies and integrations

Look for:

  • src/, lib/, app/, packages/ directories
  • Configuration files (tsconfig, webpack, vite, etc.)
  • Module boundaries and imports
  • API routes or endpoints
  • Database models or schemas

Create the folder .claude/skills/architecture/ and generate SKILL.md inside it:

---
name: architecture
description: Explains this project's architecture, components, and data flow
---

# Architecture

## Overview
[What this project does and its main purpose]

## Components
[List key components with their responsibilities]

## Directory Structure
[Important folders and what they contain]

## Data Flow
[How data moves through the system]

## Key Files
[Critical files and their purposes]

Return a summary of the architecture findings.

Build Analyzer

Analyze build process and generate a build skill.

Instructions

Explore the codebase to understand:

  • How to install dependencies
  • How to run the project locally
  • How to run tests
  • How to build for production
  • Environment setup requirements
  • CI/CD configuration

Look for:

  • package.json scripts
  • Makefile, Taskfile, or similar
  • pyproject.toml, Cargo.toml, go.mod
  • Dockerfile, docker-compose.yml
  • .env.example or environment documentation
  • CI config (.github/workflows, .gitlab-ci.yml, etc.)
  • README setup instructions

Create the folder .claude/skills/build/ and generate SKILL.md inside it:

---
name: build
description: Explains how to build, test, and develop this project
---

# Build & Development

## Prerequisites
[Required tools and versions]

## Installation
[How to install dependencies]

## Running Locally
[How to start the development server]

## Testing
[How to run tests]

## Building
[How to build for production]

## Environment Variables
[Required env vars and their purpose]

## Common Tasks
[Frequently used commands]

Return a summary of the build process.

Database Analyzer

Analyze database structure and generate a database skill.

Instructions

Explore the codebase to understand:

  • Database type (SQL, NoSQL, etc.)
  • ORM/query builder used
  • Schema organization
  • Migration patterns
  • Relationships between entities
  • Query patterns
  • Connection management

Look for:

  • Schema definitions
  • Model files
  • Migration files
  • Seed files
  • Database configuration
  • Query helpers/utilities

Create the folder .claude/skills/database/ and generate SKILL.md inside it:

---
name: database
description: Explains this project's database schema, models, and data patterns
---

# Database Guide

## Technology
[Database type and ORM/tools used]

## Schema Overview
[Key tables/collections and their purposes]

## Relationships
[How entities relate to each other]

## Migrations
[How migrations work]

## Query Patterns
[Common query patterns used]

## Adding New Models
[How to add a new model/table following project patterns]

Return a summary of the database findings.

Discovery Agent

Discover what aspects exist in this project to determine which analyzers to run.

Instructions

Quickly scan the project to detect:

  • api — REST/GraphQL endpoints, route handlers, controllers
  • database — ORM, migrations, models, schema files
  • tests — test files, test config, testing frameworks
  • frontend — UI components, pages, styles, assets
  • backend — server code, services, middleware
  • infrastructure — Docker, CI/CD, deployment configs
  • documentation — README, docs folder, API docs

Look for indicators:

  • routes/, api/, controllers/ → api
  • models/, migrations/, schema/, prisma, drizzle, sequelize → database
  • test/, tests/, __tests__/, *.test.*, *.spec.*, jest, vitest, pytest → tests
  • components/, pages/, views/, styles/ → frontend
  • services/, middleware/, server/ → backend
  • Dockerfile, .github/workflows/, docker-compose → infrastructure
  • docs/, README.md, swagger/openapi → documentation

Return a JSON object:

{
  "detected": ["api", "database", "tests", "frontend"],
  "summary": "Brief description of what was found"
}

Frontend Analyzer

Analyze frontend structure and generate a frontend skill.

Instructions

Explore the codebase to understand:

  • Framework (React, Vue, Svelte, etc.)
  • Component organization
  • State management
  • Routing approach
  • Styling solution
  • Build tooling

Look for:

  • Component files
  • Page/route components
  • State management setup
  • Style files/configuration
  • Build configuration

Create the folder .claude/skills/frontend/ and generate SKILL.md inside it:

---
name: frontend
description: Explains this project's frontend architecture, components, and UI patterns
---

# Frontend Guide

## Framework
[Framework and key libraries]

## Component Structure
[How components are organized]

## State Management
[How state is managed]

## Routing
[How routing works]

## Styling
[Styling approach and conventions]

## Creating Components
[How to create new components following project patterns]

Return a summary of the frontend findings.

Infrastructure Analyzer

Analyze infrastructure and generate an infrastructure skill.

Instructions

Explore the codebase to understand:

  • Containerization (Docker)
  • CI/CD pipelines
  • Deployment configuration
  • Environment management
  • Cloud services used
  • Monitoring/logging setup

Look for:

  • Dockerfile, docker-compose
  • CI config (.github/workflows, .gitlab-ci, etc.)
  • Deployment scripts
  • Environment files
  • Infrastructure as code (Terraform, Pulumi, etc.)

Create the folder .claude/skills/infrastructure/ and generate SKILL.md inside it:

---
name: infrastructure
description: Explains this project's infrastructure, deployment, and DevOps setup
---

# Infrastructure Guide

## Containerization
[Docker setup and usage]

## CI/CD
[Pipeline configuration and stages]

## Deployment
[How to deploy]

## Environments
[Environment configuration]

## Monitoring
[Logging and monitoring setup]

Return a summary of the infrastructure findings.

Patterns Analyzer

Analyze coding patterns and generate a patterns skill.

Instructions

Explore the codebase to identify:

  • Naming conventions (files, functions, variables, classes)
  • Code organisation patterns
  • Design patterns used (MVC, repository, factory, singleton, etc.)
  • Error handling approach
  • State management patterns (if frontend)
  • API patterns (if backend)
  • Testing patterns

Look at:

  • Multiple source files to identify consistent patterns
  • How errors are handled and propagated
  • How state is managed and shared
  • How dependencies are injected or managed
  • Code style (functional vs OOP, etc.)

Create the folder .claude/skills/patterns/ and generate SKILL.md inside it:

---
name: patterns
description: Explains coding patterns and conventions used in this project
---

# Code Patterns

## Naming Conventions
[File naming, function naming, variable naming]

## Design Patterns
[Patterns used and where]

## Error Handling
[How errors are handled]

## State Management
[How state is managed - if applicable]

## Code Style
[Functional vs OOP, formatting conventions]

## Examples
[Brief code examples demonstrating key patterns]

Return a summary of the patterns found.

Tests Analyzer

Analyze testing structure and generate a tests skill.

Instructions

Explore the codebase to understand:

  • Testing framework(s) used
  • Test organization (unit, integration, e2e)
  • Test file naming conventions
  • Mocking patterns
  • Test utilities and helpers
  • Coverage configuration
  • CI test setup

Look for:

  • Test files and directories
  • Test configuration files
  • Mock/fixture files
  • Test utilities
  • Coverage reports/config

Create the folder .claude/skills/tests/ and generate SKILL.md inside it:

---
name: tests
description: Explains this project's testing patterns, structure, and how to write tests
---

# Testing Guide

## Framework
[Testing framework and tools used]

## Structure
[How tests are organized]

## Running Tests
[Commands to run tests]

## Writing Tests
[Patterns and conventions for writing tests]

## Mocking
[How to mock dependencies]

## Test Utilities
[Available test helpers and utilities]

Return a summary of the testing findings.

Sponsors

Details

Marketplace
psousa50/claude-plugins
Source
plugins/codebase-analyzer
Category
Community

More from psousa50/claude-plugins

All 5