improve-codebase-architecture

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

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

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 an Explore sub-agent to find shallow modules, pass-through abstractions, 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) grounded in LANGUAGE.md, and aligns suggestions with the project's CONTEXT.md domain language and existing ADRs. - Guided Design Exploration: Runs a grilling conversation per candidate, supports parallel sub-agents that design radically different interfaces (Design It Twice), and classifies dependencies to choose the right testing strategy across seams. - Use Case: A team notices that understanding one order-processing flow requires jumping across eight small files. Use this Skill to identify the cluster, propose a deep Order intake module, explore alternative interfaces, and record rejected options as ADRs. ## Quick Start Ask the assistant to analyze this codebase for architecture improvement opportunities and present deepening candidates.

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 whose interfaces are nearly as complex as their implementations. It applies the deletion test to each candidate and presents a numbered list of deepening opportunities with files, problems, solutions, and benefits.

What is a deep module in software architecture?

A deep module hides a large amount of behaviour behind a small interface, giving callers leverage and maintainers locality. A shallow module is the opposite: its interface is nearly as complex as its implementation, so it earns little for the complexity it adds.

How do I design a better interface for a module?

The Skill spawns multiple parallel sub-agents that each produce a radically different interface under distinct constraints, such as minimizing entry points or optimizing the common caller. It then compares the designs by depth, locality, and seam placement and gives an opinionated recommendation.

Does this Skill work with existing architecture decision records?

Yes, 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, and it can offer to record new ADRs for rejected candidates.

When should I not introduce a new interface or seam?

Avoid introducing a seam when only one adapter would ever satisfy it, 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, mean a real one.