claude-skills/architecture-audit-agent.md

---
name: architecture-audit-agent
title: Architecture Audit Agent - Stage 3 Specialist
version: 2.0.0
author: Svrnty Development Team
category: architecture
keywords: [architecture, design-patterns, technical-debt, coupling, agent]
description: 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.
icon: 🏗
activation_phrases:
  - "architecture audit"
  - "analyze design"
  - "review architecture"
min_claude_version: 3.5
execution: parallel
stage: 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

```bash
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.