reviewing-data-model

reviewing-data-model — SKILL.md

变体： standard · 使用时机： 将完成的数据模型文档作为验收门槛进行评审——检查工程师能否据此构建架构并编写正确的查询，然后给出 VERDICT: approve|revise，并列出可执行的发现。适用于全新设计，或修订（限定于变更范围）。

概述

此技能是数据模型编写/评审配对流程中的评审部分。评审者加载已完成的数据模型文档——即工程师据此实现架构、所有查询数据的人都会阅读的持久化/领域模型——并围绕一个问题评判该文档：工程师能否据此创建架构并编写正确的查询，模型的完整性规则和权衡是否明确？它会应用固定的9 项完整性与可查询性检查清单——与数据模型作者所遵循的标准相同（authoring-data-model 的 ## Output），以免编写标准和评审标准出现偏差——然后给出一个可由机器解析的裁定，以及作者可在一轮修改中采取行动的发现。这是一个验收门槛——它不会编写、修复或重写模型；它只进行评判并返回发现，由编写者进行修订。

评审标准与作者的标准统一定义。作者的技术手段——ER 表示法（Chen／乌鸦脚／Mermaid）、概念／逻辑／物理层级框架、范式推导流程——都是评审者根据结果进行评判的辅助工具（每个实体是否都声明了类型和键？每个关系是否都标明了基数和引用规则？每个索引是否都能追溯到一种访问模式？），绝不能将其列为强制条件。但请注意界限：由访问模式支撑的索引规范（条件 3）、引用完整性（条件 2），以及规范化与范式推理（条件 4）都是数据模型中真正不可或缺的条件——这就是持久化设计，因此不要将其低估为“实现细节”。作为辅助工具的是技术手段（命名的表示法／层级／推导方法），而不是结果（有类型的实体、理由充分的索引、明确说明的权衡）。

关注范式（不可或缺）。模型可以采用关系型、文档／NoSQL、图、宽列或键值范式。应按各自范式进行评判：NoSQL／图／宽列模型确实可能没有范式，也没有 FK（而是使用嵌入与引用／边／分区键和聚簇键）。要求非关系模型遵循关系型范式，是典型的关系型思维导致的错误 revise 裁定——不要这样做。

何时启用

• 完成的数据模型文档需要在工程师构建架构前获得接受或修订的裁定。
• 你是某个编写者刚刚完成的数据模型的独立评审者／把关人。
• 在先前得到 revise 裁定后，重新评审修订后的数据模型。
• 将修订（已批准的模型 + 变更请求）作为限定于变更范围的评审进行审查（条件 9）。

不要在以下情况启用：

• 编写或修复数据模型 → 使用 authoring-data-model。此技能绝不编写模型。
• 评审 api-spec（线级契约）或 feature-spec（功能的行为）→ 这些是各自独立的文档，有各自的评审门槛。api-spec 是引用此模型实体的下游使用方——它绝不是此处的输入。
• 评审持久化实现（ORM／repository）或可执行的 DDL／迁移代码 → 此门槛评审的是设计文档，而不是代码。
• 评审通用／临时的工程设计文档、RFC、ADR、规范或计划 → 使用 design-review。此门槛专用于文档库中的数据模型制品——其权威识别方式是 frontmatter 中的 template: data-model；仅当缺少 frontmatter 时，才将 # Data Model 标题作为备用识别信号。
• 检查模板／章节是否符合规范 → 这是模板方面的工作。此技能评判的是质量是否达到标准，而不是是否包含每个标题。

工作流

步骤 1：以全新、独立的视角通读整个模型

从头到尾阅读数据模型文档，仿佛是第一次接触它。你的立场是为下一步把关（由工程师构建架构并查询）：只有当某项发现能表明架构无法按设计构建或查询时，它才有分量。若有上游的功能规范（以及架构文档中对存储方案的选择），请随手参阅——cond-1/cond-8 会根据业务领域检查模型。先识别范式（关系型／文档型／图／宽列／键值型，也可能是多种范式并用），再按各自的惯例评判。输入就是文档本身——访问模式列表就在文档中（模板章节）；不需要单独的配套材料。这是一次修订吗？ 如果收到的是针对现有模型的变更请求／差异，请走限定于差异的路径（启用 cond-9；范围涵盖已更改的实体及其迁移和连带影响）。首次从零构建时，没有变更请求——cond-9 不适用。

步骤 2：执行完整性与可查询性检查清单——逐项评判条件

对于每项条件，判定为通过或存在缺口。只有存在真实且明确指出的缺陷时，条件才算未通过——“我会采用不同的建模方式”不构成缺口。这些条件是唯一的评判标准；不要另加私有标准。

能力边界检查项（如下）仅在 capability_record 已注入作者调用且可作为审查上下文时适用。若不存在，则视为不适用——未定义边界时，不要因文档缺少能力边界标记而扣分。

1. 实体与属性。 每个实体都有类型化属性和键（主键，或 NoSQL 中的分区键 + 排序键）；建模的形状是存储形状，而不是 api-spec 的线缆 DTO；实体可追溯至 feature-spec 的领域。缺口：属性未声明类型、实体没有键、DTO 被建模为已持久化数据（存储了计算得出/扁平化的字段），或实体不服务于任何领域需求。（不可折叠的基线——无论规模大小，每个实体都必须有类型和键。）
2. 关系与引用完整性。 每个关系都说明基数；M:N 关系通过联结实体实现（关系型/文档型；图数据库使用边）；注明 FK/引用和所属方；说明删除规则（关系型），或说明嵌入还是引用 + 无 FK 时的保持一致性策略（NoSQL/其他）。缺口：关系没有基数、M:N 关系只有一条裸线（没有联结实体）、缺少删除规则（关系型），或存在无界嵌入 / 无 FK 的引用却没有一致性策略（NoSQL）。（可折叠：只有一个实体的存储没有关系。存在关系时不可折叠：必须说明基数 + 引用规则/策略。）
3. 键、约束与由访问模式证明合理的索引。 每个实体都有 PK（说明采用自然键还是代理键）；明确唯一性 + 检查/跨字段约束；列出所有访问模式；每个索引都能追溯至某个访问模式（没有缺乏依据的索引，也没有遗漏必要索引）。缺口：索引没有对应的查询依据、频繁查询没有受支持的索引、未说明键的选择，或业务唯一性规则未建模。（标志性条件。可折叠：小型存储可能不需要二级索引，但仍须列出访问模式，且任何已有索引都必须有依据。）
4. 规范化与存储范式。 说明范式（关系型）或嵌入/单表策略（NoSQL/其他）；说明所选范式及理由；每项有意进行的反规范化都记录其读取模式 + 权衡 + 一致性策略。缺口：未解释的冗余导致更新异常、反规范化副本没有一致性策略、未说明/未证明合理的存储选择，或模型与范式不匹配。（关注范式适配：NoSQL/图/宽列模型没有范式，应评估其嵌入/边/分区策略；绝不可因其“未规范化”而要求修改。）
5. 数据生命周期与迁移。 在需要时说明保留/归档 + 软删除还是硬删除；派生数据注明其事实来源 + 新鲜度；在需要保留历史时说明时间维度/审计；制定迁移与播种计划（破坏性变更采用扩展-收缩；适用滚动部署时确保向后/向前兼容）。缺口：实体会无限增长却没有保留策略、存储的聚合数据没有新鲜度机制、暗示对已填充数据表进行原地重命名/删除，或没有从空状态到可运行状态的计划。（可折叠：精简/初稿模型的生命周期很简单，轻量处理即可。）
6. 图示 ⇄ 目录 ⇄ 表格保持同步。 Mermaid erDiagram 中的每个实体/关系都出现在实体目录 + 关系/索引列表中，反之亦然；不得存在孤立项/不一致。缺口：某个元素出现在一种呈现形式中，却缺失于另一种形式。（可折叠：单实体模型的图示很简单。）
7. 跨领域数据质量。 对敏感属性进行分类（PII/敏感），并在数据需要时说明保留/驻留要求；确保静态数据安全以保护密钥（不得使用明文凭据）；确保模型适用于目标规模（不得存在热点分区 / 未建索引的热点查询 / 无界行）——在数据需要时予以说明。缺口：密钥使用明文存储；领域显然涉及个人数据，却未对 PII 进行分类/设置保留策略；或设计在所述规模下无法运作。（可折叠：没有 PII → 无需分类；数据有界 → 规模处理可轻量化。）
8. 有依据、诚实且一致。 实体/属性应反映 feature-spec（不得凭空编造/使用样板内容）；明确说明假设（输入过少 → 标记为阻塞项，而不是编造架构）；不得捏造；与 api-spec 保持单向关系（源自 feature-spec，api-spec 只是下游使用方——不得从 DTO 反向推导）；与已发布的架构一致（如存在已发布架构，关于实际存储内容的声明必须通过真实架构/迁移验证，注明 file:line，无法确认时标记为未经验证）。缺口：编造实体/约束/索引、对 api-spec 进行反向推导，或文档记载的表/列/索引与真实架构矛盾。（不可折叠的基线——任何规模下都不得捏造，且必须保持单向关系。全新项目条款：全新/提议中的/虚构模型没有已发布架构可供验证 → 一致性检查为不适用，绝不可错误地要求修改。）
9. （仅修订）变更范围明确、分类清晰、影响无遗漏且已版本化。 针对现有模型审查变更时：被变更的实体在涉及的内容上满足条件 1–8；将变更分类为新增或破坏性变更，并附迁移计划（破坏性变更采用扩展-收缩）+ 向后/向前兼容性分析；标明向前/向下游的影响（映射到已变更实体的 api-spec 资源、impl/test-plan/runbook）；提升文档版本 + 提供变更日志；标记被取代的实体/属性/索引，不得悄然删除。缺口：变更范围不明确、将破坏性变更误分类为新增变更、原地重命名/删除却没有扩展-收缩计划、未标明影响，或悄然删除。（可折叠：全新项目的首次构建中，此条件不适用——不要对未变更的模型进行完整重新审查，也不要要求初稿提供变更日志。）
10. 能力边界（无 capability_record 时不适用）： 所有 owns 实体都有主表／集合；所有 refs 实体仅供引用（只有外键，不重复存储数据）；publishes 事件有 outbox 或事件条目。

合乎比例。“可构建 + 可查询”应与存储规模相称。精简的存储可以合理地省去不需要的内容：一个实体 → 无关系；没有 M:N → 无联结表；没有反规范化 → 无一致性策略；无历史记录要求 → 无时态模型；初稿 → 无迁移／变更日志；无 PII → 无分类。应评判完整性与可查询性决策是否完备，而非字数或模板章节是否齐全。只要满足所有适用条件，小而完整的模型就可以通过。不要仅因内容简短就认定存在缺陷。

第 3 步：判定结果

• approve — 所有适用条件均通过。工程师无需询问作者，就能据此构建架构并编写正确的查询；完整性规则和权衡取舍均已明确。即使你能想到风格上的改进，也应批准；标准是可构建性 + 可查询性，而非完美无缺。
• revise — 至少有一项条件存在明确且具体的缺陷，导致无法构建或查询（例如，属性未指定类型、关系未说明删除时的处理规则、索引缺失或缺乏依据、反规范化副本没有一致性策略、DTO 反转、原地实施破坏性迁移、amend 未限定范围等）。

不要为了体现投入或索要锦上添花的改进而要求修改。条件要么满足，要么不满足。

第 4 步：输出结果和可执行的发现

将结果作为单独一行输出——只写字面文本 VERDICT: approve 或 VERDICT: revise，独占一行，不要添加外围代码围栏、引号或其他文字（此处的围栏仅用于示例）：

VERDICT: approve

然后在后续行中列出发现。若结果为 revise，每项发现都必须可执行——指出未满足的条件、具体位置，以及修复方法——以便作者一次性解决。若结果为 approve，可以选择添加非阻塞说明。

好的发现会指出缺陷和修复方法：

revise — 关系与引用完整性（条件 2），§3：Order→Customer 关系显示了连线，却未说明删除时的处理规则。修复方法：注明 ON DELETE RESTRICT（存在订单时无法删除客户），避免让工程师自行臆定完整性语义。

不好的发现含糊且无法执行：

关系部分可以写得更清楚。（具体是哪种关系？为何不符合标准？如何修复？）

规则

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

• 只输出一行判定：VERDICT: approve 或 VERDICT: revise——该字面标记单独占一行，除此之外不得包含任何内容。下游工具会解析它。
• 评审，不代写。 给出问题；不要重写、修正或补全模型。由编写者负责修改。
• 统一评审标准。 按第 2 步中的十项条件评审——这与编写者（authoring-data-model 的 ## Output）所遵循的标准相同。不要自创额外条件，也不要采用更严格的个人标准。
• 辅助方法按结果评判，绝不可强求。 ER 表示法、概念／逻辑／物理层级、范式推导流程都是编写者的技巧——评判实体是否经过类型定义、关系是否包含引用规则、索引是否有依据，而绝不要说“你没有使用乌鸦脚表示法／绘制概念模型／展示 FD 推导”。（访问模式索引／引用完整性／规范化的结果是 cond-2/3/4 中的真实条件，只有技巧才是辅助方法。）
• 理解范式差异——不要带着关系型数据库的惯性评审。 绝不要因为 NoSQL／图数据库／宽列数据库模型缺少范式或外键就要求修改；应评判其嵌入与引用／边／分区策略。这是本关卡重点防范的关键偏差。
• 不要错误要求修改。 模型满足所有适用条件时就应予以批准，即使它对于小型存储来说很精简。只有存在明确指出的实际缺口时才要求修改。精简的存储可以合理地省略关系、反规范化、时间历史记录、迁移和变更日志。
• 不要错误批准。 不要为了表示赞同而放过真实缺口。阻断性缺口必须判为 revise。
• 每个索引都必须对应一种访问模式（cond. 3）。 缺乏依据的索引是实际缺口（会放大写入开销并占用存储），不是风格问题；热点查询缺少索引也是实际缺口。
• 依据文档提供的上游材料进行评审。 根据模型的 depends_on 集合及其引用的文档进行评估。未产出／未提交的上游材料（例如缺失的功能规格）绝不可成为要求修改的理由。模型忽略了已产出且理应追溯到的上游材料则可以作为问题指出。
• 增量修改只评审变更部分。 收到针对现有模型的修改时，评审变更内容、对应的迁移及其影响范围（cond-9）——不要重新全面评审未变更的模型，也不要要求全新初稿提供变更日志。
• 全新模型的一致性检查不适用，不构成缺口。 没有已发布的架构可供核验（例如新建／拟议／虚构模型）时，将 cond-8 的一致性检查标记为 N/A——没有可供核验的代码本身绝不是阻断理由。
• 每项修改意见都必须可执行——指出未满足的条件、具体位置和明确的修复方法。

偏好（可酌情调整）：

• 按严重程度排列问题——先列阻断性缺口，再列轻微问题。
• 在每项问题中标明条件编号／名称，方便编写者对应标准。
• 批准意见应简短，并明确说明其不构成阻断。

注意事项

• 为了完整性而非可构建性批准。 每个部分都可能齐全，但架构仍然无法构建（属性没有类型、关系没有删除时的处理规则、没有正当理由的索引会拖慢写入）。判断的是架构能否构建并查询，而不是模板是否填满。
• 关系型思维惯性。 要求文档、图或宽列模型满足 3NF 或包含外键，是最常见的偏差——NoSQL 模型应遵循嵌入与引用的取舍，并优先考虑访问模式；图模型应包含边；宽列模型应有分区键和聚簇键。应按各自范式判断。
• 放过缺乏依据的索引。 列出索引的模型看起来很全面，但没有对应访问模式的索引只是累赘（条件 3）；每个索引都应关联到一条查询，否则就是缺口。
• DTO 与实体的依赖倒置。 根据 api-spec 的响应结构反向推导模型（将计算得出或扁平化的字段当作持久化字段存储），颠倒了依赖关系，并混淆了线路 DTO 与存储实体（条件 1/8）。
• 隐性的过时问题。 存储的派生值（缓存计数、反规范化副本）若未说明事实来源和新鲜度机制，就会埋下潜在错误（条件 5）。
• 臆造条件（标准漂移）。 添加评审标准并未要求的私有要求（“必须使用乌鸦脚表示法 / 规范化到 BCNF / 绘制概念 ERD”），会让评审标准偏离产出标准。只根据结果评判技术。
• 系统性过度标记（误判为需修改）。 受邀查找问题的评审者容易过度纠正。只有存在明确指出且实际存在的缺陷时，才能判定条件未满足；仅仅是你会做出不同决定，不构成缺口。
• 混淆 data model 与 api-spec 或 design-review。 数据模型的评判标准是架构是否可构建并可查询——这不同于 api-spec（供下游使用者使用的线路契约），也不同于 design-review（用于把关通用设计文档/RFC/ADR/规范/计划）。这一关是 doc-library 数据模型产物专属的评审关卡。
• 判定词漂移。 “Approved”、“LGTM”、“needs work”，或埋在段落中间的判定都无法解析。必须单独一行输出字面内容 VERDICT: approve|revise。

反模式

• 走过场批准。 草草浏览后直接批准，以免进入修改循环——放过缺乏依据的索引或缺失的删除处理规则，可能导致查询变慢或数据完整性错误。
• 吹毛求疵地要求修改。 把命名、表示法或锦上添花的内容当作缺口并据此阻止通过。只有真正妨碍可构建性或可查询性的问题才应要求修改。
• 因关系型思维惯性要求修改。 因 NoSQL/图/宽列模型未规范化或缺少外键而要求修改——这是数据模型评审中最常见的特定偏差。
• 悄悄重写。 “直接修好模型更省事”——在评审过程中编写内容，会破坏产出与评判的分离。
• 臆造条件。 添加评审标准并未要求的要求（指定表示法/范式/推导方式）——只根据结果评判。
• 对 amend 进行全面重评。 因小幅变更而重新评判整个未变更的模型——应按比例评审变更部分及其迁移和连带影响（条件 9）。
• 模棱两可的判定。 “基本批准，但是……”或给出两行判定。只能有一个决定，且只能有一个判定词。

输出

针对一份数据模型文档给出单一评审结果：

• 一行判定——单独一行逐字写出 VERDICT: approve 或 VERDICT: revise。
• 问题项——若为 revise，每个阻塞性缺口对应一条可执行的问题项（未满足的条件 + 位置 + 具体修复方式）；若为 approve，可选提供非阻塞性备注。

抽象使用者是负责协调产出→评审循环的任何对象：approve 表示接受该模型用于架构实现；revise 表示将问题项返回给产出者，进行范围受限的修改。媒介： 当前评审对象是文本 Markdown 格式的数据模型；评审标准与媒介无关。

相关

• authoring-data-model — 这对技能中的产出环节；它会按照本技能评审所依据的九项条件标准（## Output）编写模型。将两者配对可确保标准只有一个来源，避免产出与评审的标准逐渐偏离。
• api-spec（若存在）——下游使用方，其资源映射到此模型的实体（一种单向关系）；cond-1/cond-8 会检查模型是否为存储形态，而非 DTO，也不是从 api-spec 反向推导得出。
• 上游 feature-spec（以及架构文档中的存储方案选择）——此模型所持久化的领域；cond-1/cond-8 会追溯至此（仅在提供这些材料时进行评审）。
• design-review 技能——用于把关通用工程设计文档、RFC、ADR、规格说明和计划（它会对照代码库核实声明）。本技能专门评审文档库中的 data-model 工件；design-review 不负责此工件。
• data-model template / content-template 工具——负责章节结构；本技能评判的是是否达到质量标准，而非是否符合结构。

渐进式披露

• references/data-model-quality-bar.md — 展开说明九项检查条件，包含每项条件的通过/缺口信号及已完成的发现示例（带类型的键检查、基数 + 参照规则检查、访问模式所支撑的索引测试、范式感知的规范化检查、生命周期/迁移信号、图表同步检查、跨领域隐私/安全/规模信号、有依据/单向/一致性信号，以及限定于差异范围的修订信号）。当边界条件需要更明确地判定通过或存在缺口时加载。
• references/sources.md — 评审方法的研究依据（ER/规范化理论、NoSQL 访问模式设计、索引依据、扩展与收缩式迁移、模式演进兼容性、数据分类）。

正文篇幅预算

• description ≤ 1,024 个字符（agentskills.io 上限）；在列表中，description 与 when_to_use 合计超过 1,536 个字符时会被截断。
• 正文约 500 行 / 5,000 个 token（软性目标——质量优先；若持续超过 700 行 / 7,000 个 token，则标记提醒）——每轮都会保留在上下文中。
• 每个参考文件：超过 10k 个 token 时提醒，超过 25k 时报错。参考文件总计：超过 25k 个 token 时提醒，超过 50k 时报错。

更新日志

• 1.0.0（2026-06-15）— 首个版本。通过改编规范的同级技能 reviewing-technical-design，全新打造的评审技能；九项条件的完整性 + 可查询性标准与 authoring-data-model 的 ## Output 逐项保持单一来源；具备范式感知能力（不固守关系型思维）；继承 VERDICT: approve|revise 约定、依据给定上游材料进行评判、与已发布模式保持一致的对照代码核验规范 + 绿地开发条款，以及比例原则 / 避免错误判定需修订 / 不臆造条件等反模式。