backend-clean-architecture-guard

name	backend-clean-architecture-guard
description	Enforce backend design guardrails for a repository. Use when modifying or reviewing backend code, especially when adding services, endpoints, extractors, clients, dependency-injection wiring, or refactors. Prevent oversized classes, preserve Clean Architecture boundaries, apply SOLID pragmatically, and ensure modified files respect any existing .editorconfig directives before finishing.

Backend Clean Architecture Guard

Apply these guardrails before editing backend code and re-check them before finishing.

Scope

• Treat backend endpoints, handlers, services, use cases, domain models, repositories, adapters, infrastructure clients, and dependency-injection wiring as backend scope.
• Apply the skill for backend code changes, refactors, architectural reviews, and backend design proposals.
• Skip the skill for UI-only, docs-only, or ops-only changes unless they alter backend boundaries or backend workflow rules.

Enforce Clean Architecture

• Keep dependency direction stable:
  • Domain: pure business types and invariants; do not reference application, infrastructure, or API concerns.
  • Application: orchestration, use-case policy, abstractions, and options; depend on Domain, not on infrastructure details.
  • Infrastructure: adapters, IO, external clients, persistence, filesystem, HTTP, and concrete implementations of application abstractions.
  • Api: composition root, transport mapping, HTTP contracts, and request/response handling; keep business rules out of controllers and setup code.
• Decide the owning layer before coding. If code needs HTTP, filesystem, process, or third-party SDK details, it does not belong in Domain or Application.
• Prefer adding a new focused type in the right layer over pushing one more responsibility into an existing general-purpose service.

Prevent Large Classes

• Treat a growing class as a design smell before it becomes a god object.
• Split a class immediately when it starts to mix multiple concerns such as:
  • orchestration and domain rules
  • IO and business policy
  • validation and transport mapping
  • parsing/extraction and persistence
  • fallback strategy and external client details
• Use these heuristics:
  • one reason to change per class
  • one dependency cluster per class
  • one clear abstraction per file
• If a new change forces a class to coordinate unrelated workflows, extract a collaborator instead of extending the class.
• Prefer small orchestrators that compose focused collaborators over a single service that plans, fetches, validates, transforms, persists, and logs.

Apply SOLID Pragmatically

• Single responsibility: keep classes, handlers, services, and extractors narrowly focused.
• Open-closed: extend behavior through new types, strategies, or implementations instead of piling conditionals into a central class.
• Liskov substitution: preserve interface contracts; replacements must not weaken guarantees or require special-case callers.
• Interface segregation: keep interfaces small and task-specific; avoid "do everything" interfaces.
• Dependency inversion: depend on application-layer abstractions and wire concrete implementations through dependency injection at the edge.

Review Before Editing

• Identify the use case and the owning layer first.
• Check whether the target class already has more than one reason to change.
• If the change introduces a second responsibility, plan the extraction before editing.
• If the change introduces a new cross-cutting architecture or workflow rule, update the decisions registry rooted at docs/specs/DECISIONS.md.

Review Before Finishing

• Re-scan each modified backend file for boundary leaks and mixed responsibilities.
• Confirm that new abstractions are used only where they reduce coupling or isolate variation. Do not over-engineer.
• If .editorconfig exists in the repository or an ancestor directory, apply its directives to every modified file before closing the task.
• If .editorconfig does not exist, do not invent a formatting policy; keep style consistent with neighboring files.