improve-codebase-architecture

Identifies module deepening opportunities and proposes architecture refactors for testability.

20|2|Updated May 16, 2026
One-click install
npx skills add https://github.com/reddb-io/red-skills --skill improve-codebase-architecture-reddb-io
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/reddb-io/red-skills/tree/main/plugins/dev/skills/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/reddb-io/red-skills --skill improve-codebase-architecture-reddb-io

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making them hard to test, navigate, and refactor. This Skill surfaces that architectural friction and proposes deepening refactors that consolidate tightly-coupled modules behind small, high-leverage interfaces. ## Core Features & Use Cases - Friction Exploration: Uses an Explore sub-agent to walk the codebase and detect shallow modules, pass-through abstractions, and untestable seams, applying the deletion test to validate candidates. - Candidate Presentation: Produces a numbered list of deepening opportunities with files, problems, solutions, and benefits framed in terms of locality and leverage, using the project's domain vocabulary from .red/CONTEXT.md and respecting existing ADRs. - Interactive Grilling Loop: Walks the design tree with the user, classifying dependencies (in-process, local-substitutable, remote-but-owned, true-external) to define seam and testing strategy, and can spawn parallel sub-agents to design alternative interfaces. - Use Case: A team notices that understanding order intake requires bouncing between six small classes. The Skill explores the code, proposes merging them into one deep Order intake module, and helps design its interface and test strategy. ## Quick Start Ask the assistant to explore this codebase and find architecture deepening opportunities that would make it more testable.

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 an Explore sub-agent that notes friction points: shallow modules, pass-through abstractions, and hard-to-test interfaces. It presents a numbered list of deepening candidates with files, problems, and benefits before proposing any interfaces.

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 earns little. The deletion test checks whether removing a module concentrates complexity or just moves it.

Does this Skill work with existing architecture decision records?▼

Yes, it reads ADRs in .red/adr/ before suggesting changes and avoids re-litigating recorded decisions. If a candidate contradicts an ADR, it only surfaces the conflict when the friction justifies reopening it, and it can offer to record new ADRs when candidates are rejected for load-bearing reasons.

How are deepened modules tested across their seams?▼

Dependencies are classified as in-process, local-substitutable, remote-but-owned, or true-external, which determines the adapter and testing strategy. New tests are written at the deepened module's interface, and old unit tests on the shallow modules are deleted rather than layered.

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

Do not introduce a seam unless at least two adapters are justified, typically production plus test. A single-adapter seam is hypothetical indirection that adds interface complexity without hiding any real variation.