improve-codebase-architecture

Identify refactoring opportunities that deepen shallow modules into testable designs.

1|Updated May 5, 2026

Search Tags:#architecture #refactoring #testability #ports and adapters #seams #codebase deepening #ADR alignment

Ready to run

npx skills add https://github.com/yashs33244/my-mac-claude --skill improve-codebase-architecture-yashs33244

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/yashs33244/my-mac-claude/tree/main/skills/mattpocock/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/yashs33244/my-mac-claude --skill improve-codebase-architecture-yashs33244

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you identify where your codebase is shallow and hard to test, then guides you toward deeper module boundaries that concentrate change and improve AI navigation.

Core Features & Use Cases

Deepening Opportunity Discovery: Finds refactoring candidates by assessing module depth, seams, adapters, and dependency ownership.
Architecture Grilling Loop: After you pick a candidate, explores constraints, seam placement, adapter strategy, and what the implementation should hide.
Domain-Driven Vocabulary Alignment: Uses the project’s architecture vocabulary and records conflicts or new terms as needed.

Quick Start

Ask the AI to review your project and propose deepening candidates for making the architecture more testable and AI-navigable.

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 refactoring opportunities to improve codebase architecture and testability?▼

This Skill finds refactoring opportunities by assessing module depth, seams, and dependency ownership to guide you toward testable, high-leverage boundaries that improve codebase architecture.

What is the best way to plan a refactoring strategy using ports and adapters?▼

The best way to plan ports and adapters refactoring is selecting a candidate module and entering an architecture grilling loop to explore constraints, seam placement, and adapter strategy for testable boundaries.

How do I use ADRs to align my codebase architecture with domain vocabulary?▼

You align architecture with domain vocabulary by applying ADRs for documentation decisions and using a CONTEXT.md file to map domain terms, recording any conflicts or new terms discovered during refactoring.

Can I evaluate module depth and testability without external dependencies?▼

Yes, you can evaluate module depth and testability with zero external dependencies because this Skill applies interface, seam, adapter, leverage, locality, and deletion tests to assess your codebase.

When should I refactor shallow modules into deeper, testable boundaries?▼

Refactor shallow modules into deeper boundaries during architecture review, refactor planning, or when you experience friction navigating seams, dependencies, and untested boundaries in your codebase.