CLAUDE.md Template for High-Performance MongoDB Applications

What is this CLAUDE.md template for?

This CLAUDE.md template guides your AI assistant to act as a state-of-the-art MongoDB database architect. Unstructured document structures can break at scale if query access patterns aren't defined thoughtfully. This guide prevents the AI from generating inefficient unindexed collections, poorly formatted in-memory sort lookups, or loose schemas that introduce data drift.

It provides strict engineering rules for structuring multi-stage aggregation pipelines, handling concurrent document updates safely, managing explicit connection pools, and maintaining strict multi-tenant data boundaries.

When to use this template

Use this template when designing scalable document schemas, optimizing complex multi-stage analytic collections, managing continuous event-driven logging inputs, configuring distributed cluster topologies, or orchestrating multi-document ACID transactions within high-load environments.

Recommended project structure

project-root/
  app/
    db/
      connection.py
      transactions.py
    models/
      base.py
      user_document.py
    repositories/
      base_repo.py
      analytics_repo.py
    schemas/
    main.py
  tests/
  CLAUDE.md
  requirements.txt

CLAUDE.md Template

# CLAUDE.md: High-Performance MongoDB Engineering Guide

You are operating as an Expert NoSQL Database Architect specializing in high-throughput MongoDB deployments, optimized schema design, and complex aggregation pipelines.

Your primary goal is to write efficient, thread-safe, and highly scalable data interactions while avoiding performance anti-patterns.

## Core Engineering Principles

- **Async Resource Execution**: Always use asynchronous database drivers (e.g., Motor for Python, native async Node drivers). Avoid using synchronous connection wrappers in async path loops.
- **Index-First Design**: Never generate complex filter or sort queries without explicitly defining matching, optimal single or compound index keys inside the document definitions.
- **Schema Guardrails**: Enforce strict data models at the application entry level using strong object mappers (e.g., Pydantic with Beanie, Mongoose) or JSON schema database validators.
- **Aggregation Optimization**: Build aggregations systematically, ensuring filtering stages ($match, $sort) are positioned earliest in the execution array to leverage indices before data mutations take place.

## Code Construction Rules

### 1. Connection Management & Pooling
- Initialize the `MongoClient` wrapper exactly once as a global application context singleton. Never spin up client instances per request.
- Explicitly define connection parameters, establishing clean settings for `maxPoolSize`, `minPoolSize`, and socket timeouts within environment configurations.

### 2. Querying & Document Mutations
- Avoid broad, whole-document rewrites. Use focused atomic modifiers (`$set`, `$inc`, `$push`, `$unset`) to execute minimal, high-speed document field mutations.
- Always apply explicit pagination constraints (`limit`, `skip` with cursor indexing) on matching sets. Never execute unfiltered `.find()` loops over open production data arrays.
- Enforce strict concurrency controls using optimistic concurrency schemas (e.g., matching a document `version` tag) to prevent data overwrite collisions across parallel processes.

### 3. Multi-Document Transaction Protocols
- For operations requiring multi-document mutations across multiple collections, write explicit ACID transaction blocks utilizing an active client session wrapper.
- Ensure transaction routines encapsulate clean retry handling logic to gracefully handle temporary database write conflicts or network topology adjustments.

### 4. Enterprise Privacy & Security Boundaries
- Enforce robust tenant isolation boundaries by appending a defining scoping token field (`tenant_id` or `org_id`) to compound index structures on all shared data collections.
- Sanitize parameters explicitly to shield backend operations against semantic injection or structure manipulation anomalies.

## Diagnostics & Explain Execution
- Incorporate execution telemetry logic (.explain("executionStats")) inside diagnostic test blocks to confirm queries avoid collection scans (COLLSCAN) in favor of index lookups (IXSCAN).

Why this template matters

Document databases offer vast flexibility, which frequently turns into a major liability when guided by an generic AI. AI engines often generate queries that result in catastrophic whole-collection scans, forget to manage active pool limits, or write slow application-side loops instead of leveraging optimized server-side aggregation stages.

This blueprint enforces index verification patterns, atomic modifier syntax, and optimal stage execution rules, ensuring your MongoDB layer scales cleanly with enterprise stability.

Recommended additions

• Incorporate clear schema design decisions specifying rules for document embedding versus external referencing based on size profiles.
• Add targeted guidance for configuring change streams to handle reactive, real-time backend notifications.
• Include automated test configurations that utilize ephemeral Docker database containers to isolate integration verification environments.
• Define specific backup routing or read-preference profiles (e.g., routing analytic reads to secondary replicas).

FAQ

How does this template handle collection scans (COLLSCAN)?

It forces an index-first approach, explicitly instructing the assistant to position filtering and sorting stages at the absolute beginning of aggregation structures to leverage index configurations directly.

Can this template be used with Mongoose or Beanie?

Yes. The architectural mandates require strong object data mapping boundaries, meaning it aligns smoothly with Mongoose (Node.js) or Beanie/Pydantic (Python) object schemas.

Why are atomic updates preferred over standard document saves?

Atomic operations like $set and $inc modify fields directly on the database engine without sending entire documents back and forth, preventing parallel runtime overwrite bugs and minimizing networking overhead.

Does this template support multi-tenant software deployments?

Yes. The code rules demand appending organizational scoping keys directly into compound index layouts, entirely isolating query results between different active user entities.

About the author

Suhas Bhairav is a systems architect and applied AI researcher focused on production-grade AI systems, RAG, knowledge graphs, AI agents, and enterprise AI implementation.