🧠 Cursor Rule — Design Scalable Microservices with Clear Runtime Contracts

Goal

Design microservices with clear boundaries, explicit contracts, and runtime validated communication so each service can scale, fail, and evolve independently.

Rule Behavior

1️⃣ Define Services Around Business Capabilities

• Group endpoints by domain such as auth, billing, catalog, and notifications
• Avoid splitting by technical layer only such as controllers, models, utils
• Ensure each service owns its data and core logic for its domain

2️⃣ Make Contracts Explicit And Executable

• Define request and response schemas for every public endpoint
• Use JSON schemas, TypeScript types, or OpenAPI for contract clarity
• Validate contracts at runtime using integration tests and agent executions

3️⃣ Choose Communication Patterns Intentionally

• Use synchronous HTTP or gRPC only for clear request response interactions
• Prefer async messaging or queues for long running or event based flows
• Avoid chatty back and forth calls that tightly couple services

4️⃣ Design For Failure And Isolation

• Assume dependencies will fail or be slow at runtime
• Implement timeouts, retries, and circuit breakers for remote calls
• Keep service failures contained so one outage does not cascade

5️⃣ Keep Services Independently Deployable

• Each service should build, test, and deploy without touching others
• Keep shared libraries small and focused to avoid lockstep changes
• Use versioned contracts to roll out changes safely

6️⃣ Trace Requests Across Service Boundaries

• Attach correlation or trace identifiers to each request
• Log service name, endpoint, and timing for each hop
• Use Agent to replay and inspect full journeys through the system

Examples

• "Propose service boundaries for auth, billing, and orders in this app."
• "Design API contracts for an order service and a payment service."
• "Simulate payment service failure and show how order service responds."

Tool Prompts

• "Analyze this monolith and suggest a microservice split with domain boundaries."
• "Generate OpenAPI or TypeScript interfaces for each service contract."
• "Run a request through multiple services and produce a trace of calls and timings."
• "Suggest retry and timeout settings for this cross service HTTP call."

Quick Implementation Wins

• Identify two or three clear domains and draft service boundaries
• Add basic tracing and correlation IDs to existing cross service calls
• Document public endpoints and contracts for at least one core service