improve-codebase-architecture

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

11|2|Updated Dec 29, 2025
One-click install
npx skills add https://github.com/oskrgab/petrodb --skill improve-codebase-architecture-oskrgab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/oskrgab/petrodb/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/oskrgab/petrodb --skill improve-codebase-architecture-oskrgab

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, scattering logic across many small files and making testing and navigation difficult. This Skill surfaces that architectural friction and proposes deepening refactors that consolidate behavior behind small, high-leverage interfaces. ## Core Features & Use Cases - Architecture exploration: Walks the codebase with an Explore sub-agent to find shallow modules, tightly-coupled seams, and hard-to-test areas, applying the deletion test to each candidate. - Deepening proposals: Presents a numbered list of refactoring candidates 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 team with a sprawling service layer asks for an architecture review; the Skill identifies pass-through modules, proposes consolidating them into deep modules with ports and adapters, and records rejected candidates as ADRs. ## Quick Start Ask the assistant to review this codebase for architecture 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 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, and benefits.

What is a deep module versus a shallow module?

A deep module hides a large amount of behavior behind a small interface, giving callers leverage and maintainers locality. A shallow module has an interface nearly as complex as its implementation, so deleting it just moves complexity rather than concentrating it.

How does the 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 contradiction.

When should I use ports and adapters for a refactored module?

Use ports and adapters when dependencies cross a network boundary you own or a third-party service you do not control. The Skill recommends defining a port only when at least two adapters exist, typically a production adapter and an in-memory test adapter.

What are the limitations of this architecture review approach?

The Skill proposes refactors but does not implement them, and it depends on the quality of the project's CONTEXT.md domain glossary and ADRs. It deliberately skips candidates that existing ADRs forbid unless the friction is severe enough to revisit them.