improve-codebase-architecture

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

3|1|Updated Jul 12, 2026
One-click install
npx skills add https://github.com/DuckKota/my-opencode-setup --skill improve-codebase-architecture-duckkota
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/DuckKota/my-opencode-setup/tree/main/src/skills/improve-codebase-architecture
Command: npx skills add https://github.com/DuckKota/my-opencode-setup --skill improve-codebase-architecture-duckkota

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making them 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 - Hot-spot-driven exploration: Scopes the scan using git history and user direction, then applies the deletion test to find shallow modules, leaky seams, and untestable code. - Visual HTML report: Renders candidates as a self-contained HTML file in the OS temp directory using Tailwind and Mermaid via CDN, with before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Guided decision loop: After the user picks a candidate, it grills through constraints and dependencies, updates the domain glossary in CONTEXT.md, and offers ADRs for load-bearing rejections. - Use Case: Run it on a service whose order intake logic is scattered across six thin wrappers; get a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the assistant to review this codebase for architecture improvements and show the deepening candidates 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 the architecture review, which walks recent git history to find hot spots, then applies the deletion test: if deleting a module would concentrate complexity rather than move it, the module is shallow. Candidates are presented with before/after diagrams in an HTML report.

How to visualize architecture refactoring proposals?▼

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

Does the architecture review respect existing ADRs?▼

Yes, it reads ADRs in docs/adr/ before scanning and avoids re-litigating recorded decisions. A candidate that contradicts an ADR is only surfaced with a warning callout when the friction is real enough to warrant reopening the decision.

What vocabulary does the architecture report use?▼

It uses the codebase-design glossary exactly: module, interface, implementation, depth, seam, adapter, leverage, and locality. Terms like component, service, API, or boundary are deliberately avoided, and domain names come from the project's CONTEXT.md.

What happens after I pick a refactoring candidate?▼

A grilling loop walks through constraints, dependencies, and the shape of the deepened module. New domain terms are added to CONTEXT.md, and load-bearing rejections can be recorded as ADRs so future reviews do not re-suggest them.