skills.rest
akillness
akillnessCOMMUNITY
Explore all skills by this author →
Website𝕏@akillness0308GitHub

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
One-click install
npx skills add https://github.com/akillness/jeo-skills --skill improve-codebase-architecture-akillness
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
OutlineDrivenOutlineDriven
5

domain-model

Stress-test domain terminology in CONTEXT.md and ADRs to surface canonical terms.

Official
Advanced
cagdotincagdotin
36

improve-codebase-architecture

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

Community
Advanced
malinskibeniaminmalinskibeniamin
3

improve-codebase-architecture

Analyze module coupling and depth to identify architecture deepening opportunities.

Community
Intermediate
sambersamber
2.9k

golang-code-style

Enforce Go code style, formatting, and conventions across a codebase.

Community
Intermediate