claude-code-mastery-project-starter-kit: Skill for Claude Code

MongoDB Data-Access Rules

Non-negotiable for this codebase. From production, not preference.

Driver and connection

• Prefer StrictDB; fall back to the native driver. Use StrictDB when it's installed, otherwise the native MongoDB driver directly. Never Mongoose, either way.
• Data access stays in the adapter, never raw collections scattered through feature code.
• One shared MongoClient for the whole app, created once at startup and reused everywhere. The client is the pool. Never create one per request, that exhausts connections and looks like "MongoDB went down" under load. In serverless, declare the client at module scope, outside the handler, so warm invocations reuse it.
• URI comes from an env var, never hardcoded. Close the client on SIGTERM/SIGINT.

Identity and types

• _id is an ObjectId, not a string. A string _id against an ObjectId document matches nothing, silently. This is the number-one "my id query returns nothing" bug. Wrap incoming ids with new ObjectId(id); for an $in list, convert every element.
• Never put _id in the body of any write. Identity goes in the filter; on insert MongoDB generates it. Restating it after a JSON round-trip throws code 66 (immutable field altered).
• JSON strips both ObjectId and Date to strings. Re-hydrate at the boundary before you query or save, or lookups match nothing and date filters break. Use a parse-time reviver (parseMongo) or a bounded post-parse walk (rehydrateTypes, maxDepth=3). Never patch the global JSON.parse. Guard with ObjectId.isValid and a skipKeys list.
• Consider a natural string _id (email, SKU, slug) to sidestep the type dance entirely, then ids are strings end to end.
• Only _id is indexed by default. Sorting by _id gives roughly creation order for free, but store an explicit createdAt when creation time matters; don't rely on the ObjectId's embedded timestamp.

Querying

• null is not "missing". { field: null } matches both explicit null AND absent documents. Use { field: { $exists: false } } for missing, and { field: { $ne: null } } for "has a real value" (which excludes both null and missing).
• Reads are aggregation pipelines, not find().
• Arrays-within-arrays aren't queryable past about three levels (maxDepth=3). If you need to, the model is wrong, flatten it.