opencode-workflow/skills/storage-mongodb/SKILL.md

name	description
storage-mongodb	MongoDB-specific code design reference for the Code Design Agent. Load only when the architecture or repository indicates MongoDB. Covers document modeling, collection boundaries, indexing, repository design, and consistency tradeoffs.

This skill provides MongoDB-specific guidance for code-level design.

Announce at start: "I'm using the storage-mongodb skill to apply MongoDB-specific code design conventions."

When To Load

Load this skill only when one or more of the following is true:

• The architecture explicitly names MongoDB
• The repository uses MongoDB drivers, collection names, or BSON models
• The architecture favors document-oriented aggregates and embedded data

Do not load this skill for relational-first designs.

Purpose

Translate document-oriented architecture into MongoDB-aware code design: collection boundaries, document shapes, indexing, repository contracts, and BSON mapping conventions.

MongoDB Design Rules

1. Model around access patterns, not normalized relational forms
2. Embed data when it is read together and bounded in size; reference when lifecycle or cardinality differs
3. Make collection-level indexes explicit in the code design doc
4. Use multi-document transactions only when the architecture truly requires cross-document atomicity
5. Keep document versioning and migration strategy explicit when schemas evolve

Collection Guidance

• Define one repository owner per collection or aggregate root
• Document shard keys or partitioning assumptions if scale requires them
• Call out whether a collection is append-heavy, read-heavy, or mutation-heavy

Model Guidance

• Separate domain models from persistence models when BSON layout differs from business shape
• Document _id, BSON tags, embedded documents, and optional fields clearly
• Make arrays, nested objects, and denormalized snapshots explicit

Query Guidance

• Design repository methods around concrete queries from the architecture
• Call out aggregation pipelines, secondary indexes, and sort patterns explicitly
• Document pagination style and consistency expectations

Operational Safeguards

• Note write concern and read concern expectations when relevant
• Note TTL indexes, retention strategy, and document growth risks
• Surface risks of unbounded arrays and large document rewrites

Output Constraint

This skill is reference-only. It does not create files by itself. Apply its guidance inside docs/code-design/{date}-{feature}.md only.