review-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Data Fitness Review

数据适配度审查

Analyze the codebase (or specified files/modules) for data fitness. Identify gaps in schema design, migration safety, data integrity, query correctness, data modeling, and pipeline quality using evidence from the code, schema definitions, migration files, and configuration.

Reference: Fundamentals of Databases, Fundamentals of Data Engineering, Fundamentals of Graph Databases — see also Fundamentals

分析代码库（或指定的文件/模块）的数据适配度。通过代码、schema 定义、迁移文件和配置中的证据，识别 schema 设计、迁移安全性、数据完整性、查询正确性、数据建模和 pipeline 质量方面的缺口。

参考：数据库基础、数据工程基础、图数据库基础——另见基础

Domain Knowledge

领域知识

```
references/rubric.md
```
is the scoring source: severity definitions, score anchors per dimension, the N/A rule, scope boundaries, and the overall-score formula. Read it first; it is short.
```
references/checklist.md
```
lists what to inspect in each dimension during steps 4-9.
```
references/wisdom.md
```
is optional background, auto-generated from the three articles above. It has no rubric. When you need depth on one topic (normalization, CDC, data quality dimensions), grep it for that heading and read only that section; never read it whole (~25k tokens).

```
references/rubric.md
```
是评分依据：包含严重性定义、各维度的评分锚点、N/A 规则、范围边界和总体评分公式。首先阅读它；文件很短。
```
references/checklist.md
```
列出了步骤 4-9 中每个维度需要检查的内容。
```
references/wisdom.md
```
是可选的背景资料，由上述三篇文章自动生成，不包含评分标准。当需要深入了解某个主题（规范化、CDC、数据质量维度）时，使用 grep 查找相应标题并只读取对应章节；绝不整份读取（约 25k tokens）。

Configuration

配置

Invoke the resolver CLI to obtain effective weights and thresholds for the review target. Never load

fitness-config.json

directly.

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

is this skill's directory; the resolver ships two levels up in the plugin's

scripts/

. If your agent does not expand the variable, substitute the directory containing this

SKILL.md

Where

<target>

is the file or directory under review. The CLI walks up to discover any module override and merges it with the root config. Include the

Config:

and

Effective weights:

lines from the resolver output within the first 10 lines of the final report as the provenance trail (AC-03.1, AC-08.2). The

effective

object inside the JSON block delimited by

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

carries weights, status thresholds, security, and scoring for any programmatic needs.

调用 resolver CLI 获取审查目标的有效权重和阈值。绝不直接加载

fitness-config.json

。

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

是当前 skill 所在目录；resolver 位于 plugin 的

scripts/

目录中向上两级的位置。如果 Agent 无法展开该变量，则替换为包含当前

SKILL.md

的目录。

其中，

<target>

是待审查的文件或目录。CLI 会向上遍历以发现模块级覆盖配置，并将其与根配置合并。将 resolver 输出中的

Config:

和

Effective weights:

行包含在最终报告的前 10 行内，以作为溯源信息（AC-03.1、AC-08.2）。由

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

界定的 JSON 块内，

effective

对象包含权重、状态阈值、安全设置和评分信息，可用于任何程序化处理需求。

Workflow

工作流

Load the rubric — Read
```
references/rubric.md
```
, then
```
references/checklist.md
```
. Run the resolver (see Configuration) on the target.
Map data boundaries — Grep/Glob for schema definitions (CREATE TABLE, ORM models), migration directories, SQL and query-builder calls, database configuration, and pipeline code (ETL, import/export, batch jobs, stream consumers). Skip build output, vendored dependencies, and test fixtures (
```
target/
```
,
```
bin/
```
,
```
obj/
```
,
```
_build/
```
,
```
dist/
```
,
```
node_modules/
```
,
```
vendor/
```
,
```
.venv/
```
, test dirs) unless the user asks for them. For files over ~500 lines, grep for the data-access patterns (
```
query
```
,
```
execute
```
,
```
BEGIN
```
,
```
FOR UPDATE
```
,
```
ON CONFLICT
```
,
```
JOIN
```
) and read only the surrounding ranges. Also look for documented data policies (ADRs,
```
docs/
```
, migration READMEs), because a documented choice changes what counts as a gap.
Decide applicability — For each of the six dimensions, decide whether anything in scope can be evaluated, using the N/A rule in
```
rubric.md
```
. If nothing data-related exists at all, skip to step 10 and write the short "no data layer" report described under Output Format. Do not invent scores or findings to fill the template.
Audit schema design — Table definitions, column types, constraints, foreign keys, naming.
Evaluate migration safety — Migration files (sqlx, Alembic, Flyway, Rails, Knex, Django, Prisma, raw DDL). Check rollback path or documented forward-only policy, zero-downtime patterns (add-nullable/backfill/constrain, expand-contract), lock-safe DDL, data preservation.
Check data integrity — Unique and CHECK constraints, NOT NULL, transaction boundaries, isolation levels, check-then-act races.
Assess query correctness — JOIN semantics, GROUP BY, parameterization, dynamic IN/LIKE, read-modify-write scoping, type coercion.
Evaluate data modeling — Temporal columns, delete strategy, audit/history, polymorphism, JSON column use.
Assess pipeline quality — Idempotent loads, error routing, run tracking, schema evolution, quality gates between stages.
For steps 4-9, use
```
checklist.md
```
for what to look at and
```
rubric.md
```
for severity and score. Route speed-only findings (missing index for a slow query, N+1, scans) to review-performance and non-data correctness bugs (parsing, regex, general concurrency) to review-algorithms: mention them in one line under "Out of scope", do not score them.
Score and write — Score each applicable dimension against the
```
rubric.md
```
anchors, compute the overall per
```
rubric.md
```
, run the self-check below, then write the report.

加载评分标准——阅读
```
references/rubric.md
```
，然后阅读
```
references/checklist.md
```
。对目标运行 resolver（参见“配置”）。
绘制数据边界——使用 Grep/Glob 搜索 schema 定义（CREATE TABLE、ORM 模型）、迁移目录、SQL 和 query builder 调用、数据库配置及 pipeline 代码（ETL、导入/导出、批处理作业、stream consumer）。除非用户明确要求，否则跳过构建产物、vendored dependencies 和 test fixtures（
```
target/
```
、
```
bin/
```
、
```
obj/
```
、
```
_build/
```
、
```
dist/
```
、
```
node_modules/
```
、
```
vendor/
```
、
```
.venv/
```
、测试目录）。对于超过约 500 行的文件，使用 grep 搜索数据访问模式（
```
query
```
、
```
execute
```
、
```
BEGIN
```
、
```
FOR UPDATE
```
、
```
ON CONFLICT
```
、
```
JOIN
```
），并只读取相关上下文范围。同时查找已有文档记录的数据策略（ADR、
```
docs/
```
、迁移 README），因为已记录的选择会改变哪些内容被视为缺口。
判断适用性——依据
```
rubric.md
```
中的 N/A 规则，逐一判断六个维度在范围内是否有可评估的内容。如果完全不存在任何与数据相关的内容，则跳转到步骤 10，并按照“输出格式”所述编写简短的“无数据层”报告。不要为了填满模板而虚构评分或发现。
审查 schema 设计——表定义、列类型、约束、外键和命名。
评估迁移安全性——迁移文件（sqlx、Alembic、Flyway、Rails、Knex、Django、Prisma、原生 DDL）。检查回滚路径或已有文档记录的 forward-only 策略、零停机模式（add-nullable/backfill/constrain、expand-contract）、锁安全 DDL 和数据保留。
检查数据完整性——UNIQUE 和 CHECK 约束、NOT NULL、事务边界、隔离级别，以及 check-then-act 竞态。
评估查询正确性——JOIN 语义、GROUP BY、参数化、动态 IN/LIKE、read-modify-write 范围和类型强制转换。
评估数据建模——时间列、删除策略、审计/历史、多态关系和 JSON 列的使用。
评估 pipeline 质量——幂等加载、错误路由、运行跟踪、schema 演进和阶段之间的质量门禁。
对于步骤 4-9，使用
```
checklist.md
```
确定检查内容，并使用
```
rubric.md
```
确定严重性和评分。将仅与性能相关的发现（慢查询缺少索引、N+1、全表扫描）转交 review-performance，将非数据正确性缺陷（解析、正则、常规并发问题）转交 review-algorithms：在“范围外”中用一行简要提及，不要为其评分。
评分并编写报告——依据
```
rubric.md
```
的锚点评分每个适用维度，依据
```
rubric.md
```
计算总体分数，执行下述自检，然后编写报告。

Confidence and Severity

置信度与严重性

Only report findings with confidence >= 7/10. For each finding, assess:

Is this a real pattern in the code, not a guess about runtime behavior?
Can you point to a specific file and line?
Is the problematic pattern actually reachable in normal execution?

If any answer is no, do not report it. It is better to miss a theoretical issue than to flood the report with noise.

Severity levels (CRITICAL, HIGH, MEDIUM, LOW) are defined with data examples in

references/rubric.md

. A documented, followed policy (for example an ADR choosing forward-only migrations) meets the matching checklist intent; it is not a finding.

仅报告置信度 >= 7/10 的发现。对于每项发现，评估：

这是代码中真实存在的模式，而不是对运行时行为的猜测吗？
能否指向一个具体文件及其行号？
有问题的模式在正常执行流程中确实可以到达吗？

如果任一问题的答案为否，则不要报告。漏报一个理论问题，也好过用大量噪声淹没报告。

严重性等级（CRITICAL、HIGH、MEDIUM、LOW）及数据示例定义在

references/rubric.md

中。已有文档记录并被遵循的策略（例如选择 forward-only migrations 的 ADR）符合相应检查项的意图，因此不构成发现。

Scoring Dimensions (1-10 each)

评分维度（各 1-10 分）

Score anchors for each dimension are in

references/rubric.md

. A dimension with nothing in scope is

N/A

with a reason, not a number.

Schema Design — Column types, constraints, normalization level, foreign keys, naming conventions, constraint-backing indexes
Migration Safety — Rollback path or documented forward-only policy, zero-downtime patterns, expand-contract renames, lock-safe DDL, data preservation
Data Integrity — Foreign keys, unique constraints, CHECK constraints, NOT NULL enforcement, transaction boundaries, isolation levels
Query Correctness — JOIN type semantics, GROUP BY completeness, parameterized queries, transaction scoping, type coercion avoidance
Data Modeling — Temporal columns, soft-delete consistency, audit trails, versioning, polymorphic associations, JSON column appropriateness
Pipeline Quality — Idempotent loads, error handling, monitoring, incremental vs full loads, schema evolution, data quality gates

每个维度的评分锚点位于

references/rubric.md

。如果某个维度在范围内没有任何可评估内容，则将其标为

N/A

并说明原因，而不是给出数字。

Schema 设计——列类型、约束、规范化程度、外键、命名约定和约束支撑索引
迁移安全性——回滚路径或已有文档记录的 forward-only 策略、零停机模式、expand-contract 重命名、锁安全 DDL 和数据保留
数据完整性——外键、唯一约束、CHECK 约束、NOT NULL 约束、事务边界和隔离级别
查询正确性——JOIN 类型语义、GROUP BY 完整性、参数化查询、事务范围和避免类型强制转换
数据建模——时间列、soft-delete 一致性、审计轨迹、版本控制、多态关联和 JSON 列适用性
Pipeline 质量——幂等加载、错误处理、监控、增量与全量加载、schema 演进和数据质量门禁

Output Format

输出格式

Write the report to

docs/data-review.md

at the root of the repository that contains the target, unless the user gives a path. For a review scoped to a subdirectory or file set, write

docs/data-review-<scope-slug>.md

(e.g.

docs/data-review-crates-foundry-store.md

) so a scoped run does not replace the whole-repo report.

Before writing, self-check:

Every file:line exists and the line says what the finding claims.
Every finding has confidence >= 7 and belongs to this skill (not speed, not non-data correctness).
The overall equals the stated computation, including the CRITICAL cap.
No secret values (connection strings, passwords) are reproduced; refer to them by file:line only.

markdown

undefined

除非用户指定其他路径，否则将报告写入目标所在 repository 根目录的

docs/data-review.md

。对于限定在子目录或一组文件的审查，写入

docs/data-review-<scope-slug>.md

（例如

docs/data-review-crates-foundry-store.md

），避免限定范围的审查覆盖整个 repository 的报告。

写入前进行以下自检：

每个 file:line 都真实存在，并且该行的内容支持发现所声称的问题。
每项发现的置信度均 >= 7，且属于当前 skill 的范围（不包括性能问题或非数据正确性问题）。
总体分数等于规定的计算结果，并应用 CRITICAL 上限规则。
不复现任何 secret 值（连接字符串、密码）；仅通过 file:line 引用。

markdown

undefined

Data Fitness Review

数据适配度审查

Target: <path(s) or scope reviewed> Config: <copied from resolver output> Effective weights: <copied from resolver output>

审查目标： <审查的路径或范围> Config: <从 resolver 输出复制> Effective weights: <从 resolver 输出复制>

Direct Answer

直接回答

(Only when the user asked a specific question, e.g. "are the migrations safe?". Two to five sentences answering it, citing the key findings.)

（仅当用户提出了具体问题时，例如“迁移是否安全？”。用 2-5 句话回答问题，并引用关键发现。）

Summary

摘要

Overall fitness score: X.X / 10 (mean of <list scored dimensions>; <cap note if any>) — <status band>

Dimension	Score	Key Finding
Schema Design	X/10	...
Migration Safety	X/10	...
Data Integrity	X/10	...
Query Correctness	X/10	...
Data Modeling	X/10	...
Pipeline Quality	N/A — no ETL/batch/stream code in scope	—

Documented policies credited: <e.g. forward-only migrations, docs/adr/0007.md> (omit if none)

总体适配度评分：X.X / 10（<已评分维度列表> 的平均值；<如有上限说明>）— <状态区间>

维度	评分	关键发现
Schema 设计	X/10	...
迁移安全性	X/10	...
数据完整性	X/10	...
查询正确性	X/10	...
数据建模	X/10	...
Pipeline 质量	N/A — 范围内没有 ETL/批处理/stream 代码	—

已认可的文档化策略：<例如 forward-only migrations、docs/adr/0007.md>（如果没有则省略）

Detailed Findings

详细发现

Finding 1: [Title]

发现 1：[标题]

Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: X/10
Dimension: [which scoring dimension]
Location: file:line
Description: What the issue is and why it matters.
Evidence: The specific code pattern found.
Impact: What could go wrong with data integrity or quality.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

严重性： CRITICAL / HIGH / MEDIUM / LOW
置信度： X/10
维度： [所属评分维度]
位置： file:line
描述： 问题是什么，以及为什么重要。
证据： 发现的具体代码模式。
影响： 可能对数据完整性或数据质量造成什么问题。
修复方案： 提供代码示例或具体步骤的修复方案。

（按严重性排序，为每项发现重复上述内容）

Schema Design (X/10)

Schema 设计（X/10）

Evidence: file:line references
Issues found
Recommendations

(repeat for each scored dimension; one line per N/A dimension)

证据：file:line 引用
发现的问题
建议

（为每个已评分维度重复上述内容；每个 N/A 维度写一行）

Out of scope

范围外

(Optional. One line each: finding, file:line, route to review-performance / review-algorithms / review-security.)

（可选。每个问题一行：问题、file:line、转交至 review-performance / review-algorithms / review-security。）

Top Action Items (up to 5, by impact)

首要行动项（最多 5 项，按影响排序）

[CRITICAL/HIGH/MEDIUM] Description -- file:line
...

[CRITICAL/HIGH/MEDIUM] 描述 -- file:line
...

Checklist Reference

检查清单参考

See references/checklist.md for the full data checklist.

有关完整的数据检查清单，请参阅 references/checklist.md。

Reference

参考

Based on Fundamentals of Databases, Fundamentals of Data Engineering, Fundamentals of Graph Databases, and guidance from https://jeffbailey.us/categories/fundamentals/

undefined

本报告基于数据库基础、数据工程基础、图数据库基础，以及 https://jeffbailey.us/categories/fundamentals/ 中的指导。

undefined

No data layer

无数据层

When step 3 finds no schema, migrations, queries, or pipelines, write a short report instead: the H1 and provenance lines, a sentence stating that no database schema, migrations, SQL/ORM queries, or data pipelines were found and where you looked (e.g.

grep -ri "CREATE TABLE|SELECT |migrat|sqlx|ORM" (none)

), the summary table with every dimension

N/A

Overall fitness score: N/A (no scored dimensions)

, and any out-of-scope notes. No action items are required. Do not file regex, parsing, or file-handling issues as data findings; list them under Out of scope for review-algorithms.

当步骤 3 未发现任何 schema、迁移、SQL/ORM 查询或数据 pipeline 时，改为编写简短报告：包含一级标题和溯源行；用一句话说明未发现数据库 schema、迁移、SQL/ORM 查询或数据 pipeline，并列出查找位置，例如

grep -ri "CREATE TABLE|SELECT |migrat|sqlx|ORM"

（无结果）；提供所有维度均为

N/A

的摘要表；写明

总体适配度评分：N/A（无已评分维度）

；并添加任何范围外说明。不要求提供行动项。不要将正则、解析或文件处理问题列为数据发现；应将其列在“范围外”中并转交 review-algorithms。