improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors to improve testability and locality.

Updated May 10, 2026
One-click install
npx skills add https://github.com/rexshihaoren/rexy_vibing_setup --skill improve-codebase-architecture-rexshihaoren
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/rexshihaoren/rexy_vibing_setup/tree/main/docs/ai/skills/improve-codebase-architecture
Command: npx skills add https://github.com/rexshihaoren/rexy_vibing_setup --skill improve-codebase-architecture-rexshihaoren

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, spreading bugs and knowledge across callers and making code hard to test and navigate. This Skill surfaces that architectural friction and proposes deepening refactors grounded in the project's own domain language and recorded decisions. ## Core Features & Use Cases - Deepening Opportunity Discovery: Explores the codebase with sub-agents to find shallow modules, pass-throughs, and tightly-coupled seams, applying the deletion test to validate each candidate. - Consistent Architecture Vocabulary: Enforces a shared glossary (module, interface, depth, seam, adapter, leverage, locality) so every suggestion uses the same precise terms. - Parallel Interface Design: Spawns multiple sub-agents to produce radically different interface designs for a chosen candidate, then compares them by depth, locality, and seam placement. - Use Case: A developer suspects their service layer is a tangle of small, hard-to-test functions. The Skill explores the repo, presents a numbered list of deepening candidates with files, problems, and benefits, then grills the user through the design of the chosen refactor while updating CONTEXT.md and offering ADRs for rejected options. ## Quick Start Ask the agent to explore this codebase and propose deepening opportunities to improve its architecture and testability.

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 refactoring opportunities in a codebase?▼

Use this Skill to explore the codebase with sub-agents and detect shallow modules whose interfaces rival their implementations in complexity. It applies the deletion test to each candidate and presents a numbered list of deepening opportunities with files, problems, and benefits.

What is a deep module versus a shallow module?▼

A deep module hides a large amount of behavior behind a small interface, giving callers leverage and maintainers locality. A shallow module has an interface nearly as complex as its implementation, so deleting it just moves complexity rather than concentrating it.

How do I design alternative interfaces for a module?▼

The Skill spawns three or more parallel sub-agents, each given a different design constraint such as minimizing the interface or optimizing for the most common caller. It then presents and compares the designs by depth, locality, and seam placement, with an opinionated recommendation.

Does this Skill work with existing ADRs and domain glossaries?▼

Yes, it reads CONTEXT.md and docs/adr/ before exploring and uses that vocabulary in every suggestion. Candidates that contradict an ADR are only surfaced when the friction justifies reopening the decision, and are clearly marked.

When should I not introduce a new seam or port?▼

Avoid introducing a port when only one adapter exists, since a single-adapter seam is just indirection. The Skill's rule is that one adapter means a hypothetical seam while two adapters, typically production plus test, justify a real one.