Codebase Explorer Skill

A collection of bash scripts and methodology for exploring and analyzing Java codebases.

Purpose

This skill provides automated analysis capabilities for understanding the structure, patterns, and key components of Java projects. It works with both Maven and Gradle build systems.

Scripts

All scripts are located in scripts/ and can be run independently:

Script Details

analyze-structure.sh

Provides an overall view of the codebase including:

• •Module/project structure
• •Package organization
• •Lines of code by type (Java, XML, YAML, etc.)
• •Frameworks and technologies detected

find-entrypoints.sh

Identifies all entry points where execution begins:

• •Main classes with public static void main
• •@SpringBootApplication annotations
• •@RestController and @Controller classes
• •@Scheduled methods
• •@KafkaListener and message consumers
• •Event handlers

dep-graph.sh

Analyzes project dependencies:

• •External dependencies from Maven/Gradle
• •Internal package dependencies
• •Module inter-dependencies (for multi-module projects)

hot-files.sh

Finds the most important files to understand:

• •Most-imported classes (high coupling)
• •Largest files by line count
• •Files with most git commits (high churn)
• •Files with most TODOs/FIXMEs

find-god-classes.sh

Detects code smells indicating over-sized classes:

• •Classes with >500 lines
• •Classes with >20 methods
• •Classes with >30 imports
• •Classes with many injected dependencies

find-circular-deps.sh

Identifies coupling issues:

• •Bidirectional package dependencies
• •Circular dependency chains (A→B→C→A)

map-vertical-slice.sh

Given an entity name, traces the full stack:

• •Controller → Service → Repository → Entity → Database table
• •Shows the complete data flow

find-seams.sh

Identifies natural module boundaries:

• •Domain clusters (related packages)
• •API groupings
• •Event handlers
• •External client packages
• •Low-coupling packages (potential extraction candidates)

Usage Notes

1. •Default Path: All scripts default to current directory if no path provided
2. •Build System: Scripts auto-detect Maven (pom.xml) vs Gradle (build.gradle)
3. •Git: Some features require git history (hot-files)
4. •Platform: Works on Mac and Linux

Methodology

When exploring a new codebase, use scripts in this order:

1. •Start with structure: analyze-structure.sh - Get the lay of the land
2. •Find entry points: find-entrypoints.sh - Know where to start reading
3. •Understand dependencies: dep-graph.sh - Know what external libs are used
4. •Identify key files: hot-files.sh - Focus on what matters
5. •Check for issues: find-god-classes.sh, find-circular-deps.sh - Know the pain points
6. •Trace flows: map-vertical-slice.sh - Understand end-to-end data flow
7. •Find boundaries: find-seams.sh - Understand module organization

Integration

These scripts are used by:

• •codebase-cartographer agent for high-level mapping
• •module-archaeologist agent for deep dives
• •onboarding-orchestrator agent during Phase 2 (Cartography)

Requirements

• •Bash 4.0+
• •Standard Unix tools (find, grep, awk, sed, sort, uniq)
• •Git (for history-based analysis)
• •No additional dependencies