skills.rest
luizgmassa
luizgmassaCOMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

Identify deepening opportunities in codebases by analyzing module interfaces and testability.

Updated Aug 23, 2026
Search Tags:#refactoring#testability#codebase architecture#module deepening#ADR alignment#AI-navigable code#interfaces and seams
One-click install
npx skills add https://github.com/luizgmassa/Useful-Agent-Skills --skill improve-codebase-architecture-luizgmassa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/luizgmassa/Useful-Agent-Skills/tree/main/skills/improve-codebase-architecture
Command: npx skills add https://github.com/luizgmassa/Useful-Agent-Skills --skill improve-codebase-architecture-luizgmassa

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps you locate architectural friction in a codebase and convert shallow, hard-to-test modules into deep modules with clear interfaces and better test surfaces.

Core Features & Use Cases

  • Deepening opportunity discovery: identifies modules/interfaces that create friction, poor locality, or weak leverage for callers and tests.
  • Domain- and decision-aware exploration: uses the shared architecture vocabulary (module/interface/seam/adapter) and checks for conflicts with existing ADRs.
  • Interface-driven testing planning: reframes work around test surfaces at the module interface and uses the “deletion test” to find what’s truly earning its keep.
  • Optional interface iteration: can branch into alternative interface designs after a candidate is selected, using a parallel sub-agent approach.

Quick Start

Ask the skill to explore your repository and return a numbered list of deepening opportunities, then pick one candidate to grill with you.

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 for refactoring?▼

You can find shallow modules by exploring domain vocabulary and ADRs, then using the deletion test to identify interfaces that lack leverage and fail to earn their keep in the codebase architecture.

What is the best way to improve codebase architecture for AI navigability?▼

Improve codebase architecture for AI navigability by consolidating tightly coupled modules, refining interfaces and seams, and using a grilling loop to evaluate trade-offs and test surfaces.

How do I refactor tightly coupled modules to increase testability?▼

Refactor tightly coupled modules by identifying deepening opportunities, adjusting seam placement, and iterating on interface designs to increase testability and locality for callers and tests.

Does refactoring module interfaces require checking existing ADRs?▼

Checking existing ADRs is required when refactoring module interfaces to ensure domain-aware exploration, verify alignment with shared architecture vocabulary, and prevent conflicts during codebase architecture improvements.

When should I use the deletion test during codebase architecture refactoring?▼

You should use the deletion test during codebase architecture refactoring to detect shallow modules, verify that interfaces and seams are truly earning their keep, and identify valid deepening opportunities.

Related Skills

Explore More Software Engineering Skills→
JeromyJSmithJeromyJSmith
3

improve-codebase-architecture

Identify shallow modules and propose interface-focused refactoring candidates.

Community
Advanced
dimsourdimsour
2

brainstorm

Generate and analyze architectural design alternatives for .NET projects.

Community
Intermediate
kvithayathilkvithayathil

design-an-interface

Generate multiple interface designs for software modules and compare them against design criteria.

Community
Intermediate
delphicleancodedelphicleancode
48

ACBr Project Patterns

Decouple Delphi ACBr projects from VCL components using dependency injection and wrapper services.

Community
Advanced