improve-codebase-architecture

Identify shallow modules and leaky seams to propose refactoring deepening opportunities.

Updated Mar 27, 2026

Search Tags:#architecture #refactoring #testability #deepening #seam #ADR review

Ready to run

npx skills add https://github.com/gaborbencsik/tipp-game --skill improve-codebase-architecture-gaborbencsik

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/gaborbencsik/tipp-game/tree/main/.claude/skills/improve-arch
Command: npx skills add https://github.com/gaborbencsik/tipp-game --skill improve-codebase-architecture-gaborbencsik

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you reduce architectural friction in a codebase by finding shallow, hard-to-test module boundaries and proposing deepening opportunities that concentrate behaviour behind small interfaces.

Core Features & Use Cases

Architecture exploration: Walk the codebase to spot shallow modules, leaky seams, and places where tests can’t effectively exercise behaviour through the current interface.
Deepening candidate reporting: Produce an OS-temp, self-contained HTML architecture review with before/after diagrams and evidence framed using the module vocabulary (depth, seam, adapter, locality, leverage).
Interactive refactoring grilling: Once a candidate is chosen, run a constraint-driven design conversation to crystallize a deep module shape, its seam placement, and the testing approach.

Quick Start

Ask the AI to improve your repository’s architecture by generating deepening candidates in an HTML report and then select the strongest one to explore interactively.

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 shallow modules and leaky seams in my codebase architecture?▼

To find shallow modules and leaky seams, an architecture exploration pass walks the codebase to spot boundaries where tests can't effectively exercise behaviour, then proposes deepening opportunities that concentrate logic behind small interfaces.

What's the best way to refactor code for better testability and interface leverage?▼

Refactoring for testability and interface leverage involves identifying shallow boundaries and proposing deepening candidates that concentrate behaviour behind small interfaces, framed using vocabulary like depth, seam, adapter, locality, and leverage.

How does an architecture deepening report help consolidate tightly coupled modules?▼

An architecture deepening report helps consolidate tightly coupled modules by generating a self-contained HTML review with before/after diagrams and evidence, showing how to increase interface leverage and maintain locality.

Can I review ADRs and domain vocabulary before proposing refactoring candidates?▼

Yes, an exploration pass over domain vocabulary and relevant ADRs is required before proposing refactoring candidates, ensuring deepening opportunities align with existing design decisions and improve AI-navigability.

How do I define constraints and seam placement during a refactoring design conversation?▼

Constraints and seam placement are defined through an interactive refactoring grilling loop that runs a constraint-driven design conversation to crystallize the deep module shape, dependencies, and testing approach.

When should I not use a deepening approach for architecture improvement?▼

A deepening approach for architecture improvement may not suit contexts where module boundaries already exhibit high interface leverage and strong locality, as the process targets shallow modules and leaky seams that hinder testability.