Architecture Testing

Overview

Enforce architectural boundaries with automated tests. Prevents coupling that causes maintenance debt.

REQUIRED: superpowers:test-driven-development, superpowers:verification-before-completion

When to Use

• User mentions architecture, boundaries, layers, dependency rules
• Creating production-quality application
• Opt-out offered: New apps without production/best-practice/pattern request

Detection and Deference

Before creating architecture tests, check for existing patterns:

Existing Tests Detection

Deference Rules

When existing architecture tests are detected:

1. Existing test project: Enhance with additional rules, do not create new project.
2. Existing architecture doc: Update existing doc, do not create duplicate.
3. Partial coverage: Add tests for uncovered boundaries only.

Only create new architecture test project when detection finds nothing.

Decision Capture

Architecture decisions must be captured in the target repository:

1. Architecture ADR: Create docs/decisions/NNNN-architecture-pattern.md
2. Architecture Overview: Update docs/architecture-overview.md
3. Test Project README: Document which boundaries are tested

Architecture ADR Template

# ADR-NNNN: Architecture Pattern Selection

## Status

Accepted

## Context

Project needs defined architectural boundaries.

## Decision

Use [Clean Architecture / Hexagonal / Layered] pattern.

## Rationale

- [Why this pattern fits the project]
- [Trade-offs considered]

## Consequences

- Architecture tests enforce: [list of rules]
- Violations fail the build

This ensures future developers understand the architectural constraints.

Core Workflow

1. Opt-out check: New app without production quality request? Offer opt-out explicitly
2. Pattern selection: Clean, Hexagonal, Onion, Layered, or Modular Monolith
3. Define boundaries: Minimum 3 layers with explicit dependency rules
4. Add enforcement: NetArchTest (.NET), ArchUnit (Java), or custom
5. CI integration: Tests in pipeline, fail build on violations
6. Document: Update docs/architecture-overview.md (human-readable)
7. Brownfield: Permissive initial tests, tighten incrementally

See Pattern Details and NetArchTest Examples.

Reference Templates

Use pre-built templates to accelerate architecture test setup:

Using Templates

1. Copy template to tests/{Project}.ArchitectureTests/
2. Replace {NAMESPACE} with your root namespace
3. Add NetArchTest NuGet package
4. Adjust layer names to match your project structure
5. Run tests to verify boundaries

Rationalizations Table

Red Flags - STOP

• "Can add architecture later"
• "Too simple for boundaries"
• "Would block the deploy" (without proposing brownfield)
• "Tech lead said skip it" (without clarifying cost)

All mean: Apply brownfield approach or document explicit opt-out in docs/exclusions.md.