codebase-analysis
This skill should be used when the user asks about "analyzing codebase", "understanding project structure", "code exploration", "architecture discovery", "codebase patterns", or needs to systematically analyze and document a codebase's organization and conventions.
When & Why to Use This Skill
This Claude skill provides a systematic framework for analyzing and documenting codebases of any complexity. It automates the discovery of project structures, technical stacks, and coding conventions, helping developers and AI agents rapidly gain architectural insights and maintain consistency across large-scale software projects. By utilizing strategic sampling and parallel analysis tracks, it transforms raw source code into structured knowledge.
Use Cases
- Rapid Onboarding: Quickly understand the organization, dependencies, and entry points of an unfamiliar codebase to reduce ramp-up time.
- Architecture Discovery: Map out directory structures and module relationships to visualize the high-level design and hierarchy of a system.
- Convention Detection: Identify and document coding patterns, state management strategies, and naming conventions to ensure team alignment and code quality.
- Monorepo Management: Analyze workspace configurations and internal package dependencies in complex environments like pnpm, yarn, or nx.
- Technical Debt Auditing: Systematically flag inconsistencies in patterns and potential error locations to prioritize refactoring efforts.
| name | Codebase Analysis |
|---|---|
| description | This skill should be used when the user asks about "analyzing codebase", "understanding project structure", "code exploration", "architecture discovery", "codebase patterns", or needs to systematically analyze and document a codebase's organization and conventions. |
| version | 1.0.0 |
Codebase Analysis Skill
This skill provides systematic approaches to analyzing and understanding codebases of any size and complexity.
Analysis Strategy by Project Size
Small (<50 files): Comprehensive scan of all files
Medium (50-500 files): Representative sampling per category
Large (>500 files): Strategic sampling of key areas
Parallel Analysis Tracks
Run these tracks concurrently for efficiency:
Track 1: Product Understanding
# Files to examine:
- README.md, README*.md
- package.json "description" field
- docs/ or documentation/ folder
- Main entry points (index.ts, main.ts, app.ts)
- API documentation
Track 2: Technical Stack Discovery
# Configuration files:
- package.json (dependencies, devDependencies, scripts)
- tsconfig.json / jsconfig.json
- Build configs: vite.config.*, webpack.config.*, rollup.config.*
- Test configs: jest.config.*, vitest.config.*
- Linter configs: .eslintrc.*, eslint.config.*
- Formatter configs: .prettierrc.*, prettier.config.*
Track 3: Structure Mapping
# Analyze:
- Top-level directories (src/, lib/, packages/, apps/)
- 2-3 representative files per major directory
- Naming conventions (kebab-case, camelCase, PascalCase)
- Module organization patterns
- Index/barrel files
Track 4: Convention Detection
# Patterns to identify:
- Export style: named vs default exports
- Component patterns: functional vs class, HOCs
- State management: Redux, Zustand, Context
- Testing patterns: unit, integration, e2e
- Error handling: try/catch, Result types, error boundaries
Analysis Output Templates
Package Analysis
## Package: {name}
**Purpose**: {description}
**Type**: Library | Application | CLI | Framework
**Entry**: {main entry point}
### Dependencies
- Production: {count} packages
- Development: {count} packages
- Key deps: {list critical dependencies}
### Scripts
| Script | Command | Purpose |
|--------|---------|---------|
| dev | {cmd} | Development server |
| build | {cmd} | Production build |
| test | {cmd} | Run tests |
Directory Analysis
## Directory: {path}
**Purpose**: {description}
**Pattern**: {naming convention}
**File Count**: {count}
### Structure
{tree representation, 2-3 levels}
### Key Files
| File | Purpose |
|------|---------|
| {file} | {purpose} |
Convention Analysis
## Detected Conventions
### Confirmed Patterns
- {Pattern}: {evidence} (found in X% of files)
### Inconsistencies
⚠️ {Pattern}: {variant1} ({X%}) vs {variant2} ({Y%})
Recommendation: Standardize on {recommended}
Monorepo Analysis
For monorepos (pnpm workspaces, yarn workspaces, nx, turborepo):
## Monorepo Structure
### Workspace Configuration
- Tool: {pnpm/yarn/npm/nx/turborepo}
- Config: {workspace config file}
### Packages
| Package | Type | Dependencies |
|---------|------|--------------|
| {name} | {lib/app} | {internal deps} |
### Build Order
1. {package1} (no deps)
2. {package2} (depends on 1)
3. {package3} (depends on 1, 2)
### Shared Configuration
- TypeScript: {shared tsconfig}
- Testing: {shared test config}
- Linting: {shared lint config}
Error Patterns to Flag
## Issues Detected
### Critical
❌ {issue}: {description}
Location: {file:line}
Impact: {impact}
### Warning
⚠️ {issue}: {description}
Location: {file:line}
Recommendation: {fix}
### Info
ℹ️ {observation}
Integration with Steering Workflow
When used during /steering:
- Phase 2 uses this skill for systematic codebase exploration
- Product track extracts README and documentation
- Tech track discovers dependencies and build tools
- Structure track maps directories and patterns
- Convention track identifies code style rules
Best Practices
- Sample Strategically: Don't read every file; pick representative samples
- Parallel Execution: Run independent analyses concurrently
- Evidence-Based: Document where patterns were observed
- Mark Uncertainty: Use ⚠️ for unclear or conflicting patterns
- Actionable Output: Focus on patterns AI agents need to follow