name: mongodb-design slug: mongodb-design displayName: MongoDB 设计与使用助手 description: 帮助Agent为项目进行MongoDB文档模型设计、索引设计、聚合管道设计，并提供场景化使用指南。当用户需要设计MongoDB Schema、选择嵌入vs引用、设计聚合查询时触发。 version: 1.0.2 metadata: clawdbot: emoji: "🍃" requires: anyBins: ["mongosh", "mongo"] os: ["linux", "darwin"]

MongoDB 设计与使用助手

触发条件

当用户出现以下意图时激活本 Skill： - 设计 MongoDB 文档模型 / Schema - 嵌入 vs 引用的决策 - MongoDB 索引设计 - 聚合管道设计 - 分片方案

设计流程（Agent 执行路径）

0. 版本检查 → 加载 references/version-major.md 对比用户版本，识别废弃项和重大变更。同时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本），后续设计过程中 Agent 从已加载的上下文中自主匹配深度特性
1. 需求分析 → 理解数据实体、访问模式、增长预期
2. 文档模型设计 → 嵌入vs引用决策（加载 references/design-spec.md）
3. 索引设计 → ESR规则 + 查询模式匹配
4. 使用指引 → 加载 references/usage-guide.md，给出场景化操作
5. 生产建议 → 加载 references/best-practices.md，给出分片/一致性/性能建议
6. 模板参考 → 加载 references/patterns.md，匹配业务文档模型模板

快速参考

嵌入 vs 引用决策

ESR 索引规则

Equality → Sort → Range

// 查询
db.orders.find({ status: "paid" })          // Equality
  .sort({ created_at: -1 })                 // Sort
  .where("total").gt(100)                   // Range

// 索引（ESR顺序）
db.orders.createIndex({ status: 1, created_at: -1, total: 1 })

索引核心原则

1. 一个查询一个复合索引（优于多个单字段索引）
2. $match 在前可利用索引，$unwind 后不能
3. 覆盖查询：投影只包含索引字段
4. TTL 索引用于自动过期
5. 一个集合只能有一个文本索引

文档大小约束

11种官方 Schema 设计模式

渐进式加载

详细内容按需加载 references/：

版本参考文档启用规则

1. 模块激活时 — 始终加载 references/version-major.md，Agent 需主动对比用户使用的 MongoDB 版本，若存在废弃项或重大变更，立即提示用户
2. 深度特性 Step 0 自动加载 — 版本检查时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本）。设计过程中 Agent 从已加载的上下文中自主检索匹配相关特性，用户无需指定版本号
3. 深度特性按大版本拆分，小版本持续追加 — 如 version-8.0.md 包含该大版本下所有小版本的设计级特性。更新时在文件中新增 ## X.Y.Z 版本节即可，不单开文件

硬规则

1. 设计规范内容来自权威资料（MongoDB官方文档/阿里云MongoDB最佳实践），不编造
2. 单文档不超过 16MB，数组不超过 1000 元素
3. 索引必须遵循 ESR 规则
4. 能用嵌入解决的不要用 $lookup
5. 片键不可更改，选择要慎重
6. 避免单调递增片键（会成为热点）
7. 多文档事务有性能开销，尽量通过模型设计避免

这个Skill内容专业全面，涵盖MongoDB设计的各个方面，知识点讲解清晰易懂，对设计模式和最佳实践的总结很实用。但作为助手使用起来可能偏理论化，缺乏交互演示和实际案例引导，整体更像一份技术文档而非互动工具。如果需要实际项目设计指导，可能还需要额外补充更多场景化示例。