skills.rest
cloudofgeorge
cloudofgeorgeCOMMUNITY
Explore all skills by this author →
Website𝕏@cloudofgeorgeGitHub

improve-codebase-architecture

Identify shallow modules and propose deepening refactors aligned with ADR vocabulary.

Updated May 11, 2026
Search Tags:#testing#architecture#refactoring#modularization#leverage#locality#deepening
One-click install
npx skills add https://github.com/cloudofgeorge/AI-hands --skill improve-codebase-architecture-cloudofgeorge
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/cloudofgeorge/AI-hands/tree/main/skills/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/cloudofgeorge/AI-hands --skill improve-codebase-architecture-cloudofgeorge

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Core Features & Use Cases

  • Surface shallow modules and surface concrete deepening opportunities to improve testability and AI-navigability.
  • Use the deletion test and locality/leverage analysis to surface viable seams and adapters.
  • Align recommendations with ADRs and CONTEXT.md vocabulary to preserve domain language.

Quick Start

Run the Agent tool with subagent_type=Explore to map friction points and surface deepening candidates.

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

To identify architectural friction, analyze modules for high locality risk and low interface leverage, then apply the deletion test to surface viable seams and adapters for refactoring shallow modules into deeper ones.

What is the deepening approach for converting shallow modules into deep ones?▼

The deepening approach converts shallow modules into deep ones by targeting modules with high locality risk and low interface leverage. It surfaces actionable refactoring opportunities that hide implementation details behind robust interfaces to improve testability and AI-navigability.

How do I align refactoring decisions with existing ADRs and domain language?▼

Align refactoring decisions by cross-referencing architectural friction points against ADRs and CONTEXT.md vocabulary. This ensures that deepening opportunities and module modifications preserve the established domain language and architectural decisions.

When should I plan a deepening sprint for modularization and architecture improvements?▼

Plan a deepening sprint when architectural analysis surfaces concise candidate descriptions with scope, constraints, and expected impact. These candidates indicate viable seams where modularization refactors will significantly improve testability and reduce locality risk.

Does this architecture analysis require specific dependencies or component installations?▼

No specific dependencies or components are required. The analysis operates by mapping friction points and surfacing deepening candidates using an Agent tool with subagent_type=Explore to evaluate locality risk and interface leverage.

Related Skills

Explore More Software Engineering Skills→
aaronlordaaronlord
1

domain-modeling

Create and refine a project domain model with CONTEXT.md and ADRs.

Community
Intermediate
ayehiaaayehiaa

improve-codebase-architecture

Identifies deepening opportunities to improve codebase architecture by reducing shallow-module complexity.

Community
Intermediate
DuranndDurannd

improve-codebase-architecture

Identify architectural friction points and propose deepening refactors for testability and modularity.

Community
Advanced
safzanpiranisafzanpirani
1

improve-codebase-architecture

Identify architectural friction and write RFCs for module deepening refactors.

Community
Advanced