# backend-architect

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.

- subagent · `type=agent` · Claude Code · 23691 installs
- Author: davila7
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/development-team/backend-architect.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/agents/backend-architect

## What it 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.

## Install

### Claude Code (native platform)

1. **claude-code-templates**
```bash
npx claude-code-templates@latest --agent development-team/backend-architect
```

2. **Manually: put the files in place**
- File: `.claude/agents/backend-architect.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/backend-architect.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/backend-architect.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/development-team/backend-architect.md

## When to use it
- 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
- 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

## Similar
- [fullstack-developer](https://affpapa.org/en/nevibecode/agents/fullstack-developer.md) — subagent · 18117 installs
- [python-pro](https://affpapa.org/en/nevibecode/agents/voltagent-community-python-pro.md) — subagent · 11689 installs
- [python-pro](https://affpapa.org/en/nevibecode/agents/python-pro.md) — subagent · 11689 installs
- [typescript-pro](https://affpapa.org/en/nevibecode/agents/voltagent-community-typescript-pro.md) — subagent · 9602 installs
- [ai-engineer](https://affpapa.org/en/nevibecode/agents/ai-engineer.md) — subagent · 7687 installs
- [code-explorer](https://affpapa.org/en/nevibecode/agents/code-explorer.md) — subagent · 1172 installs

From the same set: [davila7/claude-code-templates](https://affpapa.org/en/nevibecode/by/davila7/claude-code-templates.md) — 205 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md