architecture-audit

Analyze codebases to surface architectural friction and outline deep-module refactor RFCs.

12|1|Updated Feb 13, 2026
One-click install
npx skills add https://github.com/helderberto/skills --skill architecture-audit-helderberto
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-audit
Source: https://github.com/helderberto/skills/tree/main/architecture-audit
Command: npx skills add https://github.com/helderberto/skills --skill architecture-audit-helderberto

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Explore a codebase to surface architectural friction and propose deep-module refactors as GitHub RFCs. Use when you want to improve architecture, identify refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Don't use for small one-off refactors or single-file cleanups.

Core Features & Use Cases

  • Surface architectural friction between modules and boundaries to guide improvement.
  • Propose deep-module refactors as RFCs with clear boundaries and rationale.
  • Provide guidance for identifying coupling points and testability gaps.
  • Use case: refactor a monolith into modular components with stable interfaces.

Quick Start

Analyze a codebase to surface architectural friction and outline deep-module refactor RFCs.

Frequently Asked Questions about architecture-audit

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

FAQPage Schema
How do I identify architectural friction in a large legacy codebase?▼

To identify architectural friction in a codebase, explore workflows to surface tightly coupled modules and testability gaps. The process frames the problem space by highlighting deep-module refactor opportunities and boundary consolidation candidates.

What is the best way to plan a monolith refactor into modular components?▼

The best way to plan a monolith refactor is to outline deep-module improvements as RFCs. This approach designs multiple interface directions with clear boundaries and rationale, ensuring stable modular components within the codebase.

How do I document refactoring opportunities for tightly coupled modules?▼

Document refactoring opportunities for tightly coupled modules by proposing deep-module refactors as RFCs. Frame the problem space by outlining interface directions, documenting dependencies, and detailing testing considerations for the codebase.

Can I use an architecture audit for small single-file cleanups?▼

An architecture audit is not suitable for small single-file cleanups or one-off refactors. It is designed for large or legacy codebases where the goal is to surface architectural friction and consolidate deeply coupled modules.

When do I need to surface deep-module refactor candidates?▼

You need to surface deep-module refactor candidates when improving architecture in a large codebase with tightly coupled modules. This process helps identify coupling points, testability gaps, and boundaries to make the codebase more AI-navigable.

Does an architecture audit help make a codebase more testable?▼

Yes, an architecture audit helps make a codebase more testable by identifying coupling points and testability gaps. It proposes refactors with clear boundaries and stable interfaces to reduce architectural friction between modules.