improve-codebase-architecture

Identifies refactoring opportunities that turn shallow modules into deep, testable modules.

60|11|Updated Jun 15, 2026
One-click install
npx skills add https://github.com/matyasstoch/david-skills --skill improve-codebase-architecture-matyasstoch
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/matyasstoch/david-skills/tree/main/skills/improve-codebase-architecture
Command: npx skills add https://github.com/matyasstoch/david-skills --skill improve-codebase-architecture-matyasstoch

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 architectural friction and proposes deepening opportunities that consolidate tightly-coupled modules behind small, high-leverage interfaces. ## Core Features & Use Cases - Architecture 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. - Structured candidate proposals: Presents numbered deepening opportunities with files, problems, solutions, and benefits framed in terms of leverage and locality, respecting existing ADRs and domain vocabulary from CONTEXT.md. - Interface design via parallel sub-agents: Generates multiple radically different interface designs for a chosen candidate and compares them by depth, locality, and seam placement. - Use Case: A developer suspects their service layer is over-fragmented. The Skill explores the repo, lists five deepening candidates, then grills the user through constraints and produces a recommended interface with a testing strategy. ## Quick Start Ask the agent to analyze this codebase for architecture improvement opportunities and propose 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 large codebase?▼

Use an exploration pass that looks for shallow modules whose interfaces are nearly as complex as their implementations, then apply the deletion test: if deleting a module just moves complexity to callers, it was earning its keep; if complexity vanishes, it was a pass-through worth removing.

What is a deep module in software architecture?▼

A deep module hides a large amount of behavior behind a small interface, giving callers leverage and maintainers locality. Depth is a property of the interface, not the implementation, so a deep module can still be internally composed of small swappable parts.

How does this Skill handle existing architecture decision records?▼

It reads ADRs in docs/adr/ before proposing changes and avoids re-litigating recorded decisions. A candidate that contradicts an ADR is only surfaced when the friction is real enough to warrant reopening it, and is clearly marked as conflicting.

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; remote owned services and third-party dependencies are the main cases where ports and adapters apply.

What are the limitations of this architecture review approach?▼

It proposes deepening candidates but does not implement refactors itself, and it depends on the quality of the project's CONTEXT.md domain glossary and ADRs. It also avoids listing every theoretical refactor, so minor or speculative improvements may be omitted.