improve-codebase-architecture

Identify shallow modules and propose deepening refactors using module, interface, seam, and adapter language.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/kileroppo/AI-Coding-Guidance-Skills --skill improve-codebase-architecture-kileroppo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/kileroppo/AI-Coding-Guidance-Skills/tree/main/skills/improve-codebase-architecture
Command: npx skills add https://github.com/kileroppo/AI-Coding-Guidance-Skills --skill improve-codebase-architecture-kileroppo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Software architectures often accumulate shallow modules where behavior is spread across callers, tests don’t validate the real interface surface, and refactors become risky and expensive; this Skill helps you find deepening opportunities that concentrate complexity into well-shaped modules.

Core Features & Use Cases

  • Explore for friction: navigates the codebase to identify places where understanding requires bouncing across many modules, where interfaces are shallow, and where locality is missing.
  • Present deepening candidates: proposes architecture refactors as deepening opportunities, explicitly framed in terms of Module, Interface, Seam, Adapter, Depth, Leverage, and Locality.
  • Grill-and-crystallize design: runs an interactive deepening conversation with constraints, dependency categories, seam placement, and test surface decisions; can also delegate to interface redesign via a parallel sub-agent pattern.

What problem does it solve?

When a codebase is hard to change safely—because tests don’t capture the real contract, seams are unclear, and behavior leaks across boundaries—this Skill helps you reshape the architecture so refactoring becomes localized and verification becomes interface-driven.

Quick Start

Ask the agent to improve architecture by exploring the most test-fragile or shallow modules and proposing concrete deepening candidates for the areas you care about most.

Frequently Asked Questions about improve-codebase-architecture

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

FAQPage Schema
How do I refactor shallow modules to make my codebase more testable?

Shallow modules force you to bounce across many files to understand behavior and make tests fragile. You can identify them by looking for architectural friction where interfaces lack depth, locality is missing, and tests fail to validate the real interface surface.

What is the best way to design seams and adapters for a fragile codebase?

Yes, you can use a parallel sub-agent pattern to delegate interface redesign during the deepening conversation. This allows the architecture exploration to run an interactive grilling loop for seam placement and test surface decisions while delegating interface shaping concurrently.

How do I plan refactoring when tests don't capture the real contract?

Plan refactoring by exploring the codebase for test-fragile areas and proposing concrete deepening candidates. Reshape the architecture so refactoring becomes localized and verification becomes interface-driven, ensuring tests validate the actual contract rather than shallow implementation details.

When should I not use deepening to restructure my codebase architecture?

You should avoid deepening when shallow modules do not cause architectural friction or when behavior is already concentrated in well-shaped modules. If refactoring is safe, tests validate the real interface surface, and understanding does not require bouncing across boundaries, restructuring adds unnecessary risk.