# Microservices Design

> Design service boundaries, contracts, and failure modes for distributed systems

- Skill: `vignesh2027/microservices-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vignesh2027/microservices-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vignesh2027/microservices-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vignesh2027 (https://skillmd.com/u/vignesh2027)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vignesh2027/microservices-design

---


## Overview

Microservices solve a people problem (independent team deployments) while creating a technical problem (distributed systems complexity). This skill only adds microservices when they solve a real problem, and designs them to be independently deployable, failure-isolated, and observable.

## When to Use

- Before splitting a monolith into services
- When designing a new service in an existing distributed system
- When services are tightly coupled in ways that prevent independent deployment

## Process

### Step 1: Justify the split
A service split is justified when: teams are blocked on each other's deployments, scaling requirements differ dramatically, or technology requirements differ. Don't split for "separation of concerns" alone — a module achieves that at lower cost.

### Step 2: Define service boundaries by business capability
Services should own a business capability end-to-end. Don't split by technical layer (don't make a "user data service" that stores data for 10 other services).

### Step 3: Design the interface contract
Services communicate via explicit contracts. Define the contract before implementation. Version it from day one.

### Step 4: Choose communication style
- **Sync (HTTP/gRPC)**: Use when caller needs the result immediately
- **Async (messaging)**: Use when caller does not need immediate result; decouples availability

Async is better for resilience; sync is simpler to reason about. Choose based on the requirement.

### Step 5: Design for failure isolation
Service A must not fail because Service B is slow or unavailable:
- Timeouts on all outbound calls
- Circuit breakers for repeated failures
- Fallback responses or graceful degradation
- Bulkhead pattern: don't let one failing downstream exhaust connection pools

### Step 6: Distributed data
Each service owns its data store. No shared databases. Services that need data from another service: use the API, or replicate via events. Cross-service joins are a design smell.

### Step 7: Distributed tracing
All services propagate trace IDs. You must be able to trace a request across all services it touches.

## Verification Requirements

- [ ] Service split justified with a specific team or scaling problem
- [ ] Service boundary follows business capability
- [ ] Contract versioned from day one
- [ ] All outbound calls have timeouts and circuit breakers
- [ ] No shared databases between services
- [ ] Distributed tracing propagated