Claude Code Backend Architect Subagent: Contract-First API Design

要開一個新後端服務或 API，與其自己亂切邊界，不如叫一個專職架構師子代理：先定服務邊界與 API 契約，再規劃同步/非同步通訊、韌性與可觀測性。

[ Log in to see the full prompt ]

## What This Is / What Problem It Solves The most common disaster when starting a new backend service is drawing the boundaries wrong: services cut too finely lead to constant cross-service calls, while cutting them too coarsely means one change ripples through everything. APIs without contracts break downstream consumers the moment a version bumps. Resilience and observability always get deferred to 'later' and then the service gets hammered the moment it goes live. This 'backend architect' subagent structures these decisions into a 10-step process: first clarify non-functional requirements (scale, latency, consistency), then draw boundaries with domain-driven design (DDD), then design APIs contract-first, and only then plan out resilience, observability, security, performance, testing, and deployment one by one. Its clearest core belief is 'clear boundaries, explicit contracts, resilience built in from day one'—and it's pragmatic enough to remind you that if a monolith will do, don't force microservices prematurely. That's exactly the senior voice hitting the brakes that many teams are missing. ## Why This Source Is Worth Using wshobson/agents (maintained by Seth Hobson, MIT licensed, 36k+ GitHub stars) doesn't reduce backend-architect to vague architectural slogans—it lays out actionable technical options for every dimension: APIs cover REST/GraphQL/gRPC/WebSocket/SSE and pagination (offset/cursor/keyset); microservices cover DDD decomposition, service discovery, API gateways, service mesh, strangler/saga/CQRS patterns; event-driven architecture lists Kafka/RabbitMQ/SQS, event sourcing, and dead letter queues; resilience calls out circuit breakers, exponential backoff, bulkheads, and idempotency; observability specifies OpenTelemetry + correlation IDs + RED metrics. Framework coverage spans Node (Express/NestJS/Fastify), Python (FastAPI/Django), Java (Spring Boot/Quarkus), Go (Gin/Echo), .NET, Rust, and more. This breadth lets it give concrete recommendations within your actual stack instead of just principles. ## How to Use It (Steps) 1. Create `.claude/agents/backend-architect.md` in your project and paste in the full_prompt spec. Note that `model: inherit` means it uses whatever model powers your current conversation—since architecture design needs stronger reasoning, use a stronger model for the main conversation in Claude Code. 2. Trigger it with: 'Use backend-architect to design X service.' Give it your business requirements, expected scale, and latency/consistency requirements up front—its first step is clarifying exactly this. 3. It will produce, in order: service boundaries, API contracts (OpenAPI/GraphQL snippets), a Mermaid architecture diagram, resilience and observability strategy, technology choices with rationale, and a deployment strategy, along with trade-offs and alternatives. 4. Save the ADRs and diagrams into your repo as the team's architecture decision record. 5. Chain it further: it deliberately leaves database schema details to a database specialist and deep security scans to security-auditor, so it pairs well as one stage in a pipeline of subagents. ## When to Use It - Starting a new backend service or public API from scratch. - Deciding whether—and how—to split a monolith into multiple services. - Designing inter-service communication (sync vs. async) or introducing message queues or event streaming. - Not a fit for pure database tuning or frontend architecture—that's outside its defined boundary. 📎 Source: wshobson/agents (author: Seth Hobson, MIT license) — this piece is a Traditional Chinese adaptation; see the link above for the original.