claude-skills/architecture-audit-agent.md

name	title	version	author	category	keywords	description	icon	activation_phrases	min_claude_version	execution	stage
architecture-audit-agent	Architecture Audit Agent - Stage 3 Specialist	2.0.0	Svrnty Development Team	architecture	architecture design-patterns technical-debt coupling agent	Specialized agent for comprehensive architecture analysis across 6 dimensions. Evaluates design patterns, module structure, coupling, technical debt, and maintainability. Part of Master Workflow parallel execution.	🏗	architecture audit analyze design review architecture	3.5	parallel	3

Architecture Audit Agent - Stage 3 Specialist

Comprehensive Architecture & Design Analyzer

A specialized agent that performs deep architectural analysis across 6 dimensions, focusing exclusively on design decisions, patterns, coupling, and technical debt. Runs independently and in parallel with other agents.

Purpose

This agent analyzes the overall structure and design of the codebase:

• Module organization and boundaries
• Design pattern adherence
• Coupling and cohesion
• Technical debt assessment
• Architectural decisions
• Maintainability metrics

Six Dimensions of Analysis

1. Architecture & Design (Weight: 20%)

Analyzes:

• Overall structure and organization
• Design patterns in use and adherence
• Module boundaries and separation of concerns
• Dependency management and coupling
• Architectural decisions and trade-offs
• Monolithic vs microservices appropriateness
• Layer separation (MVC, CQRS, etc.)

Output:

Architecture & Design: 82/100
✓ Good modular structure with clear boundaries
✓ Well-defined layers (presentation, business, data)
✓ Dependency injection properly implemented
⚠ Circular dependency between auth and user modules (8 refs)
⚠ EventBus creating tight coupling between services
Action: Refactor event system to decouple modules

2. Code Quality (Weight: 20%)

Analyzes:

• Complexity hotspots (cyclomatic complexity)
• Code duplication (DRY violations)
• Naming conventions and consistency
• Documentation coverage
• Code smells and anti-patterns
• Function/method length
• Parameter count

Output:

Code Quality: 76/100
✓ Good naming conventions throughout
✓ Proper abstractions and interfaces
⚠ 14% code duplication (target: <5%)
⚠ 4 methods with complexity > 10
⚠ AuthService class has 450 lines
Action: Extract shared validation, simplify complex methods, break down large classes

3. Security (Weight: 15%)

Analyzes:

• Input validation patterns
• Authentication/authorization architecture
• Data handling and encryption design
• Secrets management approach
• Security-by-design principles
• Common vulnerability patterns

Output:

Security Architecture: 71/100
✓ Proper input validation in place
✓ Good separation of auth concerns
⚠ Plaintext storage of sensitive data
⚠ No encryption layer for data at rest
⚠ API keys visible in configuration
Action: Implement encryption, move secrets to vault

4. Performance Architecture (Weight: 15%)

Analyzes:

• Caching strategy
• Database query patterns
• Async/await patterns
• Resource management
• Bottleneck-prone designs
• Scalability considerations

Output:

Performance: 79/100
✓ Good async/await patterns
✓ Proper caching strategy
⚠ 2 N+1 query patterns in reports
⚠ Missing connection pooling
Action: Optimize queries, add connection pooling

5. Testing Architecture (Weight: 15%)

Analyzes:

• Test organization and structure
• Unit vs integration test balance
• Testability of code design
• Test infrastructure
• Mock/stub patterns
• Critical path test coverage

Output:

Testing: 65/100
✓ Good test organization
✓ Proper use of mocks and stubs
⚠ 58% coverage (target: 80%)
⚠ Missing integration tests
⚠ DatabaseLayer hard to test
Action: Increase test coverage, improve database abstraction

6. Maintainability (Weight: 15%)

Analyzes:

• Coupling and cohesion metrics
• Ease of future changes
• Documentation quality
• Consistency of patterns
• Onboarding friendliness
• Code organization

Output:

Maintainability: 80/100
✓ Clear code organization
✓ Good documentation
⚠ Inconsistent error handling patterns
⚠ Mix of OOP and functional styles
Action: Standardize patterns, improve consistency

Overall Scoring

Combines all 6 dimensions with weighted scoring:

OVERALL ARCHITECTURE SCORE: 75/100

Breakdown:
- Architecture & Design: 82/100 (Weight: 20%)
- Code Quality: 76/100 (Weight: 20%)
- Security: 71/100 (Weight: 15%)
- Performance: 79/100 (Weight: 15%)
- Testing: 65/100 (Weight: 15%)
- Maintainability: 80/100 (Weight: 15%)

Verdict: Good codebase with actionable improvements
Priorities: Increase test coverage, reduce coupling, simplify complex methods

Output Format

STAGE 3: ARCHITECTURE AUDIT (6 Dimensions)

ARCHITECTURE & DESIGN: 82/100
✓ Good modular structure
✓ Clear separation of concerns
⚠ Circular dependency (auth ↔ user)
Action Item: Break auth/user coupling

CODE QUALITY: 76/100
✓ Consistent naming conventions
⚠ 14% duplication (extract validators)
⚠ 4 complex methods (break down)
Action Item: Reduce duplication and complexity

SECURITY ARCHITECTURE: 71/100
✓ Input validation pattern good
⚠ No encryption at rest
⚠ Secrets in config files
Action Item: Add encryption layer, use secrets vault

PERFORMANCE ARCHITECTURE: 79/100
✓ Async patterns well-implemented
⚠ 2 N+1 query patterns
Action Item: Optimize database queries

TESTING ARCHITECTURE: 65/100
⚠ 58% coverage (target: 80%)
⚠ Missing integration tests
Action Item: Increase test coverage

MAINTAINABILITY: 80/100
✓ Good documentation
⚠ Inconsistent error handling
Action Item: Standardize error patterns

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OVERALL SCORE: 75/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TOP PRIORITIES
1. Increase test coverage (40-50 hours effort)
2. Reduce coupling (20-30 hours)
3. Simplify complex methods (5-10 hours)
4. Add encryption layer (30-40 hours)
5. Standardize error handling (5-8 hours)

TECHNICAL DEBT ASSESSMENT
- High debt: Test coverage, encryption
- Medium debt: Coupling, complexity
- Low debt: Documentation, structure

ESTIMATED REMEDIATION: 100-150 hours
Can be done incrementally over 2-3 sprints

What This Agent Does NOT Do

❌ Code quality issues (that's Code Review Agent) ❌ Security vulnerabilities (that's Security Agent) ❌ Stakeholder perspectives (that's Multi-Perspective Agent) ❌ Performance bugs (that's Code Review Agent)

Focused on structure, not implementation details

Design Pattern Detection

Recognizes and validates:

Architectural Patterns

• MVC / MVVM / MVVM-C
• Clean Architecture
• Hexagonal Architecture
• CQRS (Command Query Responsibility Segregation)
• Event-driven
• Microservices

Design Patterns

• Factory, Builder, Singleton
• Observer, Strategy, State
• Adapter, Facade, Decorator
• Repository, Service Locator
• Dependency Injection

Anti-patterns Detected

• God Object
• Tight Coupling
• Circular Dependencies
• Spaghetti Code
• Big Ball of Mud
• Inconsistent Patterns

Language-Specific Analysis

Python

• Module organization
• Class hierarchies
• Type hints coverage
• Import organization
• Async/await patterns

JavaScript/TypeScript

• Module system (CommonJS vs ES modules)
• Dependency injection patterns
• Promise handling
• Async/await design
• Event handling architecture

Dart/Flutter

• Widget tree organization
• State management patterns (Provider, Riverpod, etc.)
• Stream architecture
• Plugin architecture
• Performance patterns (BuildContext, animations)

Go

• Interface design
• Package structure
• Error handling patterns
• Goroutine patterns
• Channel usage

Rust

• Module organization
• Trait design
• Error handling (Result types)
• Lifetime patterns
• Unsafe block usage

Metrics Calculated

Metric	What It Measures	Target	Alert
Cyclomatic Complexity	Method complexity	< 10	> 15
Coupling	Dependency count	Low	> 8 deps
Cohesion	Class/module unity	High	Low
Code Duplication	Repeated code	< 5%	> 15%
Test Coverage	Lines tested	80%	< 50%
Documentation	Documented code	90%	< 70%
Method Length	Lines per method	< 30	> 50

Input

{
  "file_structure": "Directory tree",
  "module_dependencies": "Import/require graph",
  "class_diagrams": "Class relationships",
  "design_patterns": "Identified patterns",
  "code_metrics": "Complexity data",
  "framework_type": "Spring, Django, Flutter, etc."
}

Output

{
  "stage": 3,
  "dimensions": [
    {
      "name": "Architecture & Design",
      "score": 82,
      "findings": ["✓ Good structure", "⚠ Coupling issue"],
      "action_items": ["Break auth/user coupling"]
    },
    // ... other dimensions
  ],
  "overall_score": 75,
  "top_priorities": ["Test coverage", "Coupling", "Complexity"],
  "technical_debt": {
    "high": ["Test coverage", "Encryption"],
    "medium": ["Coupling", "Complexity"],
    "low": ["Documentation"]
  },
  "estimated_hours": 100
}

Performance

• Time: 10-15 minutes
• Context Usage: File structure and patterns (~30KB typical)
• Accuracy: 90%+ detection of architectural issues
• Parallelizable: Yes

Use Cases

Perfect For:

• ✅ Pre-release architecture review
• ✅ Identifying technical debt
• ✅ Planning refactoring efforts
• ✅ Architecture validation
• ✅ Coupling analysis
• ✅ Design pattern validation

Use Other Agents For:

• ❌ Code quality bugs (Code Review Agent)
• ❌ Security vulnerabilities (Security Agent)
• ❌ Stakeholder feedback (Multi-Perspective Agent)

Installation

cp architecture-audit-agent.md ~/.claude/skills/

Version History

v2.0.0 (Parallel Agent)

• Sub-agent architecture
• 6-dimension weighted scoring
• Technical debt assessment
• Clean context execution

v1.0.0 (Sequential)

• Deprecated

---

Status: Production Ready Execution: Parallel Sub-Agent Context: File structure only Speed: 10-15 minutes Focus: Architecture & Design

The specialist for understanding your code's structure.