skills.rest
saitarrun
saitarrunCOMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

Design and apply a step-by-step plan to restructure the codebase.

4|2|Updated Jun 20, 2026
Search Tags:#refactoring#testability#technical-debt#adr-compliance#deep-modules#ai-navigability#codebase-architecture
One-click install
npx skills add https://github.com/saitarrun/devforge-ai --skill improve-codebase-architecture-saitarrun
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/saitarrun/devforge-ai/tree/main/skills/architecture-refactor
Command: npx skills add https://github.com/saitarrun/devforge-ai --skill improve-codebase-architecture-saitarrun

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill addresses the pain of maintaining codebases with architectural friction: shallow modules, tightly coupled components, and poor testability that slow down development, hide bugs, and make code hard for both human developers and AI coding assistants to navigate and modify.

Core Features & Use Cases

  • Domain-Aligned Analysis: Uses your project's existing domain language from CONTEXT.md and recorded architectural decisions from docs/adr/ to ensure refactoring suggestions match your project's context and don't re-litigate settled rules.
  • Visual Refactoring Reports: Generates a self-contained HTML report with before/after diagrams, clear explanations of each refactor's benefits for code locality and leverage, and prioritized recommendations marked by strength.
  • Use Case: Ideal for teams working with legacy codebases, code with low unit test coverage, or projects where AI assistants struggle to understand code structure, as well as for reducing technical debt through targeted, high-impact refactors.

Quick Start

Use the improve-codebase-architecture skill to analyze your project's codebase and get a visual report of prioritized, domain-aligned refactoring 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 architectural friction and shallow modules in a legacy codebase?▼

Refactoring legacy code for testability involves pinpointing tightly coupled components and poor structural navigation. This Skill generates visual reports with before/after diagrams, prioritizing refactors that enhance unit test coverage and AI navigability.

Can I align code refactoring suggestions with existing project ADRs and domain language?▼

Yes, aligning refactoring suggestions with ADRs is supported by reading architectural decisions from docs/adr/. This prevents re-litigating settled rules and ensures technical debt reduction aligns with your established domain language and structural constraints.

What is the best way to reduce technical debt when AI coding assistants struggle to navigate my code?▼

Reducing technical debt for AI navigability requires deepening shallow modules to improve code locality and leverage. This Skill analyzes your source code structure and outputs a visual HTML report detailing targeted, high-impact refactoring opportunities.

Does this codebase architecture analysis require specific dependencies or external libraries?▼

This architecture analysis requires no external dependencies or components to evaluate testability and AI navigability. You simply need your existing codebase, along with your CONTEXT.md and docs/adr/ files for domain-aligned analysis.

How do I generate a visual refactoring report for my software engineering workflow?▼

You generate a visual refactoring report by analyzing your codebase for architectural friction, which produces a self-contained HTML document. This report visualizes before/after states and prioritizes deepening opportunities to improve overall codebase architecture.

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
kevinnftkevinnft
13

improve-codebase-architecture

Identify shallow modules and propose deepening opportunities in codebases.

Community
Advanced
safzanpiranisafzanpirani
1

improve-codebase-architecture

Identify architectural friction and write RFCs for module deepening refactors.

Community
Advanced
jankneumannjankneumann
4

tech-debt-analysis

Analyze codebase complexity, coupling, duplication, and import issues to generate markdown and JSON reports.

Community
Advanced