skills.rest
Rayzerrek
RayzerrekCOMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

Identify architectural deepening opportunities in codebases with dependency and seam analysis.

Updated Jan 30, 2026
Search Tags:#architecture#refactoring#testability#adr#codebase analysis#seams#deepening
One-click install
npx skills add https://github.com/Rayzerrek/dotfiles --skill improve-codebase-architecture-rayzerrek
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Rayzerrek/dotfiles/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/Rayzerrek/dotfiles --skill improve-codebase-architecture-rayzerrek

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you identify architectural friction in a codebase and turn it into clear refactoring opportunities that make modules deeper, easier to test, and easier for AI to navigate.

Core Features & Use Cases

  • Architecture Review: Scan a repository for shallow modules, tangled seams, and places where complexity is spread across too many callers.
  • Refactoring Candidate Discovery: Surface concrete opportunities to consolidate logic, improve locality, and make tests cross the right interface.
  • Domain-Aware Analysis: Use the repository's glossary and ADRs so suggestions stay aligned with the project's own terminology and decisions.
  • Use Case: If a feature's logic is split across many small files with brittle tests, this Skill can recommend a deeper module and explain the trade-offs before you change anything.

Quick Start

Ask me to analyze this repository for architectural friction and list the strongest deepening 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 find refactoring opportunities in a codebase with shallow modules?▼

To find refactoring opportunities in a codebase with shallow modules, analyze the repository for architectural friction and tangled seams. This process classifies dependencies and produces candidate refactors to consolidate logic and create deeper modules.

What is a deep module in software architecture?▼

A deep module in software architecture is a component with a simple interface that hides significant complexity, improving locality and testability. Identifying shallow modules helps surface opportunities to consolidate logic into deeper, more maintainable structures.

How do I use ADRs to guide codebase refactoring?▼

To use ADRs to guide codebase refactoring, read the domain language and architecture decision records to ensure suggested refactors align with existing project terminology. This domain-aware analysis keeps deepening opportunities consistent with prior decisions.

How do I refactor tangled seams to improve code testability?▼

To refactor tangled seams and improve code testability, scan the repository for places where complexity is spread across too many callers. Surface concrete opportunities to improve locality so tests cross the right interface boundaries.

When should I analyze architectural friction before refactoring?▼

You should analyze architectural friction before refactoring when a feature's logic is split across many small files with brittle tests. This analysis evaluates leverage and trade-offs, ensuring refactoring decisions create deeper modules without unexpected regressions.

Related Skills

Explore More Software Engineering Skills→
tonombtonomb

to-spec

Synthesize conversation context and repository knowledge into structured technical specifications.

Community
Intermediate
susomejiassusomejias
9

improve-codebase-architecture

Identify shallow, tightly-coupled modules in codebases.

Community
Advanced
mistakeknotmistakeknot
3

intermap

Generate project-level code maps with call graphs and cross-project dependencies.

Community
Advanced
alangebalangeb

code-review-workflow

Run pyscan, pyanalyze, ruff, and black to generate a unified markdown report.

Community
Intermediate