arch-audit

Analyze codebases to surface architectural smells and plan refactors.

1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/maxenko/claude-skills --skill arch-audit-maxenko
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: arch-audit
Source: https://github.com/maxenko/claude-skills/tree/main/arch-audit
Command: npx skills add https://github.com/maxenko/claude-skills --skill arch-audit-maxenko

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Analyzes an entire codebase to surface architectural smells, spaghetti patterns, tangled dependencies, and structural debt — prescribes concrete refactors grounded in Ousterhout, Fowler, Hickey, Feathers, and connascence theory. It helps teams identify where to start, what to change, and in what order to execute large-scale restructuring while preserving behavior.

Core Features & Use Cases

  • Surface architectural smells (coupling, cohesion, abstraction, evolution signals) across modules and generate prioritized findings.
  • Propose concrete refactors with explicit seams and step-by-step execution patterns (Parallel Change, Strangler Fig, Branch by Abstraction).
  • Provide executable plans with fitness checks, rollback signals, and documented risks for CI integration.

Quick Start

Provide the repository path or scope to begin the architecture audit.

Frequently Asked Questions about arch-audit

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

FAQPage Schema
How do I identify architectural smells and structural debt in a large codebase?

An architecture audit analyzes an entire codebase to surface architectural smells like coupling and cohesion issues. It evaluates evolution signals across modules to pinpoint tangled dependencies and spaghetti patterns, generating prioritized findings for structural debt.

What is the best way to plan a large-scale refactor without changing existing behavior?

Planning a large-scale refactor while preserving behavior requires defining concrete seams and applying execution patterns like Strangler Fig or Branch by Abstraction. These patterns isolate changes incrementally, ensuring system behavior remains stable throughout the restructuring process.

How do I find where to start restructuring a multi-language repository?

To find where to start restructuring a multi-language repository, analyze the codebase to surface prioritized architectural findings. The audit evaluates structural dependencies and evolution issues to pinpoint the exact modules requiring immediate intervention and precise refactoring.

Can I use connascence and coupling theory to guide codebase refactoring?

Yes, you can use connascence and coupling theory to guide codebase refactoring. Analyzing an entire codebase through these architectural lenses surfaces structural smells and prescribes concrete refactors grounded in established software design principles.

What execution patterns are recommended for resolving tangled dependencies?

Recommended execution patterns for resolving tangled dependencies include Parallel Change, Strangler Fig, and Branch by Abstraction. These patterns provide step-by-step execution strategies with explicit seams to safely separate coupled modules during a refactor.