Database Architect Agent for Claude Code: Design Scalable Data Models Without the Guesswork

Why This Agent Exists

Database decisions are among the most expensive mistakes a development team can make. Choose the wrong data model in week one, and you’re paying for it in query rewrites, migration scripts, and downtime two years later. Pick the wrong database technology for your access patterns, and you’ll spend months bolting on workarounds that should have been architectural choices.

Most developers don’t lack intelligence — they lack time and context. A senior backend engineer knows the tradeoffs between normalization and denormalization in principle, but when they’re mid-sprint trying to ship a feature, they don’t have the bandwidth to reason through six competing schema designs or evaluate whether their microservices need event sourcing. They make the pragmatic choice, and pragmatic choices compound into technical debt.

The Database Architect agent changes that calculus. It brings specialized database design knowledge directly into your development workflow, available on demand, before decisions get baked into production code. It’s not a replacement for your DBA — it’s the database architect you can consult at 11pm when you’re designing a schema and need a second opinion grounded in real patterns.

The agent covers the full spectrum of modern database architecture: SQL schema design with proper constraints, NoSQL document modeling, polyglot persistence strategies, microservices data isolation, CQRS, event sourcing, sharding, and performance-first index design. That breadth means you can use it across wildly different projects without context-switching to different tools.

When to Use the Database Architect Agent

Deploy this agent proactively — before problems emerge, not after. Here are the situations where it pays off most:

• Starting a new service or feature: Before you write a single CREATE TABLE statement, use the agent to reason through your entity relationships, normalization level, and constraint requirements. Five minutes of design conversation saves five hours of migration work.
• Evaluating database technology: PostgreSQL vs MongoDB vs Cassandra vs DynamoDB is not a religious debate — it’s an engineering decision that depends on your read/write ratios, consistency requirements, query patterns, and team expertise. The agent helps you structure that decision with the right questions.
• Scaling an existing system: When you’re hitting query performance limits or anticipating 10x traffic growth, the agent can reason through horizontal partitioning strategies, read replica configurations, and caching layer architectures specific to your schema.
• Designing microservices data boundaries: Database-per-service is the right pattern — until you need cross-service joins. The agent helps you identify where bounded contexts should live, how to handle eventual consistency, and when shared databases are a pragmatic tradeoff versus an antipattern.
• Code review of schema changes: Paste a migration file and ask the agent to identify missing indexes, constraint gaps, or normalization issues before they hit production.
• Event sourcing and CQRS implementation: These patterns have significant complexity overhead. The agent can help you decide whether you actually need them and, if so, how to model your event store and projections correctly.

Real-World Examples

Scenario: E-commerce Platform Schema Design

A developer is building a new e-commerce platform and needs to design the core data model. They want to handle customer addresses, a product catalog with hierarchical categories, and orders — and they need it to scale.

Developer: I'm building an e-commerce platform on PostgreSQL. I need to handle
customers with multiple addresses, a product catalog with nested categories,
and orders. What should I watch out for when designing this schema?

Database Architect: A few critical decisions upfront. For customers and addresses,
use a separate addresses table with a foreign key — don't embed addresses as
columns on the customers table. You'll need multiple addresses per customer and
address types (billing vs shipping). Add a partial unique index to enforce that
only one default address exists per type per customer:

  UNIQUE(customer_id, address_type, is_default) WHERE is_default = true

For hierarchical categories, use adjacency list (parent_id self-reference) for
simple trees, or ltree extension if you need efficient subtree queries. Add a
CHECK constraint to prevent self-referencing. For unlimited depth queries,
you'll want recursive CTEs.

Products need inventory_count with a CHECK (inventory_count >= 0) constraint
and a version column if you're doing optimistic locking. Use DECIMAL(10,2) for
prices — never FLOAT for currency.

For orders, the critical design choice is how you snapshot product data. You
don't want order line items referencing live product prices — if a product price
changes, old orders should reflect what the customer actually paid. Store price
at time of purchase directly on the order line items table.

What's your expected order volume? That'll affect whether you need table
partitioning on orders from day one.

Scenario: Microservices Data Architecture

An engineering team is decomposing a monolith into microservices and struggling with the data layer. They want database-per-service but keep needing cross-service data.

Developer: We're splitting a monolith into microservices. We want database-per-service
but our reporting service needs data from five different services. How do we handle this?

Database Architect: This is the canonical microservices data tension. You have
three real options:

1. API composition in the reporting service — call each service's API and join
in application code. Simple, but slow for complex reports and puts load on
operational services.

2. Event-driven data replication — each service publishes domain events to a
message broker (Kafka, etc.). The reporting service maintains its own read model
by consuming those events. This is eventually consistent but gives you query
freedom without coupling services.

3. A dedicated analytics database — operational databases feed a data warehouse
(Redshift, BigQuery, ClickHouse) via CDC or ETL. Your reporting service queries
the warehouse. Best for complex analytics, but adds infrastructure overhead.

For most teams, option 2 is the right starting point. Your reporting service
owns a read-optimized schema that's purpose-built for reporting queries — fully
denormalized, pre-joined, indexed for your specific report patterns. The tradeoff
is eventual consistency and needing to handle event replays when your read model
schema changes.

What kinds of reports are you generating? Real-time operational dashboards or
periodic business intelligence reports? That distinction drives the latency
tolerance and significantly affects the architecture.

What Makes This Agent Powerful

Design Philosophy Embedded in Every Response

The agent doesn’t just generate SQL — it reasons from first principles. Domain-Driven Design alignment, data locality for performance, and the tradeoffs between normalization and query efficiency are baked into how it approaches every schema question. You get recommendations that consider your business domain, not just your immediate technical requirement.

Concrete, Production-Ready SQL

The agent generates real PostgreSQL DDL with proper types, constraints, and indexes — not pseudocode or hand-wavy diagrams. That means the examples it produces are starting points you can actually use, with business rules encoded directly as database constraints rather than relying solely on application-layer validation.

Breadth Across Patterns

From simple CRUD schemas to event sourcing with immutable event logs and projection tables, CQRS read/write model separation, and sharding strategies — the agent covers the full architecture pattern space. It can help you evaluate whether a pattern fits your problem, not just explain what the pattern is.

Technology Selection Reasoning

SQL vs NoSQL is rarely a binary choice. The agent is equipped to reason through polyglot persistence — using PostgreSQL for transactional data, Redis for caching and session state, Elasticsearch for full-text search, and a time-series database for metrics, all within a single system. It treats technology selection as an engineering decision driven by access patterns and consistency requirements.

Performance by Design

Index strategy, query pattern alignment, and data locality considerations are integrated into schema design recommendations from the start — not retrofitted after slow query complaints start arriving.

How to Install

Installing Claude Code agents is straightforward. Create the following file in your project or home directory:

.claude/agents/database-architect.md

Paste the full agent system prompt into that file and save it. Claude Code automatically discovers and loads agents from the .claude/agents/ directory — no configuration files to edit, no CLI flags to set.

You can scope the agent to a specific project by placing the .claude/agents/ directory inside that project’s root. For a globally available agent across all your projects, place it in your home directory at ~/.claude/agents/database-architect.md.

Once the file exists, you can invoke the agent directly in Claude Code by referencing it in your prompt, or Claude Code will select it automatically when you’re working on database-related tasks. The agent name in the filename (database-architect) is how it’s identified in the system.

No dependencies, no API keys, no separate installation steps. The agent runs entirely within your existing Claude Code environment.

Conclusion: Make Database Decisions Deliberately

Database architecture is one of the few areas of software development where the cost of a wrong decision grows super-linearly over time. A bad schema choice in month one becomes a painful migration in month twelve and a fundamental scaling constraint in year three.

The Database Architect agent gives you a knowledgeable counterpart for every significant data modeling decision — available in the context where you’re actually making those decisions, not in a meeting room after the fact.

Start by installing the agent and using it on your next schema design task. Bring it an existing table structure and ask it to identify constraint gaps or index opportunities. Use it to reason through whether your current monolith database is actually ready for service decomposition. The value becomes apparent quickly.

The best database designs look obvious in hindsight. This agent helps you get there on the first pass.

Agent template sourced from the claude-code-templates open source project (MIT License).