improve-codebase-architecture

Generate HTML reports of shallow modules with before/after visuals.

1|Updated Mar 9, 2026

Search Tags:#architecture #codebase #refactor #adapter #tests #deepening #seam

Ready to run

npx skills add https://github.com/danievanzyl/code-skills --skill improve-codebase-architecture-danievanzyl

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Surface architectural friction by surfacing deepening opportunities in a codebase and aligning with domain language (CONTEXT.md) and ADR decisions to enable easier testing, navigation, and future-proof refactors.

Core Features & Use Cases

Discover shallow modules and suggest targeted deepening opportunities based on domain terms.
Generate HTML architecture reports with candidate before/after visuals to communicate depth and seams.
Guide the grilling loop workflow, ADR considerations, and interface-design explorations to support deliberate refactors.

Quick Start

Run the architecture-scan workflow to surface deepening candidates and generate an HTML report for the current project.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I find shallow modules in my codebase that need refactoring?▼

To find shallow modules in your codebase, run an architecture scan to surface deepening opportunities. It applies architecture heuristics to identify candidate modules that would benefit from a seam-based refactor and presents them in an HTML report with before/after visuals.

What is a seam-based refactor and when do I need one?▼

A seam-based refactor introduces an interface boundary to isolate shallow modules, enabling easier testing and navigation. You need one when architectural friction prevents domain-aligned growth and future-proof modifications.

How do I align my architecture refactor with domain language and ADR decisions?▼

To align your architecture refactor with domain language, apply ADR-informed terms and use a CONTEXT.md glossary. This ensures suggested deepening opportunities match your domain and support deliberate interface-design explorations.

Can I generate an HTML architecture report with before and after visuals for my project?▼

Yes, you can generate an HTML architecture report with before/after visuals for your project. The report communicates depth and seams by presenting shallow modules and targeted deepening opportunities based on domain terms.

Does this codebase architecture analysis require any dependencies or specific setup?▼

No dependencies are required to run this codebase architecture analysis. You can execute the architecture-scan workflow directly on your current project to surface deepening candidates and generate the report without external components.

What is the best way to guide a grilling loop workflow for interface design?▼

The best way to guide a grilling loop workflow for interface design is to surface deepening opportunities first, then apply ADR considerations and domain language from a CONTEXT.md glossary. This approach supports deliberate refactors and targeted architecture exploration.