AI编程Harness工程实践：数仓侧落地方案

一、AI Coding 的现状与结构性痛点

1.1 使用现状：工具已覆盖，提效已显现

从行业实践观察，不少企业的离线数仓团队已经完成 AI 编程工具的基础覆盖：主力是 CLI 形态的 AI 编程助手，辅以数据平台内置的 IDE 插件。在重复性工作上的提效立竿见影——批量建表语句、字段注释补全、例行取数 SQL、存量代码迁移改写，这些场景的产出质量与效率均有明显改善。

但必须承认：工具“能用”与“稳定可靠地用”之间存在一道鸿沟。提效主要来自单点任务的加速，一旦进入完整的需求交付链路，三类结构性问题就会集中爆发。

1.2 三大核心痛点

痛点一：上下文“失忆”，临时约束反复丢失。

典型场景：会话开始时明确约定“金额字段单位为千元”，对话推进到中段后，AI 生成的 SQL 直接把千元当元参与汇总，结果相差 1000 倍。这不是提示词写得不好，而是机制的系统性限制：主流 AI 编程助手普遍内置上下文压缩（context compaction）机制，当对话 token 接近上限（约 95%）时，历史内容被自动折叠为摘要，而口头的、一次性的约束是第一批被丢弃的信息。

痛点二：规范执行靠“记忆”，稳定性不可控。

数仓开发存在大量硬性规范：分层命名前缀、注释三段式（业务含义、枚举值说明、负责人）、INSERT 必须显式指定分区、禁止 SELECT * 等。经验观察是：工期紧张时，人工规范遵守率降至 60%~70%；仅靠会话内提示词约束 AI，遵守率也只有 70%~80%。两者的共同问题在于：规范停留在“指导性内容”层面，执行与否取决于当时的“注意力状态”。工程上真正需要的是护栏——每次产出必须经过强制检查，而不是期望模型“记得”。

痛点三：大型需求把上下文撑满，越到后期越不可靠。

一个中大型需求通常包含：多张源表的血缘梳理、几十个字段口径确认、多轮模型设计推演、成片 SQL 开发与验证。内容叠加后上下文迅速见顶，压缩反复发生，早期结论持续流失，表现为“AI 越到后面越不可靠”，返工率显著上升。

1.3 从“随手问 AI”到“把能力封装起来”

三类痛点的共性是：我们把 AI 当作“一个聪明的临时对话者”，而不是“一个嵌入研发流水线的工程组件”。临时对话者天然存在状态易失、行为不稳、能力不可复用的问题；工程组件则要求状态持久、行为确定、能力可组装。弥合这道差距，正是 Harness 工程的使命。

二、先搞清楚：Harness 到底是什么

“Harness”一词源自测试领域（测试脚手架），在 AI 工程语境下指：包裹在大模型外层、决定“模型能看见什么、能做什么、产出如何被校验”的工程化框架。一个典型的 AI 编程 Harness 通常包含四类组件：

• 上下文管理：系统提示词、项目级规则文件、记忆机制、上下文压缩策略；
• 工具接入：文件读写、命令执行、检索、与外部系统的集成；
• 执行策略：任务规划、子任务分发、多轮循环与终止条件；
• 校验反馈：产出后的自动检查、错误回传与修正回路。

通俗理解：大模型是“发动机”，Harness 是整台“车辆”——方向盘、刹车、仪表盘共同决定这台发动机能否安全、稳定地跑起来。多数团队目前只在“提问技巧”层面优化（相当于研究怎么踩油门），Harness 工程则把优化对象上移到“车辆整体”。

三、核心矛盾：上下文压缩到底丢掉了什么

设计防御之前，先要弄清“敌人是谁”。以主流压缩机制为例，触发时大致发生三件事：保留系统提示词与项目规则文件；保留最近若干轮对话；把更早的历史压缩为摘要。

被优先丢弃的，恰恰是四类对数仓开发最致命的信息：

1. 一次性约束：单位、精度、边界条件、临时豁免规则；
2. 口径结论：多轮讨论才确认下来的指标口径（如“活跃用户”取登录还是下单口径）；
3. 实体关系映射：源表字段与目标字段的对应关系、清洗规则；
4. 已被否决的方案：压缩后 AI 可能重新提出已被推翻的设计，造成循环返工。

这四类信息有一个共同特征：它们是“会话过程中的增量共识”，天然不会出现在任何持久化文件里。因此防御思路只有一个——让关键信息在生成之时就被持久化、被结构化，绝不依赖单次会话的存活。

四、五层防御体系：由简入繁

4.1 第一层：硬规范写死进项目级规则文件（立即可用）

主流 AI 编程工具普遍支持项目级规则文件：会话启动时自动注入系统上下文，且在压缩时被保留。操作要点：

• 只放“必须绝对遵守”的硬约束，不放泛泛建议；
• 控制篇幅（建议 150 行以内），信息密度优先；
• 按主题分块：命名规范、SQL 硬规则、全局数据约定、禁止事项清单。

示例（节选）：

# 全局数据约定
- 所有金额字段单位为「元」；若源表为「分」，必须显式 /100
- 日期统一 STRING 类型：yyyy-MM-dd 或 yyyyMMdd，禁止混用
# SQL 硬规则
- 所有 INSERT 语句必须显式指定 PARTITION
- 禁止 SELECT *，字段必须显式列举
- 表名/字段名遵循分层前缀：ods_ / dwd_ / dws_ / ads_
- 注释三段式：业务含义 + 枚举值说明 + 负责人

局限：这一层解决“全局规范”的失忆，但解决不了“本次需求的临时约束”，更解决不了“执行校验”。

4.2 第二层：自动记忆机制持续沉淀

利用工具的记忆能力（会话中自动提取、跨会话持久），把反复出现的约定沉淀为结构化记忆条目：实体级（某表某字段的口径说明）、项目级（常用维表清单、口径字典位置）、团队级（某类任务的处理偏好）。

与第一层的差异在于：规则文件是“人写的、静态的”，记忆是“AI 自动积累的、生长的”。前者守住下限，后者提升上限。运维要点是定期清理失效条目，防止记忆污染。

4.3 第三层：钩子（hooks）自动验证——核心防御

前两层解决“信息不丢”，这一层解决“行为必查”。利用工具的事件钩子能力，在关键动作完成后自动执行校验脚本：不通过则阻断动作并将违规详情回传给模型，强制其修正后再继续。

示意（伪配置）：

on: sql_file_written
run: scripts/check_dwh_sql.sh
rules:
  - INSERT 必须含 PARTITION 子句
  - 表名必须匹配 ^(ods|dwd|dws|ads)_
  - 禁止 SELECT *
fail: 阻断写入，回传违规详情要求修复

校验脚本可复用团队现有的 SQL 静态检查工具或 lint 方案，无需重复造轮子。这一层的价值在于：把“规范遵守率”从概率问题变成确定性问题——要么合规，要么被拦截，没有第三种状态。

4.4 第四层：子代理隔离，防上下文膨胀

将高 token 消耗且“用完即弃”的操作交给子代理（subagent）执行：子代理拥有独立上下文，只把“结论”带回主上下文。典型适用场景：

• 全表血缘梳理：扫几十张表、上千个字段，只带回“相关表与字段清单”；
• 历史代码检索：通读旧任务的代码，带回“可复用的模式与口径结论”；
• 文档批量阅读：带回摘要与要点。

效果：主上下文只承载“决策所需信息”，会话寿命显著延长，压缩触发频率大幅下降。

4.5 第五层：技能（SKILL）文件化，减少重复消耗

把“方法论 + 提示词 + 校验脚本”打包成可复用的技能模块，配合新一代工具的按需加载机制：平时驻留磁盘、不占用上下文；触发时才注入，用完即释放。由此，每次任务不必重复编写长提示词，流程细则全部内置于技能内部。

五、数仓 Harness 架构：整体视图

┌──────────────────────────────────────┐
│            数仓研发流水线              │
│   需求 → 建模 → 开发 → 验证 → 上线     │
└───────────────┬──────────────────────┘
                │
┌───────────────┴──────────────────────┐
│             Harness 工程层           │
│  ① 规则文件（硬约束）                  │
│  ② 自动记忆（增量沉淀）                │
│  ③ 钩子校验（行为护栏）                │
│  ④ 子代理（上下文隔离）                │
│  ⑤ 技能模块（流程标准化）              │
└───────────────┬──────────────────────┘
                │
┌───────────────┴──────────────────────┐
│          语义资产层（团队共享）        │
│  指标口径字典 / 血缘图谱 / 质量规则库   │
└──────────────────────────────────────┘

三层分工：流水线是“业务面”，Harness 是“工程面”，语义资产是“数据面”。Harness 层的五个组件分别对应五层防御；语义资产层则决定 AI 产出准确率的上限，详见第八节。

六、基于技能规范的数仓工作流设计

6.1 八步流程标准化

将数仓任务开发固化为八个标准步骤，每步定义输入、产出与检查项：

1. 需求理解：提取指标、维度、粒度、时间范围与更新频率；
2. 语义确认：与口径字典比对，显式标记新增口径与冲突口径；
3. 血缘调研：定位源表、确认字段可用性与数据质量（交给子代理）；
4. 模型设计：确定分层归属、表结构、主键粒度与更新策略；
5. 代码生成：按规范产出 SQL/调度脚本；
6. 静态校验：钩子自动执行规范检查，不通过则阻断；
7. 数据验证：行数比对、主键唯一性、金额汇总核对、空值率与抽样比对；
8. 文档沉淀：注释与口径说明回写语义资产。

以“语义确认”步骤为例的提示词模板（节选）：

你是数仓口径审核员。请逐条比对以下指标与《口径字典》：
- 完全一致的，标注 [沿用]，给出字典编号；
- 字典中不存在的，标注 [新增]，给出你理解的口径定义待人工确认；
- 存在冲突的，标注 [冲突]，列出双方差异，禁止自行选择。

6.2 调用方式改造：按需注入

原则：主对话只保留“当前步骤所需上下文”，步骤细则封装在技能文件中按需加载。收益有二：一是上下文开销从“每次全量提示词”降为“按需增量注入”；二是步骤之间天然形成检查点，问题可定位到具体环节。

6.3 命令体系：标准化入口

为高频任务建立命令化入口（示意）：

• /dwh-model：输入需求描述，产出模型设计文档；
• /dwh-sql：输入设计文档，产出合规 SQL；
• /dwh-verify：输入任务名，执行全量数据验证并输出报告；
• /dwh-doc：回写注释与口径文档。

命令背后是同一套技能模块，团队任何成员、任何新会话得到的都是一致的行为，消除“每个人调教出不一样的 AI”的问题。

七、落地三步走

第一步：项目级上下文持久化（半天量级）。梳理团队硬规范产出规则文件；把历史沉淀的口径说明写入项目记忆。这一步上线即可消除大部分“失忆”问题。

第二步：配置钩子自动验证（1~2 天）。从最高频的两三条规则做起（INSERT 分区、命名前缀），校验逻辑复用现有检查工具。

第三步：子代理隔离高 token 操作（按需推进）。优先落地血缘调研与历史代码检索两个场景，并明确“子代理只带回结论”的产出格式约束。

节奏建议：不要追求一次到位。规则文件是成本最低、见效最快的第一步；钩子校验是收益/成本比最高的单点；其余按痛点出现频率逐步补齐。

八、Harness 工程能解决什么：回到本质

8.1 数仓 AI 开发的本质瓶颈：语义理解

在数仓场景，SQL 语法从来不构成瓶颈，真正难的是“这个指标到底是什么口径”。AI 产出 SQL 的错误，绝大多数源自语义误解而非语法缺陷：把“支付金额”理解成含退款的口径、把“活跃”理解成登录而非下单、忽略多币种与单位差异。因此，任何提效方案的终点，都是把团队的语义资产变成 AI 可消费的输入。

8.2 语义 × 数据 = 准确率

一个直观的公式：AI 产出准确率 ≈ 语义供给质量 × 数据供给质量。Harness 工程解决的是“语义供给”——让口径字典、血缘关系、验证规则以工程化方式进入 AI 的输入与校验回路；数据供给（源表可信度、元数据完整度）则需要数据治理体系托底。两者相乘，任何一项趋近于零，整体准确率都不可用。

8.3 具体解决的四类问题

1. 规范一致性：命名、注释、分区等硬规范从概率执行变为强制执行；
2. 口径准确性：语义确认步骤强制比对口径字典，新增口径显式化；
3. 结果可靠性：数据验证成为流水线的固定环节，而非“有空再查”；
4. 经验可复用：临时会话中的结论被沉淀为记忆与技能，新成员、新会话直接继承。

8.4 与传统数仓 AI 使用方式的对比

传统方式：人带着问题找 AI，规范靠口头叮嘱，验证靠人肉复查，结论随会话消亡。Harness 化方式：AI 嵌入流水线，规范由文件与钩子承载，验证自动执行，结论持续沉淀。一句话概括：从“AI 是一个聪明的实习生”，升级为“AI 是流水线上一台自带质检工位的设备”。

8.5 从“AI 帮我写代码”到“AI 嵌入研发流水线”

提效的第一阶段是“让 AI 替我打字更快”；Harness 工程开启的是第二阶段：“让 AI 成为流程中一个确定性的、可审计的、可复利的节点”。当规范、语义、验证全部工程化之后，评估 AI 的方式也随之改变——不再是“这次生成得准不准”，而是“这条流水线的产出合格率是多少、瓶颈落在哪一步”。

九、结语

数仓场景的 AI 编程提效，短期靠提示词，中期靠 Harness，长期靠语义资产。五层防御体系给出了一条从“今天就能做”到“值得持续投入”的渐进路径：先把硬约束持久化，再让行为可校验，最后让知识可复利。当 AI 的每一次产出都经过护栏、每一个结论都被沉淀，提效才能从“个体手感”沉淀为“组织能力”。