backend-clean-architecture

Backend Clean Architecture

Purpose

Enforce strict layer separation in backend code. Domain layer has zero dependencies on frameworks, databases, or external libraries. Every piece of code must belong to exactly one layer.

Agent Protocol

Trigger

Exact user phrases: "where does this code go", "what layer", "clean architecture", "hexagonal", "ports and adapters", "domain layer", "application layer", "infrastructure layer", "should this be in service or repository", "layer violation", "architecture rule".

Input Context

Before activating, verify:

• The stack is known (NestJS, Go, Rust, Python, Spring Boot).
• The user has described a specific piece of code or asked about a specific location.
• The project's folder structure is visible or has been described.

Output Artifact

No file output. This skill produces text guidance.

Response Format

Answer exactly:

{code piece} -> {Layer}: {one-sentence justification}
File: {suggested file path}

If there is a violation:

VIOLATION: {file}:{line}
Layer {X} imports Layer {Y} which is NOT allowed.
Fix: {specific refactor instruction}
Direction: {layer name} -> {layer name} is the correct direction.

No preamble. No postamble. No explanations. No filler/hedging/transitions. Compress output.

Completion Criteria

• The layer for the code has been identified.
• If a violation exists, it has been identified with specific file/line.
• The fix direction has been specified.
• No layer rules have been explained — only applied.

Max Response Length

Layer assignment: 3 lines. Violation: 5 lines.

Architecture Decision Tree

Where Does This Code Go?

Is the code a business concept/rule?
  ├── Yes → Does it depend on a framework, DB, or external library?
  │         ├── No  → Domain Layer (Entity, Value Object, Domain Service, Repository Interface)
  │         └── Yes → INFRASTRUCTURE LAYER VIOLATION — extract pure logic to Domain
  ├── No → Does it orchestrate business operations?
  │         ├── Yes → Application Layer (Use Case, Command/Query Handler, Port Interface)
  │         └── No → Does it handle external input (HTTP, CLI, message)?
  │                  ├── Yes → Presentation Layer (Controller, Middleware, DTO, Resolver)
  │                  └── No → Does it implement external concerns?
  │                           ├── Yes → Infrastructure Layer (DB repo, API client, queue)
  │                           └── No → Reconsider the architecture — every piece fits one layer