Back to Details

review-schema

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review a Prepr schema

审查 Prepr schema

Review the schema of a live Prepr environment, or the schema files in 
prepr/schema/
, and deliver concrete, prioritized fixes. A review has two layers: design (is it a good schema) and, where content exists, actual use (what editors did with it, which contradicts the design more often than anyone expects).
This skill is read-only. It never changes the schema; fixes go through create-schema, which plans them and waits for a yes.
Run the check first. Name what you review, the environment or the files, in the first line of your report.
  • Live environment: needs MCP. If it is not connected, offer connect-prepr, or review the files instead if the project has them.
  • Schema files: read every file in 
    prepr/schema/
    (format: schema-files.md). Use-of-content findings need MCP; without it, say they were skipped.
  • Both available: compare them as schema-route.md describes and report every drift between environment and files as a finding of its own, with which side the user should keep.
审查实时 Prepr 环境的 schema，或 
prepr/schema/
下的 schema 文件，并给出具体且有优先级的修复建议。审查分为两层：设计（它是不是一个好的 schema），以及在已有内容时审查实际使用情况（编辑实际如何使用它，其与设计之间的矛盾往往超出预期）。
此 skill 是只读的。它绝不会更改 schema；修复操作需通过 create-schema 完成，后者会制定计划并等待用户确认。
首先运行检查步骤。在报告的第一行说明审查对象，即相关环境或文件。
  • **实时环境：**需要 MCP。如果尚未连接，可以提供 connect-prepr；如果项目中存在 schema 文件，也可以改为审查这些文件。
  • **Schema 文件：**读取 
    prepr/schema/
    中的每个文件（格式参见 schema-files.md）。关于内容实际使用情况的发现需要 MCP；没有 MCP 时，应说明已跳过这些发现。
  • **两者都可用：**按照 schema-route.md 所述进行比较，并将环境与文件之间的每一处偏差作为独立发现报告，同时说明应保留哪一侧。

Step 1: Collect the whole schema

第 1 步：收集完整的 schema

Page through 
list_schema
to the last page, then call 
get_schema_entity
for every model and component, and for the enums they use. Reference and stack findings are meaningless from a partial view.
If the environment has more than 40 entities, say how many there are and ask whether to review everything or a named area (for example "the page builder" or "the blog").
逐页调用 
list_schema
直至最后一页，然后为每个 Model 和 Component，以及它们使用的 Enum 调用 
get_schema_entity
。如果视图不完整，引用关系和栈结构方面的发现都毫无意义。
如果环境中有超过 40 个实体，请说明实体总数，并询问用户是审查全部内容，还是审查某个指定领域，例如“page builder”或“博客”。

Step 2: Assess the design

第 2 步：评估设计

Judge against https://docs.prepr.io/content-modeling/best-practices (the authority) with schema-design-principles.md as a worked example of the patterns in practice. Deviating from the example is never a finding by itself; only deviations from documented best practices or from the principles' reasoning are. Check in particular:
  1. Model/Component/Enum choices. Standalone lifecycle or cross-page reuse → Model; embedded structure → Component; fixed choice list → Enum, never free text.
  2. Composition fits the content. Judge whether each model's shape matches what it holds, not whether it matches one house pattern. A flexible stack suits pages whose layout editors vary; a fixed field list suits strongly-structured content (pricing, profiles, product data); rich text with embeddable components suits article bodies. None of these is the default. Flag a real mismatch (a stack of one permitted type, a fixed field list on a page editors clearly need to compose freely, a section vocabulary grown past about 6 near-identical types) and do not flag a flat block stack for lacking a container level, or a field-list model for not being a page builder.
  3. Duplication. Near-identical components (HeroV2, repeated label/headline/text groups) → shared atom or variant enum. Repeated option lists → shared enum.
  4. References and taxonomy. Shared entities duplicated instead of referenced; fields that listing pages filter on but that are not filterable; reference fields allowing hundreds of items where the front end renders one. For taxonomy, a content item per term is the house default; flag any Tags field used for something category-shaped (anything that may need a term page, a description or image, hierarchy, or a curated vocabulary), since converting tags to a Model later means migrating every item that used them. A term Model with nothing but a title is not a finding.
  5. Editor experience. Missing internal title on models editors must find; missing field descriptions; forms without dividers past about 8 fields; variant-specific fields not hidden behind conditional display; presentation enums without a default; guidance crammed into a field's label instead of its description; models with no title field, or more than one. Also check translation intent: human-language text should be marked for translation, and URLs, names and identifiers should not.
  6. AI context. Models without an 
    ai_goal
    , text fields without an 
    ai_purpose
    , and descriptions too weak to guide anyone ("Summary of the article."). Judge them against ai-context.md and propose concrete replacements. Also note whether the environment AI context is set, as described there.
  7. Naming. Presentation-based field names (
    small_text_left
    ), inconsistent vocabulary across components (headline vs title vs heading for the same role), casing that differs from the rest of the environment.
  8. Future pain. Personalization and A/B testing not enabled on section stacks, missing SEO component on routable models, missing slug templates on page models, Float used for money.
依据 https://docs.prepr.io/content-modeling/best-practices（权威依据），并参考 schema-design-principles.md 作为这些模式在实际应用中的示例。仅偏离示例本身绝不构成问题；只有偏离已记录的最佳实践或原则背后的推理时才构成问题。特别需要检查：
  1. **Model、Component 和 Enum 的选择。**独立生命周期或跨页面复用 → Model；嵌入式结构 → Component；固定选项列表 → Enum，绝不能使用自由文本。
  2. **组合方式是否适合内容。**判断每个 Model 的形态是否与其承载的内容相匹配，而不是是否符合某一种内部惯例。灵活的栈适合布局差异很大的页面；固定字段列表适合高度结构化的内容（定价、资料、产品数据）；可嵌入 Component 的富文本适合文章正文。任何一种都不是默认选择。只有出现真正的不匹配时才应标记（只允许一种类型的栈、页面编辑明显需要自由组合却使用固定字段列表、section 类型词汇表膨胀到约 6 个以上近乎相同的类型），不要因为扁平 block 栈缺少容器层级而标记它，也不要因为字段列表式 Model 不是 page builder 而标记它。
  3. **重复。**近乎相同的 Component（HeroV2、重复的 label/headline/text 组）→ 共享 atom 或 variant Enum。重复的选项列表 → 共享 Enum。
  4. **引用和 taxonomy。**本应共享的实体被重复创建，而不是通过引用关联；列表页需要筛选、字段却不可筛选；引用字段允许选择数百项，而前端只渲染其中一项。对于 taxonomy，每个术语对应一个内容项是默认做法；如果某个 Tags 字段被用于具有分类属性的内容（可能需要术语页面、描述或图片、层级结构或经过策划的词汇表），就应标记出来，因为以后将 tags 转为 Model 意味着迁移每一个使用过它们的条目。term Model 只有 title 字段并不构成问题。
  5. **编辑体验。**编辑需要查找的 Model 缺少内部 title；字段缺少描述；字段超过约 8 个后表单仍无分隔；variant 专属字段没有通过条件显示隐藏；展示用 Enum 没有默认值；指导信息被塞进字段 label 而不是 description；Model 没有 title 字段，或有多个 title 字段。还要检查翻译意图：自然语言文本应标记为可翻译，而 URL、名称和标识符不应翻译。
  6. **AI context。**没有 
    ai_goal
    的 Model、没有 
    ai_purpose
    的文本字段，以及弱到无法为任何人提供指导的描述（“文章摘要。”）。依据 ai-context.md 进行判断，并提出具体的替换内容。还要按照该文档所述检查环境 AI context 是否已设置。
  7. **命名。**基于展示形式的字段命名（
    small_text_left
    ）、不同 Component 之间词汇不一致（同一角色分别称 headline、title 或 heading）、大小写风格与环境其余部分不同。
  8. **未来痛点。**section 栈未启用个性化和 A/B 测试；可路由 Model 缺少 SEO Component；页面 Model 缺少 slug 模板；使用 Float 表示金额。

Step 3: Assess against actual use

第 3 步：根据实际使用情况进行评估

Only when content exists. Before launch there is nothing to measure, so skip this step and say so. Work read-only with 
query_items
(conditions under 
filters
) and 
get_item
:
  • Count items per model.
  • For every model with items, open up to 3 items, the most recently updated first, and note which section and block types they use, which optional fields are empty, and which enum values appear.
  • Don't report "actual use" findings from counts alone. If you could not sample, say which models you skipped.
The schema was designed against expectations. Content records what actually happened, and the gap is a class of finding no pre-launch review can produce:
  • A type nobody uses. A section or block type present in no item, or a personalization variant never filled in. Either the vocabulary is larger than the site needs or editors do not know the type exists; ask which before recommending removal.
  • A field nobody fills. An optional field empty on almost every item is unclear, unnecessary, or in the wrong place in the form. An enum value never chosen is the same finding one level down.
  • A count that contradicts the design. A model with three items where the plan assumed hundreds is over-modelled. A stack grown to fifty entries wants a filtered listing and filterable fields, not a longer stack.
  • Duplication that names a missing model. The same quote, author, or logo typed into many items is a Component where a Model belonged.
  • Fields carrying what the model does not offer. Editors pasting HTML into a text field, or using a headline field for a label, have marked the shape they needed and did not get.
Because content exists, almost everything structural here is a migration rather than a free change. Say what the migration would cost next to each recommendation, and expect "leave it, and stop offering the unused type to editors" to be the right answer more often than it is before launch.
仅在已有内容时执行。上线前没有可测量的数据，因此跳过此步骤并明确说明。只使用 
query_items
（条件放在 
filters
下）和 
get_item
进行只读检查：
  • 统计每个 Model 的条目数。
  • 对每个包含条目的 Model，打开最多 3 个条目，优先选择最近更新的条目，并记录所使用的 section 和 block 类型、哪些可选字段为空，以及出现了哪些 enum 值。
  • 不要仅根据计数报告“实际使用情况”方面的发现。如果无法抽样，请说明跳过了哪些 Model。
Schema 是依据预期设计的。内容记录实际发生的事情，而两者之间的差距是一类上线前审查无法发现的问题：
  • **无人使用的类型。**某个 section 或 block 类型没有出现在任何条目中，或者某个个性化变体从未被填写。这可能意味着类型词汇表超出了网站需求，也可能意味着编辑不知道该类型的存在；建议移除之前，应先询问属于哪种情况。
  • **无人填写的字段。**几乎每个条目中都为空的可选字段可能含义不清、没有必要，或放错了表单位置。从未被选择的 enum 值也是同一层级的问题。
  • **数量与设计相矛盾。**计划预期会有数百个条目，Model 中却只有三个，说明该 Model 过度建模。栈增长到 50 个条目时，需要的是带筛选的列表和可筛选字段，而不是继续加长栈。
  • **重复现象揭示了缺失的 Model。**同一段引文、作者或 logo 被录入许多条目，说明本应是 Model 的内容被做成了 Component。
  • **字段承载了 Model 未提供的能力。**编辑将 HTML 粘贴到文本字段，或使用 headline 字段充当 label，说明他们已经标明了所需的形态，但 schema 没有提供这种能力。
因为已有内容，几乎所有结构性调整都属于迁移，而不是可以直接进行的更改。每条建议旁都要说明迁移成本，并且要预期“保留它，但不再向编辑提供未使用的类型”会比上线前更常是正确答案。

Step 4: Report

第 4 步：报告

Lead with a verdict, then group findings by what acting on them costs. Within a group, order by impact, and put a finding that covers others above the ones it covers.
markdown
undefined
先给出结论，然后按照处理这些问题需要付出什么成本对发现进行分组。在组内按影响程度排序，并将能够覆盖其他问题的发现放在其所覆盖问题之上。
markdown
undefined

Schema review: <environment>

Schema 审查：<environment>

Verdict. One sentence on the state of the model, plus the single change you would make if there were time for only one.
结论。 用一句话说明当前模型的状态，并指出如果只能做一项改动，你会做哪一项。

Fix before content exists

在内容创建前修复

Free today, a content migration later. When content already exists this group is titled Needs a content migration instead, and each finding states what the migration involves.
  • Must · <category> — <Model>.<field>: <problem>. Fix: <concrete change>.
现在可以免费完成，但之后需要内容迁移。如果已经有内容，这一组的标题应改为 需要内容迁移，并且每项发现都要说明迁移涉及哪些内容。
  • 必须 · <类别> — <Model>.<field>：<问题>。修复：<具体改动>。

Fix any time

随时可修复

Costs the same next quarter as it does today.
  • Should · <category> — <Model>: <problem>. Fix: <concrete change>.
下个季度的成本与现在相同。
  • 应该 · <类别> — <Model>：<问题>。修复：<具体改动>。

What's good

做得好的地方

  • <1-3 things done well, so the next person does not "fix" them>

Severity has three levels:

- **Must**: breaks silently in production, or blocks editors
- **Should**: costs editors or developers on every use
- **Consider**: a real improvement whose absence is defensible

Every finding carries a category (Architecture, Composition, Naming, Editor
form, Field types, Posture, from the sections of
[schema-design-principles.md](references/schema-design-principles.md)), the
entity and field it applies to, and a fix concrete enough to apply without a
follow-up question.

Rules that keep the report useful:

- **Which group a finding belongs in depends on whether content exists.**
  Check with a content query. On an empty environment nothing needs a content
  migration yet and every structural fix is free; say so, because it is the
  best news a review can carry.
- **What belongs in "Fix before content exists"** is the list in
  [Decisions that are expensive to reverse](references/schema-design-principles.md#decisions-that-are-expensive-to-reverse).
- **Bundle mass findings.** "19 fields have no description" is one finding,
  not nineteen.
- **Weigh editor experience as heavily as API cleanliness.** A valid model
  with 40 flat fields is still a bad schema.
  • <1-3 个做得好的方面，以免下一个人把它们“修坏”>

严重程度分为三级：

- **必须**：会在生产环境中静默出错，或阻碍编辑操作
- **应该**：每次使用都会给编辑或开发者带来成本
- **考虑**：属于真实改进，但缺少它也有合理理由

每项发现都应包含一个类别（Architecture、Composition、Naming、Editor form、Field types、Posture，源自 [schema-design-principles.md](references/schema-design-principles.md) 的各节）、适用的实体和字段，以及无需追问即可执行的修复方案。

让报告保持实用价值的规则：

- **问题属于哪一组取决于是否已有内容。**通过内容查询进行确认。如果环境为空，目前没有任何内容需要迁移，所有结构性修复都是免费的；要明确说明这一点，因为这是审查能带来的最好消息。
- **哪些内容应归入“在内容创建前修复”**由 [Decisions that are expensive to reverse](references/schema-design-principles.md#decisions-that-are-expensive-to-reverse) 中的列表决定。
- **合并大量同类发现。**“19 个字段没有描述”应算作一项发现，而不是 19 项。
- **编辑体验与 API 整洁性同等重要。**一个包含 40 个扁平字段的合法 Model，仍然是糟糕的 schema。

Step 5: Offer fixes

第 5 步：提供修复方案

Ask which findings to fix. Hand the chosen ones to create-schema, which plans them, waits for a yes, and applies them. Never change the schema from this skill.
询问用户要修复哪些发现。将选中的发现交给 create-schema，后者会制定计划、等待用户确认，然后应用更改。绝不要从此 skill 直接更改 schema。