improve-codebase-architecture

Scan a codebase for shallow modules and present deepening refactors as a visual HTML report.

Updated Aug 5, 2026
One-click install
npx skills add https://github.com/pd-phuc/laravel-template --skill improve-codebase-architecture-pd-phuc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/pd-phuc/laravel-template/tree/main/.claude/skills/improve-codebase-architecture
Command: npx skills add https://github.com/pd-phuc/laravel-template --skill improve-codebase-architecture-pd-phuc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making them hard to test and navigate. This Skill surfaces that architectural friction and proposes concrete deepening refactors instead of vague cleanup advice. ## Core Features & Use Cases - Architecture exploration: Uses an Explore subagent to find shallow modules, leaking seams, and untestable code, applying the deletion test to validate candidates. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory with Tailwind and Mermaid diagrams showing before/after visualizations, recommendation strength badges, and a top recommendation. - Guided design grilling: After you pick a candidate, runs a grilling loop to walk constraints, dependencies, and the shape of the deepened module, updating CONTEXT.md and offering ADRs for load-bearing rejections. - Use Case: Point it at a Laravel or similar codebase where order intake logic is scattered across handlers, validators, and repositories; it renders a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the AI to review this codebase for architecture improvements and show me the deepening opportunities as a report.

Frequently Asked Questions about improve-codebase-architecture

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

FAQPage Schema
How do I find shallow modules in my codebase?▼

Run this Skill to launch an Explore subagent that walks the codebase looking for modules whose interfaces are nearly as complex as their implementations. It applies the deletion test to confirm whether removing a module would concentrate complexity rather than just move it.

How to visualize architecture refactoring opportunities?▼

The Skill writes a self-contained HTML report to the OS temp directory using Tailwind and Mermaid from CDNs. Each candidate gets a before/after diagram, problem and solution statements, and a recommendation strength badge of Strong, Worth exploring, or Speculative.

What is a deep module versus a shallow module?▼

A deep module has a small interface hiding a substantial implementation, while a shallow module's interface nearly matches its implementation. The Skill uses this vocabulary from the companion codebase-design skill, along with terms like seam, adapter, leverage, and locality.

Does the architecture review modify my repository files?▼

The HTML report is written to the OS temp directory, not the repo, so nothing lands in your project. It may update CONTEXT.md with new domain terms and offer to record ADRs only when a rejected candidate has a load-bearing reason worth preserving.

What happens after I pick a refactoring candidate?▼

The Skill runs a grilling loop that walks the design tree with you, covering constraints, dependencies, the deepened module's shape, and which tests survive. It can also invoke a design-it-twice pattern with parallel subagents to explore alternative interfaces.