authoring-data-model

authoring-data-model — SKILL.md

变体： 标准 · 使用时机： 编写数据模型文档。此技能提供编写方法和完整性/可查询性标准；章节结构来自与之组合使用的独立数据模型模板工具。请勿在此重述该模板的大纲。

概述

数据模型文档是系统存储数据的持久化/领域模型——工程师据此实现架构，所有查询数据的人都会阅读该模型。此技能指导编写者撰写此类文档：从上游功能规格中推导实体，识别存储范式并据此建模，明确完整性规则，并根据访问模式说明每个索引的理由。它传授的是方法——研究方法和质量标准——并与提供章节结构的独立模板工具配合使用。标准是：“工程师能够据此创建架构并编写正确的查询，而且模型的完整性规则和权衡取舍都清晰明确。”

此技能适用于多种范式：相同的建模严谨性（实体、关系、完整性、有依据的索引、明确说明的权衡取舍）适用于关系型/SQL、文档型/NoSQL、图、宽列和键值存储；只有产物会有所不同。下文详细介绍关系型和文档型两种路径；其他范式则使用各自的惯用方式建模（步骤 2）。

何时启用

• 已有上游功能规格（以及适用时，标明存储的架构文档），需要为系统或功能编写或大幅修订数据模型/架构设计文档。
• 编写者需要方法（如何推导实体、建模关系、说明索引理由、阐明权衡取舍）以及可构建、可查询的模型必须达到的标准，而不是一张空白页面。

请勿在以下情况启用：

• 审查或评判已完成的数据模型——这是运行时审查关卡，而非文档编写任务。
• 编写API 线路契约（操作 + 请求/响应 DTO）——这属于 api-spec；它会引用本模型的实体（单向下游依赖），而不会重新定义这些实体。
• 设计持久化实现（ORM/存储库/访问层）——这属于技术设计文档；系统的数据存储拓扑属于架构文档。
• 编写可执行的DDL/迁移脚本——此处要编写的是设计文档（实体、约束、迁移计划），而非代码。
• 编写其他类型的文档。

输入

阅读计划提供给你的每一份文档——即 depends_on 集合（上游文档发现流程确定的、会为本文档提供信息的文档）——并追溯本文档内容的来源。不要假设输入固定不变：此技能列出的典型上游文档只是方法指引，不是输入上限。请做到自足——根据实际收到的任何上下文编写文档；如果缺少预期的信息来源文档，请基于现有信息继续，并将缺口作为明确的假设指出，绝不可编造内容来填补。并且，在有可用研究能力时使用它（deep-research），确保文档全面详尽，而不只是填充模板。

能力上下文（如果提供）： 如果调用方注入了 capability_record（来自 capability-map.yaml product_capabilities 的记录），请在步骤 1 之前阅读它。它定义了你的范围边界：owns = 你负责涵盖的实体；refs = 你引用但不负责的实体；publishes/consumes = 你要说明的事件；entry_points/exit_points = 用户进入和离开的方式；has_ui/has_api/has_persistence = 适用的界面。提供该记录时，须将其视为硬性约束——不得超出其定义的边界。

工作流

章节结构来自与之组合使用的数据模型模板工具。以下步骤是用于填充模板的方法——将其应用于模板包含的相应章节；切勿重述模板的大纲。

步骤 1：获取结构并梳理输入

从模板工具获取数据模型模板的章节集。阅读上游的 feature-spec（功能所操作的数据），以及在存在时阅读 architecture-doc（选定的存储）。你是在完善这些内容，而不是从空白开始。通过研究能力，依据成熟实践（ER 建模、规范化理论、所选范式的惯用做法）来确定建模决策，而不是凭空发明。

如果存在 capability_record：为所有 owns 实体定义主表／集合；将 refs 实体仅作为 FK 引用处理（不重复数据）；为 publishes 事件纳入 outbox／事件条目。

步骤 2：识别范式并选择建模路径

根据 architecture-doc／选定的存储，判断每种存储所采用的范式（一个系统可以采用多种范式——分别沿各自的路径建模）。无论采用哪种范式，都要保持同等严谨；产物则有所不同：

• 关系型／SQL — 实体映射为表；提供 ER 图和逐属性规格表；明确主键／外键及引用完整性；先规范化，再有意进行反规范化。
• 文档型／NoSQL — 以访问模式优先（根据查询列表建模，而非根据实体，因为临时查询的灵活性有限）；定义集合和文档结构；选择嵌入还是引用；将一同读取的实体放在一起；采用单表设计——在条目集合中，跨实体类型复用通用的分区键＋排序键；仅在基键无法满足某种访问模式时才添加 GSI／LSI；避免使用低基数的热分区键。
• 其他范式（按其惯用做法建模，规模适度——不采用完整路径）： 图 — 实体是节点，关系是具有类型／方向的一等边（包含边属性），访问模式是遍历（例如，朋友的朋友）；不要强行使用关系型连接表。宽列 — 对宽行和追加密集型行使用分区键＋聚簇键；针对读取进行设计，可自由反规范化；基于 TTL 保留数据；不使用联接。键值 — 严格按键访问；定义值的结构和键方案。所有范式都适用的规则（实体必须有类型、每个实体有一个键、每个索引／辅助结构都必须有访问模式作为依据、说明权衡、明确生命周期）在所有范式中都成立；references/modeling-method.md 介绍各范式的惯用做法。

步骤 3：列举访问模式，然后建模

先列出系统必须通过这些数据支持的读写操作。对于关系型数据库，这些操作用于确定索引；对于 NoSQL，它们决定了模式。然后：

• 实体 — 从 feature-spec 的名词中推导实体。为每个属性标注类型；标明必填／可选；有默认值时予以注明；记录取值约束。持久化实体应与 api-spec 中的传输 DTO 区分开来——两者通常并不相同；应对存储结构建模，而非 DTO。
• 关系 — 每种关系都要注明基数（1:1／1:M／M:N）、实现关系的外键或引用、哪一侧拥有生命周期，以及引用规则（删除时：限制／级联／设为 null；对于 NoSQL，则说明嵌入还是引用，以及在没有数据库强制 FK 的情况下如何保持引用一致性）。ER 图、关系列表和实体目录必须保持一致。
• 键与约束 — 为每个实体指定一个主键（自然键还是代理键，并说明原因；对于 NoSQL，则说明分区键＋排序键及任何复用键策略）；唯一性（包括多列唯一性）；检查／域约束；跨字段不变量。明确写出，不得含糊带过。

第 4 步：说明索引的依据、权衡取舍并处理生命周期

• 索引——每个索引都对应第 3 步中的一种访问模式（WHERE/JOIN/ORDER BY 中的列，以及这些查询涉及的外键）。没有合理访问模式支撑的索引应予以删除；索引过多会增加存储开销并拖慢写入。
• 规范化/反规范化——说明采用的范式（关系型数据库：通常为 3NF/BCNF）或 NoSQL 嵌入策略，并记录每一项有意进行的反规范化，包括其服务的读取模式、接受的写入成本/数据过时权衡，以及如何保持冗余副本的一致性。核心权衡：规范化有利于提高写入效率并维护完整性；反规范化有利于提升读取性能。
• 数据生命周期——按实体说明保留/归档策略（软删除还是硬删除，以及墓碑记录对查询/唯一性的影响）；说明任何存储的派生/计算值及其事实来源，以及如何保持其最新；在历史记录重要时说明时态/审计/版本控制（有效期记录、审计/仅追加日志、缓慢变化维策略、用于乐观并发控制的行版本控制）。
• 数据隐私与分类——对敏感属性进行分类（PII / sensitive / internal / public），根据分类确定密钥保留策略和数据驻留要求，并落实数据最小化（仅存储必要数据）；在数据层保护机密信息（密码采用哈希+盐值，银行卡采用令牌化——绝不存储明文）。参见 references/modeling-method.md。
• 迁移与模式演进——说明迁移/填充数据计划（如何创建和演进模式、回填、填充数据）——只写计划，不写 DDL。将变更分类为增量式（向后兼容）或破坏性；对已有数据的存储执行破坏性变更时，采用扩展并收缩（扩展 → 回填 → 切换读取 → 收缩——绝不直接重命名/删除），并说明滚动部署下的向后/向前兼容性立场。详细要求和修订流程见 references/lifecycle-and-amend.md。

第 5 步：指出空缺，然后根据标准自查

将未知事项记录为明确的假设/待解问题——绝不凭空捏造。然后在交付前，根据 ## Output 中的质量标准核对文档。所有内容均以文本形式表达（Mermaid erDiagram、属性/约束规格表、索引/关系列表，以及 NoSQL 的围栏文档结构示例）——方法和标准不受呈现媒介限制。

第 6 步：修订已批准的模型（模式变更增量）

如果输入是针对已批准模型的变更请求（新增实体/属性、关系/基数变更、反规范化、键变更），应只编辑，不重画：仅在原位置修订受影响的实体及其关系/约束/索引。

迁移就是修订机制——它有两个数据模型特有的属性：

• 分类并迁移。 将变更分类为增量式（新增可空列/表/索引——向后兼容）或破坏性（删除/重命名/收窄列、基数变更、键变更）；将破坏性变更规划为扩展并收缩（绝不原地重写），并分析向后/向前兼容性。将已被取代的实体/属性/索引标记为弃用——绝不默默删除——并更新文档版本和变更日志。
• 向下游传递影响。 模式变更会波及下游 api-spec（其资源映射到发生变更的实体）、涉及该模式的 impl/test-plan，以及任何迁移/运行手册；应先修订上游 feature-spec（按 spec→plan→impl 的顺序）。标明影响范围——不要悄然破坏下游使用方。

完整流程见 references/lifecycle-and-amend.md。对于全新项目的首次构建，此步骤不适用。

规则

硬性规则（绝不可违反）：

• 组合内容，不要重复。 章节结构取自模板工具；此技能提供方法和标准。生成的文档中绝不要重述模板的大纲，也不要把结构当作此技能的职责。
• 每个实体都有类型和键；每种关系都标明基数和引用规则。 不得交付无类型属性、无键实体，或缺少基数／引用行为的关系。
• 每个索引都对应一种访问模式。 不得添加缺乏依据的索引，也不得遗漏必需的索引。
• 以功能规格（+ 架构文档）为依据，绝不要从空白页开始。 实体和属性应反映真实领域；将缺口作为假设指出，不要凭空编造。
• 持久化模型相对于 api-spec 是单向的。 这是存储的模式。api-spec 是引用这些实体的下游使用方，绝不是此处的输入（将其视为输入会造成循环依赖）。存储实体不是线上的 DTO。
• 能力边界（提供了 capability_record 时）。 将文档输出限制在该记录的边界内。生成边界之外的内容（例如，把 refs 实体当作自有实体来描述；或设计超出 exit_point 的流程）属于范围违规，相当于编造规格中不存在的内容。

偏好（可覆盖）：

• 按比例确定篇幅：“全面”意味着更高的目标；精简的存储层可省略不需要的章节。标准是完整性、可查询性和访问模式覆盖，而非字数。
• 除非自然键稳定且有意义，否则优先使用代理主键；无论选择哪种，都要说明理由。

易错点

• 在 NoSQL 存储中套用纯关系型思维。 如果存储是文档型／NoSQL，却默认采用表和第三范式，就会得到无法使用的模型。先识别范式（步骤 2），再针对 NoSQL 优先按访问模式建模。
• “以防万一”地添加索引。 没有访问模式支撑的索引毫无价值——它会拖慢写入并增加存储开销。将每个索引关联到步骤 3 中的查询，否则就删除它。
• 关系线未标明基数或删除规则。 ER 图如果只画出关系线，却不标明 1:M／M:N 及删除时的处理方式，就无法据此构建。每种关系都必须包含这两项。
• 建模线上 DTO，而非存储实体。 api-spec 的请求／响应结构通常不同于实际存储的数据（计算字段、未公开的内部字段、扁平化连接）。应对持久化结构建模；由 api-spec 映射到该结构。
• ER 图与表格内容不一致。 一边有而另一边没有的实体或关系会误导读者。保持 Mermaid 图、实体目录和关系列表同步。
• 输出 DDL／迁移代码。 交付物是设计（实体 + 约束 + 迁移计划），而非可执行的模式脚本。

反模式

• “api-spec 已经列出字段了，我就按它来建模。” 这颠倒了依赖关系，也混淆了线上 DTO 与存储实体。应根据功能规格建模；api-spec 引用此模型，而不是反过来。
• “我会把所有内容都规范化到 BCNF，然后就结束。” 范式只是起点，不是目标——应明确指出访问模式所需的刻意反规范化及其权衡。
• “我会重述模板的章节，让文档看起来完整。” 重复大纲不等于撰写内容——应按结构要求提供填入方法后的内容。
• “存储方案显而易见，无需论证。” 应说明存储选择和范式，并给出理由（数据形态、一致性、规模、访问模式）；下游读者无法自行推断。

输出

一份满足上述完整性与可查询性标准的数据模型文档（Markdown 文本）。这九项条件由 reviewing-data-model gate 单一来源定义——其检查清单就是这份列表，因此产出标准与评审标准不会偏离。交付前请据此进行自检：

1. 实体与属性——每个实体都有类型化属性和键（主键，或 NoSQL 的分区键 + 排序键）；建模的形态是存储形态，而不是 api-spec 的线传输 DTO；实体可追溯至 feature-spec 的领域。
2. 关系与引用完整性——每种关系都注明基数；M:N 关系通过连接实体实现（关系型/文档型；图数据库使用边）；注明 FK/引用及所属方；注明删除规则（关系型），或注明嵌入还是引用 + 无 FK 时的保持一致性策略（NoSQL/其他）。
3. 键、约束与访问模式所需的索引——每个实体都有 PK（注明自然键还是代理键）；明确列出唯一性约束、检查约束/跨字段约束；列出访问模式；每个索引都可追溯至某个访问模式（没有缺乏依据的索引，也没有遗漏必要索引）。
4. 规范化与存储范式——注明范式（关系型）或嵌入/单表策略（NoSQL/其他）；注明所选范式及其理由；每项有意的反规范化都记录其读取模式、权衡和一致性策略。
5. 数据生命周期与迁移——在需要时注明保留/归档策略及软删除还是硬删除；派生数据注明其事实来源和新鲜度；在历史记录重要时说明时态/审计策略；制定迁移与播种计划（破坏性变更采用扩展-收缩；滚动部署适用时确保向后/向前兼容）。
6. 图表 ⇄ 目录 ⇄ 表格保持同步——Mermaid erDiagram 中的每个实体/关系都出现在目录及关系/索引列表中，反之亦然；不留孤项/偏差。
7. 跨领域数据质量——在数据需要时，对敏感属性进行分类（PII/敏感），并注明保留/驻留要求；确保秘密信息在静态存储时安全保护（不存储明文凭据）；确保模型适用于目标规模（没有热点分区/未建立索引的高频查询/无界行）——在数据需要时加以说明。
8. 有据可依、诚实且一致——实体/属性反映 feature-spec（不凭空捏造或套用模板）；明确假设（输入不足 → 标记为阻塞项，而不是自行编造架构）；不得捏造；相对于 api-spec 保持单向关系（根据 feature-spec 派生，api-spec 只是下游使用方——绝不从 DTO 反向推导）；与已发布的架构保持一致（若存在）。
9. 按变更范围修订（变更请求时）——变更涉及的实体须在触及范围内满足条件 1–8；将变更归类为新增或破坏性变更，并附上迁移计划 + 兼容性分析；标明向前/向下游的影响；提升文档版本 + 更新变更日志；标记已被取代的项目。（全新项目的首次构建 → 不适用。）

**适度原则：**精简的数据存储可以合理地省去不需要的内容（单个实体、没有 M:N 关系、没有反规范化、没有时态历史记录、初稿无需迁移、没有 PII）。评判完整性与可查询性是否完备，而不是文档字数。

抽象层面的使用者：负责实现持久化并编写查询的工程师、资源映射至这些实体的下游 api-spec 作者，以及依据上述标准检查文档的 reviewing-data-model gate。

相关内容

• 内容模板工具 — 提供此技能组合使用的数据模型章节结构（即结构；此技能提供方法和标准）。
• 深度研究能力 — 依据既有实践（ER 建模、规范化理论、该范式的惯用方式）来支撑建模决策，而不是凭空创造。
• 上游的 feature-spec（以及存在时的 architecture-doc）——输入上下文；此模型设计 feature-spec 行为所需的持久化方案。
• api-spec 编写事项——下游使用方：其资源映射到此模型的实体（单向）。这是不同的制品——它是线上的契约，而非存储架构。
• reviewing-data-model ——专门的验收关卡（配套技能）：依据 ## Output 中相同的九项条件（单一来源）评判完成的模型，并输出 VERDICT: approve|revise。完成的数据模型制品应转到此处，而不是通用的 design-review（后者会像对待 technical-design 和 architecture-doc 制品一样，将其排除在外）。
• 一对 references/ 文件：references/modeling-method.md（各范式的惯用方式，以及实体／关系／键／索引／规范化的深度内容）和 references/lifecycle-and-amend.md（保留／时态／隐私、扩展与收缩迁移、修订流程，以及向前／向下的波及影响）。

渐进式披露

大量内容放在子文件夹中，仅在需要时加载：

• references/modeling-method.md —— 各范式的惯用方式（关系型／文档型／图型／宽列型／键值型），以及实体／属性、关系／参照完整性、键／约束／基于访问模式的索引、规范化／范式选择和数据隐私／分类方面的深入内容。针对特定范式建模或处理边界完整性决策时加载。
• references/lifecycle-and-amend.md —— 保留／软删除／派生数据／时态方面的深入内容、扩展与收缩迁移流程，以及修订方法（分类为新增／破坏性变更、兼容性、向前／向下的波及影响）。处理生命周期或修订／增量任务时加载。
• references/sources.md —— 方法和标准的研究出处。验证某项主张的依据时加载。

此技能不提供 scripts/ 或 assets/。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文约 500 行／5,000 个 token（软性目标——质量优先；若持续超过 700 行／7,000 个 token，则应标记）。
• 每个参考文件：超过 10k 个 token 时警告，超过 25k 时错误。参考文件总量：超过 25k 时警告，超过 50k 时错误。

更新日志

• 1.3.0（2026-06-21）— capability_record 上下文注入：在 Step 1 中使用可选的调用方注入 capability_record（依据 owns／refs／publishes／consumes 确定范围边界）；新增 capability_boundary 规则；正文篇幅限制调整为目标值。未注入记录时可平稳回退。
• 1.2.0（2026-06-15）— 生产级重构：新增迭代／修订方法（Step 6——分类为新增／破坏性变更 + 扩展与收缩迁移 + 向后／向前兼容 + 向前／向下的波及影响）；深入补充生命周期中的架构演进／迁移、时态／审计／SCD，以及数据隐私／分类；扩展范式覆盖范围（图型／宽列型／键值型惯用方式 + NoSQL 单表深入内容）；重构 ## Output，使其包含与配套的 reviewing-data-model 一一对应且采用单一来源的九项条件（新增跨领域数据质量 + 限定增量范围的修订）；完成的制品转到 reviewing-data-model（而非通用的 design-review）；将深入内容拆分到 references/modeling-method.md + references/lifecycle-and-amend.md。方法 + 输入契约 + 介质保持不变（仅新增内容）。
• 1.1.0（2026-06-04）— 首个经过评审的版本。