improve-codebase-architecture

Identify shallow modules and propose refactorings with Mermaid diagrams.

Updated Jun 12, 2026
One-click install
npx skills add https://github.com/Kushal9889/claude-plugins --skill improve-codebase-architecture-kushal9889
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Kushal9889/claude-plugins/tree/main/mattpocock-skills/skills/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/Kushal9889/claude-plugins --skill improve-codebase-architecture-kushal9889

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill identifies shallow modules in your codebase, proposes refactoring to deepen them, and guides you through the process to improve architecture and make the codebase more testable.

Core Features & Use Cases

  • Identifies Shallow Modules: Analyzes the codebase for modules with complex interfaces.
  • Proposes Deepening: Recommends refactorings to convert shallow modules into deep ones.
  • Architectural Review: Generates a comprehensive HTML report showcasing the architectural review, with diagrams and suggestions for improvement.
  • Interactive Guidance: Engages in an interactive loop to walk through the proposed changes, considering dependencies, constraints, and implementation details.

Quick Start

Use the 'improve-codebase-architecture' skill to generate an architectural review report for your codebase.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is a shallow module in codebase architecture and how do I identify it?

A shallow module in codebase architecture has a complex interface relative to its functionality. You can identify shallow modules by analyzing the codebase for modules where the interface complexity outweighs the hidden implementation details.

How do I refactor shallow modules to improve codebase testability and AI navigability?

To refactor shallow modules and improve codebase testability, you propose deepening the modules by simplifying their interfaces and moving complexity into the implementation. This process enhances both testability and AI navigability.

Can I generate a visual architectural review report for my codebase?

Yes, you can generate an architectural review report for your codebase. The report is output as a comprehensive HTML file showcasing dependency visualization through Mermaid diagrams and suggestions for architectural improvement.

Does this codebase refactoring guidance consider existing domain glossaries and architectural decisions?

Yes, the codebase refactoring guidance is informed by existing domain glossaries and architectural decisions. It engages in an interactive loop to walk you through proposed changes while considering dependencies and implementation constraints.

What is the best way to visualize codebase dependencies during an architectural review?

The best way to visualize codebase dependencies during an architectural review is using Mermaid diagrams. These diagrams are generated within an HTML report to map module relationships and guide refactoring efforts.

Are there limitations to using automated refactoring proposals for codebase architecture?

Automated refactoring proposals for codebase architecture are limited by the need for interactive guidance. You must manually walk through proposed changes, considering specific dependencies, constraints, and implementation details before applying them.