skills.rest
Davie521
Davie521COMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

Identify shallow modules and architectural seams for refactoring opportunities.

7|Updated Mar 4, 2026
Search Tags:#architecture#codebase#adr#refactor#domain-language#deepening#seam
One-click install
npx skills add https://github.com/Davie521/claude-skills --skill improve-codebase-architecture-davie521
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Davie521/claude-skills/tree/main/plugins/dev-workflow/skills/improve-codebase-architecture
Command: npx skills add https://github.com/Davie521/claude-skills --skill improve-codebase-architecture-davie521

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Surface architectural friction in a codebase and surface deepening opportunities that turn shallow modules into deep, testable interfaces.

Core Features & Use Cases

  • Identify shallow modules and potential seams that warrant deeper examination
  • Propose ADR-aligned deepening candidates with domain-language naming
  • Run a guided grilling loop to compare options, assess trade-offs, and plan implementations
  • Use Case: during architecture reviews, surface refactor opportunities and create actionable PR roadmaps

Quick Start

Analyze the repository to surface one high-impact deepening candidate and outline the steps to implement it.

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?▼

Identifying shallow modules requires analyzing architectural seams to surface deepening opportunities that turn shallow interfaces into deep, testable modules. This process targets large, multi-module projects to uncover hidden structural friction.

When do I need to use architectural seams for codebase refactoring?▼

Architectural seams are needed during architecture reviews when you must surface refactor opportunities and create actionable PR roadmaps. They help assess trade-offs and guide the discovery of testability improvements within complex projects.

How do I align domain language with ADR considerations during an architecture review?▼

Aligning domain language with ADR considerations involves applying a domain glossary (LANGUAGE.md) alongside architectural decision records (docs/adr/). This ensures proposed deepening candidates use consistent domain-language naming and adhere to documented decisions.

What is the best way to compare refactoring options and assess trade-offs in a large project?▼

The best way to compare refactoring options is running a guided, test-focused grilling loop. This structured workflow evaluates deepening candidates, assesses trade-offs, and plans implementations to ensure actionable refactoring outcomes.

Does this deepening approach work for codebases without existing ADRs or domain glossaries?▼

This deepening approach is designed for large, multi-module projects that already satisfy domain-language alignment and include ADRs. Without these existing architectural records and glossaries, the structured grilling workflow lacks the necessary context for accurate analysis.

Why does my codebase architecture suffer from hidden friction and shallow interfaces?▼

Codebase architecture suffers from hidden friction when shallow modules lack deep, testable interfaces. Surfacing these architectural seams as deepening candidates transforms them into robust modules, guided by ADR considerations and domain-language alignment.

Related Skills

Explore More Software Engineering Skills→
automatedigitalautomatedigital
1

grill-with-docs

Align software plans with domain glossaries and architectural decision records.

Official
Intermediate
Insik-HanInsik-Han
16

improve-codebase-architecture

Identify shallow modules and propose deepening candidates in codebases.

Community
Advanced
miptah21miptah21
2

improve-codebase-architecture

Identify architectural friction and propose refactors that deepen module interfaces.

Community
Intermediate
openstatusHQopenstatusHQ
2.2k

improve-codebase-architecture

Identify architectural friction and generate RFCs for module-deepening refactors.

Official
Intermediate