improve-codebase-architecture

Analyze a codebase and produce prioritized deepening candidates with files, problems, solutions, and benefits.

36|Updated Jan 28, 2026

Search Tags:#architecture #codebase #adr #glossary #refactor #analyze #domain-model

Ready to run

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

💬 Prompt for ChatGPT / Claude Chat▼

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

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

Explore the project's domain glossary and ADRs, then examine the codebase to identify seams where complexity concentrates and interfaces are too shallow.
Present deepening opportunities as candidates with the involved files, the problem, the proposed solution, and the expected benefits, following CONTEXT.md vocabulary.
Use cases include consolidating tightly-coupled modules behind clearer seams to improve locality, testability, and AI navigability.

Quick Start

Read the project's domain glossary and ADRs, then present a numbered list of deepening opportunities with files, problem, solution, and benefits.

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 the codebase using the domain glossary and ADRs to find seams where complexity concentrates. This surfaces deepening opportunities that turn shallow modules into deep ones for better testability and AI-navigability.

What is a deepening opportunity when refactoring software architecture?▼

A deepening opportunity is a refactor that turns a shallow module into a deep one by consolidating tightly-coupled code behind clearer seams. It is presented as a candidate with the involved files, the problem, the proposed solution, and expected benefits.

How do I use ADRs and a domain glossary to improve codebase testability?▼

Use ADRs and the domain glossary to examine the codebase and identify architectural friction. By applying CONTEXT.md vocabulary, you can pinpoint shallow modules and propose refactors that improve locality, testability, and AI navigability.

Does this architectural analysis work for code reviews or only full module refactors?▼

This architectural analysis is applicable during both code reviews and architectural refactors across modules. It examines the codebase to surface prioritized deepening candidates that improve testability and AI-navigability in either context.

What's the best way to consolidate tightly-coupled modules behind clearer seams?▼

The best way to consolidate tightly-coupled modules is to analyze the codebase using the domain glossary and ADRs to generate a prioritized list of deepening opportunities. These candidates provide the files, problem, solution, and benefits for improving locality.

Why does my codebase lack AI-navigability and how can I fix it?▼

Your codebase lacks AI-navigability due to shallow modules and tightly-coupled code creating architectural friction. You can fix it by surfacing deepening opportunities through analyzing the domain glossary and ADRs to consolidate complexity behind clearer seams.