playbooks

home / skills / xfstudio / skills / architecture-patterns

architecture-patterns skill

/architecture-patterns

This skill helps you design and migrate backend systems using Clean, Hexagonal, and Domain-Driven patterns for scalable, testable architectures.

This is most likely a fork of the architecture-patterns skill from nilecui
npx playbooks add skill xfstudio/skills --skill architecture-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.5 KB
---
name: architecture-patterns
description: Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.
---

# Architecture Patterns

Master proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to build maintainable, testable, and scalable systems.

## Use this skill when

- Designing new backend systems from scratch
- Refactoring monolithic applications for better maintainability
- Establishing architecture standards for your team
- Migrating from tightly coupled to loosely coupled architectures
- Implementing domain-driven design principles
- Creating testable and mockable codebases
- Planning microservices decomposition

## Do not use this skill when

- You only need small, localized refactors
- The system is primarily frontend with no backend architecture changes
- You need implementation details without architectural design

## Instructions

1. Clarify domain boundaries, constraints, and scalability targets.
2. Select an architecture pattern that fits the domain complexity.
3. Define module boundaries, interfaces, and dependency rules.
4. Provide migration steps and validation checks.

Refer to `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

## Resources

- `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

Overview

This skill implements proven backend architecture patterns such as Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to produce maintainable, testable, and scalable systems. It guides pattern selection, module boundaries, and migration plans tailored to your domain constraints and scalability targets. Use it to standardize architecture decisions and reduce long-term technical debt.

How this skill works

I analyze your domain boundaries, constraints, and nonfunctional requirements, then recommend an appropriate pattern and concrete module interfaces. I produce dependency rules, layered or port-adapter layouts, and a step-by-step migration or implementation plan. Deliverables include interface sketches, testing strategies, and validation checks to ensure the design remains decoupled and testable.

When to use it

  • Designing a new backend for a complex domain
  • Refactoring a monolith to improve maintainability and testability
  • Establishing architecture standards across a team or organization
  • Decomposing a system toward microservices with clear domain boundaries
  • Applying Domain-Driven Design to align code with business concepts

Best practices

  • Clarify domain boundaries and ubiquitous language before choosing a pattern
  • Keep dependencies pointing inward and enforce interfaces at module edges
  • Write integration and boundary tests for adapters and ports
  • Introduce changes incrementally with a migration plan and validation checkpoints
  • Document module responsibilities and public interfaces for onboarding and maintenance

Example use cases

  • Refactor a legacy monolith into a hexagonal layout with clear adapters for I/O
  • Design a new service using Clean Architecture to separate use cases from frameworks
  • Apply DDD to model complex business rules and create bounded contexts
  • Extract domain logic into testable core modules and replace side-effecting code with adapters
  • Plan a phased migration to microservices while preserving transactional integrity

FAQ

Which pattern should I choose for a greenfield project?

Start with Clean Architecture for clear separation of concerns; adopt DDD if the domain is complex and requires rich modeling.

How do I migrate incrementally without breaking production?

Create an adapter layer around legacy code, introduce the domain core behind interfaces, and run validation checks after each small migration step.