skills.rest
ckyeon
ckyeonCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

improve-codebase-architecture

Identify shallow modules and generate an HTML report with refactoring recommendations.

Updated May 16, 2026
Search Tags:#refactoring#testability#deepening#codebase architecture#AI-navigable
One-click install
npx skills add https://github.com/ckyeon/claude-code-settings --skill improve-codebase-architecture-ckyeon
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/ckyeon/claude-code-settings/tree/main/user/shared/skills/improve-codebase-architecture
Command: npx skills add https://github.com/ckyeon/claude-code-settings --skill improve-codebase-architecture-ckyeon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill identifies shallow modules in a codebase and suggests refactoring opportunities to improve architecture, making the codebase more testable and AI-navigable.

Core Features & Use Cases

  • Deepening Opportunities: Surface architectural friction and propose refactoring opportunities to turn shallow modules into deep ones.
  • Domain Language: Uses the domain language in CONTEXT.md and architectural decisions in docs/adr/ to inform suggestions.
  • HTML Report: Generates a self-contained HTML report with visualizations and recommendations for refactoring.

Quick Start

Run the improve-codebase-architecture skill to analyze your codebase and receive architectural suggestions.

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 in my codebase for refactoring?▼

To identify shallow modules, analyze your codebase architecture to surface friction and propose deepening opportunities. This refactoring turns shallow modules into deep ones, making your codebase more testable and AI-navigable.

What is a deep module in codebase architecture?▼

A deep module in codebase architecture is a component with a rich interface but minimal implementation details exposed. Deepening shallow modules improves testability and makes the codebase AI-navigable by hiding internal complexity behind a robust interface.

How do I use domain language and architectural decisions to inform refactoring suggestions?▼

Refactoring suggestions are informed by reading domain language from a CONTEXT.md file and architectural decisions from docs/adr/. This ensures that codebase architecture improvements align with your project's established terminology and design rationale.

Can I generate a visual report of codebase refactoring opportunities?▼

Yes, you can generate a visual report of codebase architecture refactoring opportunities. The analysis produces a self-contained HTML report that includes visualizations and actionable recommendations to guide your deepening efforts.

Does this codebase architecture analysis require any specific dependencies?▼

No, this codebase architecture analysis requires no external dependencies to run. It operates directly on your project files, relying on existing CONTEXT.md and docs/adr/ directories to inform its architectural suggestions.

When should I not use automated refactoring suggestions for my codebase?▼

You should avoid relying solely on automated refactoring suggestions when your codebase lacks a CONTEXT.md or docs/adr/ directory. Without domain language and architectural decision records, the generated deepening opportunities may lack proper context.

Related Skills

Explore More Software Engineering Skills→
dachentdachent
18

grill-with-docs-codex

Validate project plans against domain terminology, ADRs, and codebase context.

Community
Intermediate
JeromyJSmithJeromyJSmith
3

improve-codebase-architecture

Identify shallow modules and propose interface-focused refactoring candidates.

Community
Advanced
GuitarAlchemistGuitarAlchemist

improve-codebase-architecture

Analyze module interfaces and generate HTML reports on architectural deepening opportunities.

Official
Advanced
tonombtonomb

improve-codebase-architecture

Analyze dependency graphs and refactor shallow modules into deep architectures.

Community
Advanced