improve-codebase-architecture

Identify module deepening opportunities and propose refactor candidates from code evidence.

1|1|Updated Apr 24, 2026

Search Tags:#architecture #refactoring #testing strategy #module boundaries #ports and adapters #seams #AI navigability

Ready to run

npx skills add https://github.com/luan/agents --skill improve-codebase-architecture-luan

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/luan/agents/tree/main/skills/improve-codebase-architecture
Command: npx skills add https://github.com/luan/agents --skill improve-codebase-architecture-luan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you reduce architectural friction by identifying shallow module boundaries and proposing deepening refactors that improve testability and AI navigability.

Core Features & Use Cases

Architecture deepening suggestions: surfaces refactor opportunities that turn shallow modules into deep ones using clear module/interface/seam language.
Dependency-aware design: classifies dependencies (in-process, local-substitutable, remote-owned with ports/adapters, true external with mocks) to guide how the deepened module should be tested.
Grilling loop for confident decisions: walks constraints, seam placement, adapters, and interface test surfaces, and records vault docs only when justified.

Quick Start

Ask the AI to improve the architecture of the selected parts of your codebase by finding deepening opportunities and proposing the safest refactor candidates grounded in your vault docs and code evidence.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I identify shallow module boundaries for architecture refactoring?▼

You identify shallow module boundaries by analyzing codebase areas for deepening opportunities that increase module depth through well-defined interfaces and seams, requiring evidence gathering from vault documentation and code inspection.

What is the best way to make codebase refactors testable using ports and adapters?▼

The best way to make codebase refactors testable is classifying dependencies as in-process, local-substitutable, remote-owned with ports and adapters, or true external with mocks, guiding how the deepened module should be tested through interface-based testing surfaces.

How does a grilling loop improve software architecture decisions?▼

A grilling loop improves software architecture decisions by walking through constraints, seam placement, adapters, and interface test surfaces, reasoning about dependency categories to ensure confident refactoring decisions and recording vault docs only when justified.

Can I use this approach to improve AI navigability in my codebase?▼

Yes, you can improve AI navigability by reducing architectural friction through deepening refactors that turn shallow modules into deep ones using clear module, interface, and seam language grounded in your vault documentation and code evidence.

When should I not use module deepening for refactoring?▼

You should avoid module deepening when premature interface changes are required, as the approach requires candidate presentation without premature interface changes and only records vault documentation when constraints and seam placement are fully justified.