AI生成的数据清洗规则没写进任何文档，下个月换人接手时没人知道数据被怎么改过？

摘要

过去两年，越来越多的数据团队把清洗规则的编写工作交给了大模型：给一段脏数据样本，让模型输出去重、补全、标准化、异常剔除的规则，再人工挑几条跑通就上线。问题在于，这些规则往往只存在于一次对话、一段临时脚本或某个人的记忆里，既没有进入版本库，也没有形成可追溯的文档。一旦负责人离职或轮岗，后来者面对一张字段被改过、口径被调整过的表，既说不清“为什么这么改”，也说不清“改了哪些行”。

本文提出一条贯穿全文的分析主线：规则即代码、代码即文档、文档即审计。围绕这条主线，文章先拆解“规则失忆”的技术成因，再给出从 AI 输出中抽取规则、把规则固化为可执行资产、自动生成人类可读文档、建立变更审计与回放机制的完整操作路径，并讨论多模态数据、跨团队协作与合规场景下的延伸做法。全文以可复制、可运行的步骤为主，配套排错清单与验证方法，目标是让读者在一到两个迭代内，把“没人知道数据被怎么改过”变成“任何人随时能查清数据被怎么改过”。

目录

一、问题界定：AI 生成规则为什么天然“不留痕”

要解决问题，先要承认它不是“某个人忘了写文档”这么简单。把清洗规则的生成交给大模型，等于把一部分决策过程外包给了一个概率系统，而概率系统的输出默认是“会话内有效、会话外丢失”的。笔者认为，规则失忆至少有三层成因，且这三层是叠加而非并列的。

1.1 第一层：规则以自然语言存在，天然不可执行

大模型最擅长的输出形态是自然语言描述，例如“把手机号中的空格和横线去掉，保留 11 位数字，非 11 位的置空”。这句话对人很清楚，对流水线却不可执行。工程上必须把它翻译成正则、映射表或函数，而翻译这一步往往由工程师当场完成、当场调试、当场丢弃。于是真正生效的规则活在代码里，而“为什么这么写”活在对话里，两者从第一天起就是分离的。

国内外关于数据准备与数据质量的研究早已指出，规则的可执行化是数据治理落地的关键瓶颈之一。例如数据质量领域经典的维度框架把“一致性、完整性、有效性”拆成可度量指标，但指标本身不等于规则实现。本文评述：这些框架解决的是“该测什么”，而 AI 生成规则带来的新问题是“规则从哪来、由谁负责、如何复现”，这是传统框架没有覆盖的空白。

1.2 第二层：会话式交互没有版本概念

多数人使用大模型的方式是“贴样本—要规则—改一改—再要一版”。这个过程没有提交、没有 diff、没有回滚。等到下个月新人接手，他看到的只有最终脚本，看不到中间被否决的方案，也看不到某条规则是因为某个业务例外才加上的。更麻烦的是，模型本身可能升级，同样的提示词在不同时间给出不同建议，导致“规则来源”这件事连当事人自己都说不清。

这一点与软件工程里“配置漂移”现象高度相似。笔者认为，可以把 AI 会话看作一种特殊的“未受控配置源”：它持续产出变更建议，却没有进入配置管理。解决思路不是禁止使用 AI，而是给 AI 的输出加一道“落库”闸门。

1.3 第三层：责任边界模糊，没人觉得文档该自己写

在不少团队里，数据工程师认为文档是数据治理岗的事，治理岗认为规则是工程师写的，工程师认为规则是“模型给的”。三方都合理，合起来就是无人负责。这种责任稀释在人员稳定时看不出问题，一旦发生交接就集中爆发。下表把三类典型场景做了对照，便于读者判断自己处在哪一档。

这张表不是要给团队贴标签，而是提供一个自检坐标。多数团队处在 L1 到 L2 之间，本文的目标是把读者推到 L3。需要说明的是，表中“交接成本”为定性分级，来自笔者对公开工程实践的归纳，并非某次受控实验的测量结果，读者可结合自身团队规模校准。

二、主线确立：规则即代码、代码即文档、文档即审计

上一节把问题拆成了三层，这一节给出统一解法。笔者认为，与其在“要不要写文档”上反复拉扯，不如换一个更硬的约束：凡是影响数据的规则，必须以代码形式存在；凡是代码形式的规则，必须能自动生成文档；凡是生成过的文档，必须能对应到审计记录。这三句话构成本文的分析主线，后文所有步骤都是它的展开。

2.1 为什么是“代码”而不是“文档”作为第一落点

直觉上大家会说“那就补文档”。但纯文档有两个硬伤：一是容易与实现脱节，写完就过期；二是无法验证，文档说“去掉了空格”，代码可能只去掉了半角空格。把代码作为第一落点，是因为代码可以被执行、被测试、被 diff，而文档可以由代码派生。这样文档的“真实性”不再依赖人的自觉，而依赖生成流程。

这一思路与基础设施领域“文档即代码”的实践一脉相承。本文评述：数据清洗场景比基础设施配置更复杂，因为规则往往带业务例外，但核心机制可以照搬——把规则声明成结构化对象，再由渲染器输出人类可读版本。区别在于，数据规则还需要额外的“样本验证”环节，这一点后文会专门处理。

2.2 三层结构的关系图

可以用一个简单的分层来理解：最底层是规则对象（Rule Object），中间层是执行引擎与测试，最上层是文档与审计。三者之间是单向派生关系，而不是各自维护。下面这段伪代码展示了规则对象的最小形态，字段命名刻意保持直白，便于团队直接采用。

{
  "rule_id": "phone_normalize_v3",
  "target_column": "contact_phone",
  "intent": "统一手机号格式，剔除无法修复的记录",
  "source": "ai_assisted",
  "author": "data-eng@team",
  "created_at": "2025-03-11",
  "logic": {
    "type": "regex_replace",
    "pattern": "[^0-9]",
    "replacement": "",
    "post_check": "length == 11"
  },
  "on_fail": "set_null_and_flag",
  "sample_before": ["138 0013 8000", "138-0013-8000"],
  "sample_after": ["13800138000", "13800138000"],
  "references": ["internal://dq-standard-07"]
}

这段 JSON 的关键不在字段多少，而在它同时承载了“怎么做”（logic）、“为什么做”（intent）、“谁负责”（author）和“怎么验证”（sample_before/after）。有了这四类信息，文档生成和审计回放才有原料。

2.3 与既有方法的边界

需要澄清的是，本文主线并不替代数据质量框架、也不替代数据目录工具。它解决的是“AI 参与规则生产后，规则资产如何沉淀”这一特定环节。数据目录负责“有哪些表”，质量框架负责“测哪些指标”，本文方法负责“规则从生成到审计的闭环”。三者是拼接关系，不是替代关系。笔者认为，明确边界比追求大而全更重要，否则方案会在落地时被既有系统吞掉。

三、落地路径：从 AI 输出到可执行文档的七步法

这一节是全文的操作核心。适用场景：团队已在使用大模型辅助编写清洗规则，但规则散落在脚本与对话中。环境要求：Python 3.10 及以上、Git、任一支持 JSON Schema 的校验库（本文用 jsonschema）、可选的任务编排工具（Airflow 或 Dagster 均可）。准备工作：选定一张问题较多的表作为试点，准备好近三个月的脏数据样本，并确认团队有代码评审流程。最终效果：规则进入版本库，文档自动生成，变更可回放。

步骤 1：建立规则清单，先盘点再动手

操作：把试点表涉及的所有清洗动作列成清单，逐条标注来源（人工/模型）、当前存放位置、是否有样本。预期结果：得到一张 20 到 50 行的规则清单，其中“来源=模型”的条目通常占三到五成。常见错误：一上来就写代码，结果漏掉隐性规则，比如“某字段为空时用另一字段兜底”这种只在脚本里出现的逻辑。

盘点的价值在于暴露“隐性规则”。笔者建议用一句固定提问自查每条规则：“如果删掉这行代码，下游哪个报表会变？”答不上来的，说明这条规则没有被理解，需要优先补样本。

步骤 2：把 AI 输出改写成结构化规则对象

操作：对清单中“来源=模型”的条目，回到原始对话，把自然语言描述改写成 2.2 节的 JSON 结构。预期结果：每条规则都有 rule_id、intent、logic、样本四要素。常见错误：把多个动作塞进一条规则，导致后续无法单独回滚。建议一条规则只做一件事，组合关系用 pipeline 字段表达。

这一步最容易偷懒，也最值得投入。笔者观察到，规则拆得越细，后续测试和审计的成本越低；反之，一条“大规则”看似省事，出问题时却无法定位是哪一步改坏了数据。可以借助下面的校验脚本，把结构不合规的规则挡在提交之前。

import json, jsonschema

RULE_SCHEMA = {
    "type": "object",
    "required": ["rule_id", "target_column", "intent", "logic", "author"],
    "properties": {
        "rule_id": {"type": "string", "pattern": "^[a-z0-9_]+$"},
        "target_column": {"type": "string"},
        "intent": {"type": "string", "minLength": 8},
        "author": {"type": "string"},
        "logic": {"type": "object"},
        "sample_before": {"type": "array"},
        "sample_after": {"type": "array"}
    }
}

def validate(path):
    with open(path, encoding="utf-8") as f:
        rule = json.load(f)
    jsonschema.validate(rule, RULE_SCHEMA)
    return rule["rule_id"]

if __name__ == "__main__":
    print("valid:", validate("rules/phone_normalize_v3.json"))

关键参数说明：pattern 限制 rule_id 只能用小写字母、数字和下划线，是为了让文件名与 ID 一一对应；intent 设最小长度，是为了防止“清洗手机号”这种过于笼统的描述通过校验。读者可按团队习惯调整。

步骤 3：为每条规则补样本，形成可回归的测试集

操作：从脏数据中抽取正例、反例、边界例各若干条，写入 sample_before/sample_after。预期结果：每条规则至少有 5 组样本，覆盖空值、异常长度、全角字符等情形。常见错误：只写正例，导致规则在边界数据上静默失败。建议把样本单独存为 CSV，规则对象里只放引用路径，避免 JSON 膨胀。

样本的作用不只是测试，它还是文档里最有说服力的部分。新人看十条“改前/改后”对照，比看一段正则更快理解规则意图。本文评述：样本集本质上是一种“可执行的规格说明”，它把规则的口径钉死在具体数据上，减少了自然语言解释的歧义空间。

步骤 4：把规则接入执行引擎

操作：编写一个通用执行器，读取规则 JSON，按 logic.type 分发到具体处理函数。预期结果：同一份规则对象既能在本地跑测试，也能在调度平台跑全量。常见错误：把执行逻辑散落在各个脚本里，导致规则对象与实际行为不一致。下面给出一个最小执行器示例。

import re
import pandas as pd

def apply_rule(df: pd.DataFrame, rule: dict) -> pd.DataFrame:
    col = rule["target_column"]
    logic = rule["logic"]
    if logic["type"] == "regex_replace":
        s = df[col].astype("string")
        s = s.str.replace(logic["pattern"], logic["replacement"], regex=True)
        if logic.get("post_check") == "length == 11":
            bad = s.str.len().ne(11)
            s = s.mask(bad, pd.NA)
        df[col] = s
    elif logic["type"] == "map_values":
        df[col] = df[col].map(logic["mapping"]).fillna(df[col])
    else:
        raise ValueError(f"unsupported logic type: {logic['type']}")
    return df

关键参数说明：astype("string") 而非 object，是为了让空值语义统一为 pd.NA；mask 而非 where，是为了让“置空并打标”的意图更直观。若团队使用 Spark，可把同样的分发结构移植到 DataFrame API，规则对象无需改动。

步骤 5：自动生成人类可读文档

操作：写一个渲染器，遍历规则目录，输出 Markdown 文档，包含规则表、样本对照、变更历史。预期结果：每次提交规则，CI 自动更新文档并提交回仓库。常见错误：文档生成后没人看，原因是缺少“按字段检索”的入口。建议同时生成一份按 target_column 索引的目录页。

渲染器不需要复杂模板，一个循环加字符串拼接即可。真正决定文档质量的是规则对象本身的信息密度：intent 写得清楚，文档就可读；intent 敷衍，文档就是字段罗列。笔者认为，把文档质量前移到规则编写环节，比事后要求“补文档”有效得多。

步骤 6：纳入代码评审与版本管理

操作：规则目录与执行器同仓管理，任何规则变更走 Pull Request。预期结果：每条规则都有提交记录、评审意见和关联 issue。常见错误：把规则放在共享盘或数据库里，绕过评审。建议在 PR 模板中固定三个问题：这条规则解决什么数据问题、影响哪些下游、样本是否覆盖边界。

评审环节是“规则失忆”的最后一道防线。笔者建议评审人至少包含一名下游使用者，因为规则的影响往往在消费端才显现。这一步看似增加流程，实际减少的是交接期的反复沟通成本。

步骤 7：发布与交接演练

操作：模拟一次交接，让未参与项目的同事仅凭文档和规则库，复现一次完整清洗。预期结果：对方能在半天内说清每条规则的作用，并成功跑通测试。常见错误：只验证“能跑”，不验证“能解释”。建议交接演练同时考核两件事：复现结果是否一致、能否指出某条规则的业务背景。

这一步是检验前六步是否真正闭环的试金石。如果交接演练失败，问题通常不在文档排版，而在规则对象的 intent 或样本缺失。回到步骤 2 补信息，比在文档里加形容词更有效。

四、审计与回放：让每一次数据变更都可解释

规则进了版本库，只解决了“规则是什么”，还没解决“数据被怎么改过”。审计要回答的是另一个问题：某张表在某个时间点，被哪条规则、以什么参数、影响了多少行。这一节给出最小可行的审计设计。

4.1 变更日志的最小字段集

操作：在每次执行清洗时，向审计表写入一条记录。预期结果：审计表可按表名、规则 ID、时间范围检索。常见错误：只记录成功/失败，不记录影响行数和参数快照，导致事后无法复现。建议字段如下表。

params_snapshot 这一列常被忽略，但它是回放的关键。规则文件可能被后续提交修改，只有快照能还原“当时到底用了什么参数”。本文评述：审计表不是日志的堆砌，而是“可回放”的前提，字段设计应围绕回放需求倒推。

4.2 规则回放与差异比对

操作：用审计表中的 params_snapshot 和 git_commit，在隔离环境重跑一次清洗，与生产结果比对。预期结果：差异行数为零，或差异可被已知原因解释。常见错误：回放环境的数据快照与生产不一致，导致比对失真。建议在清洗前对源表做快照，快照与审计记录同生命周期保存。

# 伪命令：按审计记录回放
git checkout a1b2c3d -- rules/
python run_pipeline.py \
  --source snapshot/2025-03-11/raw.parquet \
  --rules rules/ \
  --out replay/20250311.parquet

python compare.py \
  --left replay/20250311.parquet \
  --right prod/2025-03-11/clean.parquet \
  --key id \
  --report diff_report.html

关键参数说明：--source 指向快照而非实时表，保证输入一致；--key 指定主键，用于行级比对；--report 输出 HTML 便于交接时直接查看。若差异集中在某一列，通常说明该列规则在两次执行间被修改过，回到 git log 即可定位。

回放机制还有一个隐性收益：它让“规则变更”变得可度量。团队可以统计每月规则变更次数、每次变更的影响行数，进而判断清洗逻辑是否稳定。笔者认为，这类度量比“文档覆盖率”更能反映治理成熟度，因为它衡量的是行为而非形式。

五、工程化增强：测试、CI 与多模态扩展

七步法和审计机制构成了主干，这一节补充三个增强方向，帮助方案在更大规模下站住脚。

5.1 规则级单元测试与 CI 门禁

操作：为每条规则生成一个测试函数，读取样本 CSV，断言输出与 sample_after 一致。预期结果：CI 在每次 PR 时运行全部规则测试，失败即阻断合并。常见错误：测试只覆盖正例，导致边界问题漏网。建议在样本集中显式标注“边界”“异常”“空值”三类，测试报告按类汇总。

CI 门禁的意义在于把“规则正确性”从人工评审中剥离出来，让人专注判断业务意图是否合理。本文评述：自动化测试不能替代业务判断，但能把低级错误挡在合并之前，这对频繁使用 AI 生成规则的团队尤其重要，因为模型输出的规则质量波动较大。

5.2 规则血缘与下游影响分析

操作：在规则对象中增加 downstream 字段，列出依赖该字段的报表与模型。预期结果：修改规则时，系统自动提示受影响的下游资产。常见错误：血缘只记到表级，不记到字段级，导致提示过于宽泛。建议与现有数据目录工具对接，字段级血缘优先。

血缘信息也是交接文档的重要组成部分。新人接手时，最想知道的两件事是“这条规则为什么存在”和“改了会怎样”，前者靠 intent，后者靠 downstream。两者齐备，交接才算完整。

5.3 多模态与非结构化数据的延伸

操作：对文本、图像类数据，把清洗规则拆成“解析规则”和“归一化规则”两层，分别建模。预期结果：非结构化数据的处理同样可版本化、可回放。常见错误：把模型推理直接当作清洗步骤，导致结果不可复现。建议固定模型版本与提示词版本，并把二者写入规则对象。

这一点在近年的多模态数据治理讨论中反复出现。笔者认为，非结构化数据的规则化难度更高，但原则不变：任何影响数据的步骤都要有版本、有样本、有审计。模型版本和提示词版本应被视为规则的一部分，而不是外部依赖。

六、排错清单与验证方法

方案落地过程中，问题往往集中在几个固定位置。下面按“症状—可能原因—处理”给出清单，便于快速定位。

验证方法建议分三层：单条规则用样本测试验证；整条流水线用回放比对验证；交接能力用演练验证。三层都通过，才说明“规则失忆”问题被真正解决。需要说明的是，本文给出的行数、比例等数字多为示例或定性归纳，读者应以自身数据为准。

拓展阅读方面，可参考数据质量维度与规则管理的公开教程（DataVersity 数据管理资料）、开源数据质量工具的官方文档（Great Expectations 文档），以及数据契约相关实践（Data Contract 规范）。视频类可搜索“data quality rules versioning”相关公开分享，注意甄别版本时效。

七、总结与进阶方向

回到标题里的那个问题：下个月换人接手，为什么没人知道数据被怎么改过？因为规则从来没有以“可执行、可版本化、可审计”的形态存在过。本文给出的答案不是“多写文档”，而是把规则的第一落点从自然语言换成结构化对象，再让文档和审计从对象派生。这条主线可以概括为三句话：规则即代码，代码即文档，文档即审计。

从工程角度看，七步法的成本主要集中在步骤 2 和步骤 3，即结构化与样本。这两步做扎实，后面的文档生成、审计回放都是顺水推舟；这两步敷衍，后面的自动化只会放大错误。笔者认为，团队在推广时不必追求工具完备，先用 Git 加一个校验脚本跑通试点，比采购一套平台更能积累经验。

进阶方向有三个：一是把规则对象与数据契约打通，让清洗规则成为上下游约定的一部分；二是引入规则变更的影响面自动分析，减少人工判断；三是探索模型辅助的规则重构，即在规则库积累到一定规模后，用模型做规则去重与冲突检测。三个方向都建立在“规则已资产化”的前提上，没有这个前提，工具再先进也无处发力。

最后提醒一句：AI 生成规则本身没有问题，问题在于把生成结果当成一次性消耗品。把每一次生成都当作一次待入库的变更，交接时就不会再出现“没人知道数据被怎么改过”的尴尬。

主要参考文献

说明：本文参考文献与资料共计 60 余篇（含上述主要文献及文中提及的官方文档、行业白皮书与公开教程），其中近三年资料占比超过一半。文中涉及的行数、比例等数字为示例或定性归纳，非受控实验测量结果；如涉及数据集，均以公开文档描述为准，未做额外虚构预处理。