codebase-architecture

Identify architectural friction and propose boundary-based refactors for shallow modules.

Updated Mar 23, 2026

Search Tags:#testing #architecture #codebase #testability #refactor #boundaries #ai-navigable

Ready to run

npx skills add https://github.com/mia-cx/.agents --skill codebase-architecture-mia-cx

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Identify friction points in a codebase and surface opportunities to deepen shallow modules, enabling more robust testing, AI-assisted navigation, and safer, bounded refactors.

Core Features & Use Cases

Surface architectural friction and deepening opportunities to improve testability and AI-navigability.
Produce candidate RFCs with dependency and testing implications to guide refactors.
Generate multiple interface designs and a recommended path, plus an issue ticket to implement.

Quick Start

Run the Agent tool with subagent_type=Explore to identify friction points in the codebase.

Frequently Asked Questions about codebase-architecture

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

FAQPage Schema

How do I refactor tightly-coupled codebase modules to improve testability?▼

To improve testability in a tightly-coupled codebase, you identify architectural friction and propose boundary-based refactors to deepen shallow modules. This clarifies unclear interfaces and establishes bounded dependencies, enabling robust testing and safer structural consolidation.

What is a shallow module in software architecture?▼

A shallow module in software architecture is a component with unclear interfaces and tightly-coupled dependencies that creates friction. Deepening these modules involves restructuring boundaries to isolate functionality, which directly boosts testability and AI-navigability across large codebases.

How do I prepare an RFC for a codebase refactoring workplan?▼

You prepare a refactoring RFC by categorizing dependencies and analyzing testing implications for proposed boundary changes. The process generates multiple interface designs with a recommended path, culminating in a structured workplan and an issue ticket to implement the refactor.

Can I analyze codebase architecture for AI navigation without decoupling modules?▼

Analyzing codebase architecture for AI navigation without decoupling modules is difficult due to tightly-coupled friction. Surfacing boundary-based refactors to deepen shallow modules is required to establish clear interfaces, directly enabling effective AI-assisted navigation and robust testing.

What is the best way to identify architectural friction in a large codebase?▼

The best way to identify architectural friction in a large codebase is to run an exploration agent to surface tightly-coupled modules. This process highlights shallow modules and unclear interfaces, producing dependency categorizations and boundary-focused testing strategies for structured refactors.