improve-codebase-architecture

Explores codebases to identify module-deepening refactors that improve testability and architecture.

1|Updated May 4, 2026
One-click install
npx skills add https://github.com/wesbragagt/nixos-config --skill improve-codebase-architecture-wesbragagt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/wesbragagt/nixos-config/tree/main/home/skills/improve-codebase-architecture
Command: npx skills add https://github.com/wesbragagt/nixos-config --skill improve-codebase-architecture-wesbragagt

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Codebases accumulate shallow, tightly-coupled modules that are hard to test, hard to navigate, and hide bugs in the seams between components. This Skill systematically explores a codebase to surface architectural friction and proposes concrete module-deepening refactors based on John Ousterhout's deep module philosophy. ## Core Features & Use Cases - Organic Codebase Exploration: Uses exploratory agents to find friction points where understanding one concept requires bouncing between many small files, or where modules are too shallow to test at their boundary. - Dependency Classification: Categorizes each candidate's dependencies into four types (in-process, local-substitutable, ports & adapters, true external) to determine the right deepening and testing strategy. - Parallel Interface Design: Spawns multiple sub-agents that each produce radically different interface designs for the deepened module, then compares them and gives an opinionated recommendation. - Use Case: A team has a service layer split across a dozen tiny modules with integration bugs in the seams. Use this Skill to identify the cluster, evaluate three alternative deep interfaces, and produce a refactor proposal with boundary tests replacing shallow unit tests. ## Quick Start Ask the assistant to explore this codebase and find opportunities to deepen shallow modules and improve testability.

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?

Explore the codebase organically and note where you experience friction: concepts scattered across many small files, modules whose interfaces rival their implementations in complexity, and tightly-coupled code with integration risk in the seams. That friction signals deepening candidates.

What is a deep module in software design?

A deep module, from John Ousterhout's A Philosophy of Software Design, has a small interface hiding a large implementation. Deep modules are more testable because you test at the boundary instead of inside, and they are easier to navigate.

How do I test modules with external dependencies like Stripe?

True external dependencies you do not control should be mocked at the boundary. The deepened module takes the external service as an injected port, and tests provide a mock implementation while production uses the real adapter.

Should I delete old unit tests after consolidating modules?

Yes, the strategy is replace, not layer. Old unit tests on shallow modules become waste once boundary tests exist. Write new tests at the deepened module's interface that assert observable outcomes and survive internal refactors.

When is module deepening not appropriate?

Deepening depends on the dependency category. In-process code is always deepenable, local-substitutable dependencies need a test stand-in, and remote owned services need a ports-and-adapters split. If no viable test strategy exists for the boundary, deepening may not pay off.