home / skills / hoangnguyen0403 / agent-skills-standard / system-design

system-design skill

This skill helps you apply foundational architectural principles and patterns to design robust, scalable, and maintainable systems.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill system-design

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

Files (1)

SKILL.md

1.5 KB

---
name: System Design & Architecture Standards
description: Universal architectural standards for building robust, scalable, and maintainable systems.
metadata:
  labels: [system-design, architecture, scalability, reliability]
  triggers:
    keywords: [architecture, design, system, scalability]
---

# System Design & Architecture Standards

## **Priority: P0 (FOUNDATIONAL)**

## Architectural Principles

- **SoC**: Divide into distinct sections per concern.
- **SSOT**: One source, reference elsewhere.
- **Fail Fast**: Fail visibly when errors occur.
- **Graceful Degradation**: Core functional even if secondary fails.

## Modularity & Coupling

- **High Cohesion**: Related functionality in one module.
- **Loose Coupling**: Use interfaces for communication.
- **DI**: Inject dependencies, don't hardcode.

## Common Patterns

- **Layered**: Presentation → Logic → Data.
- **Event-Driven**: Async communication between decoupled components.
- **Clean/Hexagonal**: Core logic independent of frameworks.
- **Statelessness**: Favor stateless for scaling/testing.

## Distributed Systems

- **CAP**: Trade-off Consistency/Availability/Partition tolerance.
- **Idempotency**: Operations repeatable without side effects.
- **Circuit Breaker**: Fail fast on failing services.
- **Eventual Consistency**: Design for async data sync.

## Documentation & Evolution

- **Design Docs**: Write specs before major implementations.
- **Versioning**: Version APIs/schemas for backward compatibility.
- **Extensibility**: Use Strategy/Factory for future changes.

Overview

This skill provides universal architectural standards for building robust, scalable, and maintainable systems. It captures foundational principles, common design patterns, and operational guidance to shape architecture decisions across languages and frameworks. The guidance is framework-agnostic and intended to be applied to projects from mobile apps to distributed backends.

How this skill works

The skill inspects architecture decisions and recommends patterns that improve cohesion, reduce coupling, and increase resilience. It highlights principles such as separation of concerns, single source of truth, dependency injection, and stateless design and maps them to practical patterns like layered, event-driven, and hexagonal architectures. It also flags distributed-system concerns such as idempotency, circuit breakers, and trade-offs in CAP.

When to use it

Starting a new project and defining the overall architecture and boundaries
Refactoring monoliths into modular or distributed systems
Designing APIs, data models, or service contracts for forward compatibility
Evaluating operational resilience strategies for production systems
Onboarding teams to common coding and architecture standards

Best practices

Apply Separation of Concerns: keep presentation, business logic, and data access distinct
Favor high cohesion and loose coupling; use interfaces and dependency injection
Design for failure: fail fast, use circuit breakers, and implement graceful degradation
Prefer stateless components where possible to simplify scaling and testing
Document designs and version APIs/schemas to preserve backward compatibility
Use patterns (strategy, factory) to make behavior extensible without invasive changes

Example use cases

Defining module boundaries and DI strategy for a TypeScript backend using NestJS
Transforming a tightly coupled mobile app into clean, testable layers for React Native or Flutter
Designing an event-driven pipeline with idempotent handlers and retry semantics
Choosing consistency and availability trade-offs when sharding or partitioning data
Creating API versioning and migration plans for a microservice ecosystem

FAQ

How do I choose between layered and hexagonal architectures?

Use layered architecture for straightforward separation of concerns; choose hexagonal when you need a framework-independent core and easier testability of business rules.

When should I favor stateless services?

Favor stateless services when you need horizontal scalability and simple failure recovery; keep state in external stores or dedicated stateful services when necessary.