improve-codebase-architecture

Scan a codebase for module deepening opportunities and present them as a visual HTML report.

Updated May 28, 2026
One-click install
npx skills add https://github.com/changfengpro/agent-skills --skill improve-codebase-architecture-changfengpro
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/changfengpro/agent-skills/tree/main/skills/improve-codebase-architecture
Command: npx skills add https://github.com/changfengpro/agent-skills --skill improve-codebase-architecture-changfengpro

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making code hard to test and navigate. This Skill surfaces that architectural friction and proposes concrete deepening refactors grounded in a shared design vocabulary. ## Core Features & Use Cases - Architecture exploration: Scopes the review using git history hot spots, reads CONTEXT.md and ADRs, then explores the codebase for shallow modules, seam leakage, and poor locality. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory using Tailwind and Mermaid via CDN, with before/after diagrams, recommendation-strength badges, and a top recommendation. - Grilling loop: After the user picks a candidate, runs a decision-tree grilling session, updates CONTEXT.md with new domain terms, and offers ADRs for load-bearing rejections. - Use Case: Point it at a subsystem where order intake logic is scattered across six thin wrappers; it produces a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the assistant to review the architecture of the current codebase and show deepening opportunities as an HTML report.

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?

Run this Skill to explore the codebase for modules whose interface is nearly as complex as their implementation. It applies the deletion test to candidates and presents each finding with a before/after diagram in an HTML report.

How to generate an architecture review report as HTML?

The Skill writes a self-contained HTML file to the OS temp directory using Tailwind and Mermaid from CDNs, then opens it in your browser. Each candidate gets a card with files, problem, solution, benefits, and a before/after diagram.

Does the architecture review respect existing ADRs?

Yes, it reads ADRs in docs/adr/ before proposing changes and avoids re-litigating recorded decisions. A candidate that contradicts an ADR is only surfaced with a clear warning callout when the friction justifies reopening it.

What vocabulary does the architecture report use?

The report uses a fixed glossary from the codebase-design skill: module, interface, implementation, depth, seam, adapter, leverage, and locality. It avoids substitute terms like component, service, API, or boundary.

What happens after I pick a refactoring candidate?

The Skill runs a grilling loop that walks the decision tree for the chosen candidate, covering constraints, dependencies, and the shape of the deepened module. It updates CONTEXT.md with new domain terms and can offer to record an ADR for load-bearing rejections.