backend-architect — Claude Code subagent: backend and API design
A subagent for backend design work: service boundaries, API paradigm choice, database schemas and observability. Useful when the decision comes before the first line of code.
npx claude-code-templates@latest --agent development-team/backend-architectWhat backend-architect does
backend-architect is a Claude subagent that handles design decisions rather than implementation. It works through bounded contexts and data ownership, picks an API paradigm for the specific case, and writes the contracts and schemas. For writing code from a finished design, the author points you to a separate agent, backend-developer.
The agent carries a defined order of work: clarify bounded contexts first, design APIs contract-first, then work out consistency requirements per aggregate. Observability gets its own section — structured logs with trace IDs, distributed tracing through OpenTelemetry, RED-method metrics, and /health, /ready, /metrics endpoints. Output includes a service diagram in Mermaid or ASCII, an OpenAPI 3.1 spec or Protobuf IDL, a database schema with indexes and sharding, plus bottlenecks and failure modes.
It can read and edit files, run commands and search the repo. Secrets belong in environment variables or Vault, never in source. If what you need is service code rather than service boundaries, this agent stops short — it stays at the level of decisions.
What it helps with
- split a monolith into services without downtime
- choose between REST, gRPC and GraphQL for a given case
- write API contracts before development starts
- design a database schema with indexes and sharding
- build tracing and metrics into the architecture from the start
Example prompts for the agent
- Split our Rails monolith into services: show the boundaries, contracts and migration order
- Design the backend for a ride-sharing service: trip lifecycle, matching, payments, PostgreSQL schema
- Pick an API paradigm for internal service-to-service calls and justify it
How to install backend-architect
1claude-code-templates
npx claude-code-templates@latest --agent development-team/backend-architect2Manually: put the files in place
.claude/agents/backend-architect.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/backend-architect.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/backend-architect.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about backend-architect
How do I install backend-architect in Claude?
Through the templates: npx claude-code-templates@latest --agent development-team/backend-architect. The agent file lands at .claude/agents/backend-architect.md.
What does backend-architect do?
It designs backend architecture: service boundaries, API paradigm, database schemas, event schemas and observability. Code from those decisions is written by another agent.
How is it different from backend-developer?
backend-architect makes the design decisions and produces specs; backend-developer implements the services from them.
