MongoDB Best Practices
Expert rules for schema design, indexing, and performance in MongoDB (NoSQL).
Best use case
MongoDB Best Practices is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Expert rules for schema design, indexing, and performance in MongoDB (NoSQL).
Teams using MongoDB Best Practices should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/mongodb-best-practices/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How MongoDB Best Practices Compares
| Feature / Agent | MongoDB Best Practices | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Expert rules for schema design, indexing, and performance in MongoDB (NoSQL).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# MongoDB Best Practices
## **Priority: P0 (CRITICAL)**
## Guidelines
- **Schema Design**:
- **Embed vs Reference**:
- **Embed** (1:Few): Addresses, Phone Numbers. Optimization: Read locality.
- **Reference** (1:Many/Infinity): Logs, Activity History. Optimization: Document size limits (16MB).
- **Bucket Pattern**: For time-series or high-cardinality "One-to-Many", bucket items into documents (e.g., `DailyLog`).
- **Indexing**:
- **ESR Rule**: Equality, Sort, Range. Order your index keys `(status, date, price)` if you query `status='A'`, sort by `date`, filter `price > 10`.
- **Text Search**: Use `$text` search instead of `$regex` for keywords. `$regex` is slow (linear scan) unless anchored (`^prefix`).
- **Covered Queries**: Project only indexed fields to avoid fetching the document (`PROJECTION` is key).
- **Explain Plan**: Target `nReturned` / `keysExamined` ratio of ~1. If `docsExamined` >> `nReturned`, index is inefficient.
- **Sharding (Horizontal Scale)**:
- **Shard Key**: Avoid monotonically increasing keys (e.g., `Timestamp`, `ObjectId`) for high-write workloads (creates "Hot Shards"). Use Hashed Sharding or high-cardinality natural keys.
- **Performance**:
- **Avoid `skip()`**: Use `_id` or sort-key based pagination (`bucket_id > last_id`). `skip(10000)` scans 10000 docs.
- **Aggregation**: Prefer Aggregation Framework (`$match`, `$group`) over bringing data to client (JS).
- **Operations**:
- **Write Concern**: Understand `w:1` (Ack) vs `w:majority` (Safe).
- **Transactions**: Use only when ACID across multiple documents is stricter than performance needs.
## Anti-Patterns
- **Large Arrays**: Don't let arrays grow unboundedly (`$push` without limit).
- **Client-Side Filtering**: Don't fetch 1MB document to use 1KB of data.
- **Deep Nesting**: Avoid >4 levels of nesting (hard to query/update).
## References
- [Best Practices Guide](references/best-practices.md)
- [Anti-Patterns](references/anti-patterns.md)
- [Postgres vs Mongo Comparison](references/postgres-comparison.md)Related Skills
nodejs-best-practices
Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
nextjs-best-practices
Next.js App Router principles. Server Components, data fetching, routing patterns.
MongoDB with Mongoose
Database patterns for user data and credentials storage
mongodb-expert
MongoDB document modeling, aggregation pipeline optimization, sharding strategies, replica set configuration, connection pool management, and indexing patterns. Use this skill for MongoDB-specific issues, NoSQL performance optimization, and schema design.
mongodb-development
MongoDB development guidelines with Payload CMS, Mongoose, aggregation pipelines, and TypeScript best practices.
mongodb-crud-operations
Master MongoDB CRUD operations, document insertion, querying, updating, and deletion. Learn BSON format, ObjectId, data types, and basic operations. Use when working with documents, collections, and fundamental MongoDB operations.
lit-best-practices
Lit web components best practices and performance optimization guidelines. Use when writing, reviewing, or refactoring Lit web components. Triggers on tasks involving Lit components, custom elements, shadow DOM, reactive properties, or web component performance.
laravel-12-best-practices
Software engineering best practices for Laravel 12.x, covering architecture, Eloquent, testing, security, and the new starter kits.
kafka-development-practices
Applies general coding standards and best practices for Kafka development with Scala.
jupyter-notebook-best-practices
Guidelines for structuring and documenting Jupyter notebooks for reproducibility and clarity.
js-ts-best-practices
JavaScript and TypeScript best practices covering naming conventions, control flow, state management, TypeScript patterns (avoid any/enum, prefer type over interface), safety (input validation, assertions, error handling), performance optimization (reduce branching/looping, memoization, defer await, cache property access, storage API caching), and documentation (JSDoc, comment markers). Use when writing JS/TS functions, refactoring code for performance, reviewing code quality, fixing type errors, optimizing loops or conditionals, adding validation, or improving error messages.
golang-best-practices
Comprehensive Go code review meta-skill. Coordinates 5 specialized domain skills. For targeted reviews, use domain-specific skills (concurrency-safety, clean-architecture). For full audits, use this meta-skill.