improve-codebase-architecture

Identify architectural frictions and prioritize module deepening candidates in a codebase.

102|4|Updated Apr 15, 2009

Search Tags:#architecture #refactoring #codebase #testability #modularity #seams #deepening

Ready to run

npx skills add https://github.com/mikker/dotfiles --skill improve-codebase-architecture-mikker

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Surface architectural friction and surface opportunities to deepen modules, enabling better testability and AI-navigability within a codebase.

Core Features & Use Cases

Surface shallow modules and propose concrete deepening opportunities to consolidate seams and improve locality.
Align recommendations with the project's domain language (CONTEXT.md) and ADRs to ensure architecture decisions stay coherent.
Provide a prioritized plan for refactors that increase leverage behind the external interface while preserving behaviour.

Quick Start

Run the Explore flow to identify opportunities in your repository and generate a prioritized plan.

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 architectural friction in a large codebase?▼

Identify architectural friction by surfacing shallow modules and analyzing seams to generate a prioritized list of deepening candidates. This reveals areas where poor locality limits testability, providing concrete rationale for structural improvements across the codebase.

What is the best way to refactor shallow modules for better testability?▼

Refactor shallow modules by applying a deepening plan that consolidates seams and increases leverage behind external interfaces. This approach preserves behavior while improving locality, resulting in a codebase that is significantly more testable and AI-navigable.

How do I align codebase refactoring with existing architecture decisions?▼

Align refactoring with architecture decisions by satisfying domain concepts defined in CONTEXT.md and ADR-FORMAT.md. This ensures that proposed structural changes and module deepening opportunities stay coherent with the established project domain language.

Can I use this approach for large codebases with complex module dependencies?▼

Yes, this approach specifically applies to refactoring contexts across large codebases. It focuses on analyzing module depth, seams, and locality to surface deepening opportunities, ensuring structural improvements scale effectively within complex dependency networks.

When do I need to deepen modules in my architecture?▼

Deepen modules when architectural friction surfaces through shallow structures that reduce testability and AI-navigability. A prioritized plan helps consolidate these seams, increasing leverage behind the external interface while preserving existing system behavior.

How do I generate a prioritized refactoring plan for my codebase?▼

Generate a prioritized refactoring plan by running the Explore flow to identify deepening opportunities in your repository. This surfaces architectural friction and outputs a structured list of candidates with rationale for improving modularity.