improve-codebase-architecture

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

Updated Nov 23, 2024
One-click install
npx skills add https://github.com/tokisakiyuu/dotfiles --skill improve-codebase-architecture-tokisakiyuu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/tokisakiyuu/dotfiles/tree/main/home/dot_claude/skills/improve-codebase-architecture
Command: npx skills add https://github.com/tokisakiyuu/dotfiles --skill improve-codebase-architecture-tokisakiyuu

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 the code hard to test, navigate, and reason about. This Skill surfaces that architectural friction and proposes concrete deepening refactors. ## Core Features & Use Cases - Deepening Opportunity Discovery: Explores the codebase with sub-agents to find shallow modules, pass-through abstractions, and tightly-coupled clusters, applying the deletion test to validate each candidate. - Consistent Architecture Vocabulary: Uses a shared glossary (module, interface, depth, seam, adapter, leverage, locality) so every suggestion is expressed in precise, consistent terms. - Domain-Aware Recommendations: Reads the project's CONTEXT.md domain glossary and docs/adr/ decision records so proposals use domain language and avoid re-litigating settled decisions. - Parallel Interface Design: Spawns multiple sub-agents to design radically different interfaces for a chosen candidate, then compares them by depth, locality, and seam placement. - Use Case: A team inherits a service where business logic is split across dozens of tiny handlers and helpers. Run this Skill to get a numbered list of consolidation candidates, pick one, and walk through a grilling session that produces a deep module with a small interface and tests at the seam. ## 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 large codebase?▼

Use this Skill to explore the codebase with sub-agents that look for shallow modules, pass-through abstractions, and tightly-coupled clusters. 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 behaviour behind a small interface, giving callers high leverage. A shallow module has an interface nearly as complex as its implementation, so it adds indirection without hiding complexity. The Skill uses this distinction to rank refactoring candidates.

How does the Skill handle existing architecture decision records?▼

It reads ADRs in docs/adr/ before proposing changes and avoids re-litigating settled decisions. If a candidate contradicts an ADR, it only surfaces the conflict when the friction justifies reopening the decision, and marks it explicitly.

Can I compare multiple interface designs before refactoring?▼

Yes. After picking a candidate, the Skill spawns three or more parallel sub-agents that each design a radically different interface under different constraints, then compares them by depth, locality, and seam placement with an opinionated recommendation.

When should I not introduce a new interface or seam?▼

Avoid a new 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 and test, justify a real one.