improve-codebase-architecture

Identify shallow modules and propose prioritized deepening opportunities with affected files.

40|9|Updated Jan 4, 2026

Search Tags:#architecture #refactoring #codebase #testability #adr #seams #domain-terms

Ready to run

npx skills add https://github.com/akillness/jeo-skills --skill improve-codebase-architecture-akillness

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

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

Core Features & Use Cases

Read domain glossary (CONTEXT.md) and ADRs before surveying the codebase to capture domain terms and existing decisions.
Identify shallow modules and seams where interfaces can be deepened to improve locality and leverage.
Propose a prioritized set of deepening opportunities with affected files, the problem, the proposed solution, and expected benefits; surface ADR conflicts if any.
Follow the grilling loop with user until a concrete plan emerges and update CONTEXT.md or ADRs as needed.

Quick Start

Evaluate a codebase to locate shallow modules and propose actionable deepening opportunities.

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

Architectural friction refers to strong coupling, shallow interfaces, and unclear seams in a codebase that hinder testability. Identifying these shallow modules allows you to prioritize refactoring opportunities that deepen interfaces for better locality and leverage.

How do I refactor shallow modules to improve codebase testability?▼

Refactor shallow modules by deepening their interfaces and isolating seams to improve testability. This process produces a prioritized list of candidates detailing affected files, problems, proposed solutions, and expected benefits for actionable architecture improvements.

When do I need to update ADRs during a codebase architecture refactoring?▼

You need to update ADRs during architecture refactoring when proposed deepening opportunities conflict with existing decisions. The analysis surfaces these ADR conflicts, requiring you to resolve them and update documentation as part of the concrete plan.

Can I use CONTEXT.md domain terms to guide codebase architecture analysis?▼

Yes, you can use CONTEXT.md to guide architecture analysis. The evaluation reads your domain glossary and ADRs before surveying the codebase, ensuring proposed deepening opportunities align with established domain terms and existing architectural decisions.

What is the best way to prioritize codebase refactoring opportunities for AI-navigability?▼

The best way to prioritize refactoring opportunities for AI-navigability is to evaluate modules for coupling and interface shallowness. This generates a prioritized list of deepening candidates, detailing affected files, problems, solutions, and expected benefits.