skills.rest
zebbern
zebbernCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

deep-module-refactor

Explores codebases to find shallow modules and proposes module-deepening refactors as GitHub issue RFCs.

4.6k|462|Updated Jun 21, 2025
Search Tags:#testability#code exploration#Refactoring#Ports and Adapters#deep modules#gitHub issues#Software Architecture
One-click install
npx skills add https://github.com/zebbern/claude-code-guide --skill deep-module-refactor
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: deep-module-refactor
Source: https://github.com/zebbern/claude-code-guide/tree/main/skills/deep-module-refactor
Command: npx skills add https://github.com/zebbern/claude-code-guide --skill deep-module-refactor

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Shallow, tightly-coupled modules make codebases hard to test, hard to navigate, and risky to change. This Skill explores a codebase to surface architectural friction and turns refactoring opportunities into actionable GitHub issue RFCs.

Core Features & Use Cases

  • Organic Codebase Exploration: Uses an Explore sub-agent to navigate the code naturally, treating friction (bouncing between small files, untestable seams) as the signal for refactoring candidates.
  • Parallel Interface Design: Spawns 3+ sub-agents that each produce radically different interface designs for the deepened module, then compares them and gives an opinionated recommendation.
  • Dependency Classification: Categorizes dependencies as in-process, local-substitutable, ports & adapters, or external mocks, with a matching testing strategy for each.
  • Use Case: A team has dozens of small, tightly-coupled service modules with brittle unit tests. Use this Skill to identify deepening candidates, design a small interface hiding the merged implementation, and file a refactor RFC via gh issue create.

Quick Start

Ask the agent to explore this repository and propose module-deepening refactors that would make the codebase more testable.

Frequently Asked Questions about deep-module-refactor

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

FAQPage Schema
How do I find refactoring opportunities in a large codebase?▼

Use this Skill to explore the codebase with an Explore sub-agent that notes architectural friction, such as concepts split across many small files or modules whose interfaces rival their implementations. It presents a numbered list of deepening candidates for you to choose from.

What is a deep module in software design?▼

A deep module, from John Ousterhout's A Philosophy of Software Design, has a small interface hiding a large implementation. Deep modules are more testable and navigable because you test at the boundary instead of inside the implementation.

How does the Skill handle external dependencies during refactoring?▼

It classifies dependencies into four categories: in-process, local-substitutable, remote but owned (ports and adapters), and true external (mocked at the boundary). Each category has a matching testing strategy described in REFERENCE.md.

Does this refactoring approach delete existing unit tests?▼

Yes, the strategy is replace, not layer. Old unit tests on shallow modules are deleted once boundary tests exist, and new tests assert observable behavior through the deepened module's public interface so they survive internal refactors.

What is the output of the deep module refactor workflow?▼

The final output is a refactor RFC created as a GitHub issue using gh issue create. The issue follows a template covering the problem, proposed interface, dependency strategy, testing strategy, and implementation recommendations.

Related Skills

Explore More Software Engineering Skills→
notquenotque
415

codebase-overview

Analyze a repository's type, language, and architecture into a markdown report.

Community
Advanced
mia-cxmia-cx

codebase-architecture

Identify architectural friction and propose boundary-based refactors for shallow modules.

Official
Intermediate
ProgrammerAnthonyProgrammerAnthony
138

improve-codebase-architecture

Analyze code repositories to identify shallow modules, tight coupling, and testing barriers.

Community
Advanced
crgarcia12crgarcia12

rewrite-planner

Plan incremental component rewrites using the strangler fig pattern.

Community
Advanced