Advisor Backend Developer

A senior backend development agent with deep expertise in Node.js, Python, and Go, focused on building scalable, secure, and performant server-side applications with proper API design, database integration, and deployment patterns.

When to Use This Agent

Choose Backend Developer Advisor when:

• Building REST or GraphQL APIs with Node.js, Python, or Go
• Designing database schemas and data access patterns
• Implementing authentication, authorization, and security middleware
• Optimizing backend performance (caching, connection pooling, async patterns)
• Setting up server-side testing strategies and CI pipelines

Consider alternatives when:

• Designing high-level architecture without writing code (use an architecture agent)
• Building frontend components (use a frontend development agent)
• Setting up infrastructure without application code (use a DevOps agent)

Quick Start

Copy
# .claude/agents/advisor-backend-developer.yml
name: Backend Developer Advisor
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a senior backend developer. Build scalable server-side
  applications with Node.js 18+, Python 3.11+, or Go 1.21+.
  Follow security best practices, write comprehensive tests,
  and design clean APIs. Always review existing patterns before
  writing new code.

Example invocation:

Copy
claude --agent advisor-backend-developer "Build a REST API for
  user management with JWT auth, role-based access control,
  rate limiting, and proper input validation using Express
  and PostgreSQL"

Core Concepts

Backend Application Structure

src/
├── routes/          # Route definitions and request handling
├── controllers/     # Request/response logic
├── services/        # Business logic
├── models/          # Data models and database schemas
├── middleware/       # Auth, validation, error handling
├── utils/           # Shared utilities
├── config/          # Environment and app configuration
└── tests/           # Unit, integration, and API tests

API Design Patterns

Pattern	Use Case	Example
REST	Standard CRUD operations	GET /api/users/:id
GraphQL	Flexible queries, multiple clients	query { user(id: 1) { name } }
gRPC	Internal microservice communication	Proto-defined service calls
WebSocket	Real-time bidirectional	Chat, live dashboards
SSE	Server-to-client streaming	Notifications, feeds

Security Checklist

Input:     Validate all inputs (schema validation, sanitization)
Auth:      JWT with short expiry + refresh tokens
Headers:   CORS, CSP, X-Content-Type, HSTS
Rate:      Rate limiting per IP and per user
Secrets:   Environment variables, never in code
SQL:       Parameterized queries, never string concatenation
Deps:      Regular dependency audits (npm audit, pip audit)
Logging:   Never log passwords, tokens, or PII

Configuration

Parameter	Description	Default
language	Primary backend language	Node.js (TypeScript)
framework	Web framework	Express
database	Primary database	PostgreSQL
auth_method	Authentication strategy	JWT
test_framework	Testing framework	Jest / Pytest
api_style	API architecture	REST
orm	Database ORM/query builder	Prisma / SQLAlchemy

Best Practices

1. Validate all external input at the API boundary with schema validation. Use libraries like Zod (TypeScript), Pydantic (Python), or go-playground/validator (Go) to define input schemas. Reject invalid requests before they reach business logic. Schema validation catches malformed data, prevents injection attacks, and documents the expected input format. Never trust client-side validation alone.

2. Separate business logic from HTTP handling. Controllers handle request parsing and response formatting. Services contain business logic that's independent of the transport layer. This separation lets you test business logic without HTTP mocking, reuse logic across different API endpoints, and swap frameworks without rewriting business rules.

3. Use database transactions for operations that modify multiple tables. When creating an order requires inserting into orders, order_items, and updating inventory, wrap all operations in a transaction. If any step fails, the entire operation rolls back to a consistent state. Without transactions, partial failures leave data in an inconsistent state that's difficult to detect and repair.

4. Implement structured error handling with consistent error responses. Define an error response format and use it everywhere: { error: { code: "VALIDATION_ERROR", message: "...", details: [...] } }. Create custom error classes that map to HTTP status codes. Use error-handling middleware to catch unhandled errors and format them consistently. Clients should never receive raw stack traces.

5. Write tests at three levels: unit, integration, and API. Unit tests verify individual functions. Integration tests verify service interactions with databases and external services. API tests verify the full request/response cycle. Aim for high unit test coverage (80%+), targeted integration tests for critical paths, and API tests for every endpoint's happy path and main error cases.

Common Issues

API response times increase as the application grows. Profile requests to identify bottlenecks: N+1 database queries, missing indexes, synchronous calls to external services, and large response payloads. Add database query logging to catch N+1 patterns early. Use caching (Redis) for frequently accessed data. Convert synchronous external calls to async with message queues when responses aren't needed immediately.

Authentication token handling becomes complex across services. Centralize token validation in middleware that runs before route handlers. Pass the validated user context through the request object, not through additional token validation in each service. For microservices, use an API gateway that validates tokens once and passes user context via headers to downstream services.

Database connection pool exhaustion under load. Set pool sizes based on the number of concurrent database operations your application performs, not the number of HTTP connections. Monitor active and idle connections. Return connections to the pool promptly by avoiding long-running transactions and ensuring all query results are consumed. Connection leaks (unreturned connections) are the most common cause of pool exhaustion.