improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors to improve codebase testability and navigability.

Updated Jul 17, 2026
One-click install
npx skills add https://github.com/unnxt30/skills --skill improve-codebase-architecture-unnxt30
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/unnxt30/skills/tree/main/improve-codebase-architecture
Command: npx skills add https://github.com/unnxt30/skills --skill improve-codebase-architecture-unnxt30

SYSTEM DOCUMENTATION & REQUIREMENTS

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 that consolidate behaviour behind small, high-leverage interfaces. ## Core Features & Use Cases - Deepening Opportunity Discovery: Explores the codebase with sub-agents to find shallow modules, pass-through abstractions, and tightly-coupled seams, applying the deletion test to validate each candidate. - Structured Candidate Review: Presents numbered refactoring candidates with files, problems, solutions, and benefits framed in terms of leverage and locality, while respecting existing ADRs and domain vocabulary from CONTEXT.md. - Guided Design Conversation: Runs a grilling loop on the chosen candidate, updates CONTEXT.md with new domain terms, offers ADRs for rejected candidates, and supports parallel sub-agent exploration of alternative interface designs. - Use Case: A team struggling with scattered business logic across dozens of small functions uses this Skill to identify consolidation opportunities, then designs a single deep module with a minimal interface that tests can target directly. ## Quick Start Ask the assistant to analyze this codebase for architectural improvement opportunities and propose deepening refactors.

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 for shallow modules where the interface is nearly as complex as the implementation. 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 behaviour behind a small interface, giving callers high leverage. A shallow module has an interface nearly as complex as its implementation, so it adds indirection without hiding complexity.

How does this Skill handle existing architecture decision records?

It reads ADRs in docs/adr/ before proposing changes and avoids re-litigating recorded decisions. If a candidate contradicts an ADR, it only surfaces the conflict when the friction justifies reopening the decision, clearly marking the conflict.

When should I introduce a port and adapter at a seam?

Introduce a port only when at least two adapters are justified, typically a production adapter and a test adapter. A single-adapter seam is just indirection; the Skill treats one adapter as a hypothetical seam and two as a real one.

What happens to old unit tests after deepening modules?

Old unit tests on shallow modules are deleted once tests exist at the deepened module's interface. New tests assert observable outcomes through the interface, so they survive internal refactors and describe behaviour rather than implementation.