办公数据5 阅读

如何让 Codex 生成指标口径说明文档

发布时间 2026/07/04

很多团队的数据问题，不是没有报表，而是报表背后的指标口径没有说清楚。一个“新增用户数”，可能有人按注册成功算，有人按首次登录算，有人按手机号去重算，还有人按设备 ID 去重算。短期看只是小误差，长期看会导致复盘结论、增长判断和业务决策全部变形。这类问题不适合只靠人工重新翻一遍代码。更好的做法是让 Codex 进入项目仓库，读取 SQL、数据模型、埋点定义、接口字段、Dashboard 配置和旧文档，先整理出指标清单，再生成一份可复核的指标口径说明文档。注意，Codex 不能替业务负责人拍板指标口径。它更适合做“提取、对齐、标注疑点、生成文档初稿、补齐验收清单”这些工作。最终口径仍需要数据负责人、产品负责人或业务负责人确认。

为什么指标口径说明文档很重要

指标口径说明文档的本质不是“写给别人看的说明书”，而是团队内部统一判断标准的工具。没有这份文档，数据系统越复杂，指标越容易变成一堆只能靠老员工口头解释的隐性知识。

对产品团队：能明确一个功能到底看哪些指标，避免用错误数据判断迭代效果。
对运营团队：能知道活动转化、留存、付费等指标的计算范围，减少复盘争议。
对开发团队：能把接口字段、埋点事件、数据表和业务指标对应起来。
对管理层：能降低“同一个指标不同部门报出不同结果”的风险。
对新人：能快速理解数据体系，不必从历史 SQL 和群聊记录里倒推逻辑。

什么情况下适合让 Codex 来做这件事

如果只是从零写一个空白模板，ChatGPT 就够了。但如果你已经有项目代码、SQL 文件、dbt 模型、埋点配置、BI 报表或数据导出文件，那么让 Codex 处理更合适，因为它可以直接读取项目文件，并基于真实上下文生成文档。

场景	是否适合 Codex	原因
已有 SQL / dbt / API / Dashboard 配置	适合	Codex 可以从真实文件中提取指标来源和计算逻辑。
只有一个指标名称列表	一般	可以生成模板，但容易缺少真实计算依据。
指标口径存在争议，需要业务拍板	适合辅助	Codex 可以列出不同口径差异，但不能代替业务决策。
需要生成可维护的 Markdown / MDX 文档页	适合	Codex 可以直接把文档放入 docs 目录并保持项目格式。
需要批量整理几十个历史报表	适合	Codex 可以先输出指标清单、重复项和冲突项。

一份合格的指标口径说明文档应该包含什么

不要只写“指标名称 + 计算公式”。这会让文档看起来有内容，但真正使用时仍然解释不清。指标口径至少要覆盖统计对象、时间范围、过滤条件、去重规则、数据来源和使用限制。

字段	说明	示例
指标名称	业务侧常用名称，不要只写数据库字段名。	注册用户数
英文 / 字段名	代码、SQL 或埋点中对应的字段、别名或事件名。	registered_users / user_signup
业务含义	这个指标想回答什么业务问题。	统计完成注册流程的用户规模。
统计对象	按用户、订单、设备、会话还是页面访问统计。	用户
统计周期	按日、周、月、自然日、滚动 7 天还是实时。	按自然日
计算公式	明确分子、分母、聚合方式。	COUNT(DISTINCT user_id)
过滤条件	排除测试数据、内部账号、退款订单、无效会话等。	exclude is_test = true
去重规则	说明用哪个 ID 去重，多个 ID 冲突时怎么处理。	优先 user_id，缺失时不计入
数据来源	表、视图、事件、接口或数据集。	users 表 + signup_events
刷新频率	实时、小时级、T+1、手动更新。	T+1，每天 03:00 更新
适用范围	哪些页面、报表、团队可以使用。	增长日报、注册漏斗
口径风险	容易误解或不适合使用的情况。	不代表激活用户，也不包含游客。

让 Codex 生成指标文档前，先准备这些材料

你给 Codex 的上下文越完整，生成出来的口径文档越接近真实情况。不要只给一句“帮我生成指标文档”，否则它只能写出通用模板。

数据表结构：schema.sql、Prisma schema、Supabase 表结构、dbt models、数据库迁移文件。
历史 SQL：报表查询、定时任务、数据仓库脚本、分析脚本。
埋点文件：tracking plan、events.ts、analytics.ts、Segment / GA / Mixpanel 事件定义。
BI 配置：Metabase、Looker、Superset、Tableau 或自研 Dashboard 的查询文件。
业务文档：PRD、运营日报、增长复盘、指标解释说明、旧版 Excel 口径表。
验收要求：希望输出 Markdown、CSV、Notion 表格、doc 文档还是代码仓库里的 docs 页面。

第一步：让 Codex 扫描项目里的指标线索

第一条指令不要急着让 Codex 写最终文档。先让它做指标盘点，找出项目里到底有哪些指标、来源文件在哪里、是否存在重复或冲突。

请你先不要修改代码，也不要生成最终文档。请扫描当前项目中与数据指标相关的文件，包括但不限于： - SQL 查询、dbt models、数据库 schema、迁移文件 - analytics / tracking / events 相关代码 - dashboard、report、charts、BI 配置文件 - docs、README、PRD 或运营报表说明请输出一份「指标线索清单」，按表格整理： 1. 指标名称或疑似指标名称 2. 出现位置：文件路径 + 行号或模块名 3. 关联字段 / 事件 / 表名 4. 当前能推断出的计算逻辑 5. 是否存在多个不同口径 6. 需要人工确认的问题限制： - 不要凭空补业务含义。 - 无法确认的地方标记为「待确认」。 - 不要修改任何文件。

第二步：让 Codex 识别重复指标和口径冲突

指标文档最有价值的部分，不是把指标抄一遍，而是把冲突挖出来。例如 dashboard 里“活跃用户”按登录算，增长日报里按任意行为事件算，这两个数字都叫活跃用户，但不能混用。

基于你刚才整理的指标线索清单，请继续分析是否存在指标口径冲突。请重点检查： 1. 同名指标是否在不同 SQL / 报表 / 代码中有不同计算方式。 2. 不同名称的指标是否实际使用了相同计算逻辑。 3. 是否存在分子、分母、过滤条件、去重 ID、时间窗口不一致的问题。 4. 是否混用了自然日、滚动周期、UTC 时间、本地时间或 T+1 数据。 5. 是否有测试账号、内部账号、无效订单、退款订单没有被过滤。输出格式： - 冲突指标名称 - 冲突来源文件 - 差异点 - 可能影响的报表或业务判断 - 建议人工确认的问题限制： - 只做分析，不要直接统一口径。 - 不确定的结论必须标注证据不足。

第三步：生成指标口径说明文档初稿

完成盘点和冲突识别后，再让 Codex 生成文档。这样它会基于项目中的真实材料写，而不是泛泛地生成一份“指标说明模板”。

请基于前面的指标线索清单和冲突分析，生成一份指标口径说明文档初稿。文档路径建议：docs/metrics/metric-definition.md 文档结构请包含： # 指标口径说明文档 ## 1. 文档使用说明 ## 2. 指标总览表 ## 3. 核心指标详细口径 ## 4. 指标冲突与待确认问题 ## 5. 数据来源与刷新频率 ## 6. 后续维护规则每个核心指标必须包含： - 指标名称 - 英文名 / 字段名 / 事件名 - 业务含义 - 统计对象 - 统计周期 - 计算公式 - 数据来源 - 过滤条件 - 去重规则 - 刷新频率 - 适用报表 - 不适用场景 - 待确认问题限制： - 不要把猜测写成事实。 - 每个结论尽量写明来源文件。 - 不能确认的口径统一写「待确认」。 - 生成 Markdown 文档即可，先不要改业务代码。

第四步：让 Codex 补充示例 SQL 和验收方式

指标口径文档不能只给中文解释。最好给出示例 SQL 或伪代码，这样开发、数据分析师和 BI 同事都能复核。

请为指标口径说明文档中的核心指标补充「示例 SQL / 伪 SQL」。要求： 1. SQL 只用于说明口径，不要求能在生产环境直接运行。 2. 每段 SQL 需要标注依赖表、关键字段、过滤条件和去重逻辑。 3. 如果项目中已经有真实 SQL，请优先引用并简化说明。 4. 如果缺少数据表或字段，请标注「缺少数据来源，需人工确认」。 5. 为每个指标补充一个验收方法：如何检查这个指标有没有算错。请直接更新 docs/metrics/metric-definition.md。

第五步：把指标文档变成可维护的项目规则

如果项目长期迭代，不要只生成一次文档就结束。更稳妥的做法是把指标维护规则写进 AGENTS.md，让以后每次 Codex 修改埋点、报表、SQL 或统计逻辑时，都顺手检查指标文档是否需要更新。

AGENTS.md 中可加入的指标文档规则 ## Metrics documentation rules - 当修改 SQL、埋点、报表、Dashboard、数据模型或统计接口时，必须检查 docs/metrics/metric-definition.md 是否需要同步更新。 - 不允许在没有说明口径的情况下新增业务指标。 - 不允许把字段名直接当作指标定义。 - 所有指标都必须说明统计对象、统计周期、计算公式、过滤条件、去重规则、数据来源和刷新频率。 - 不确定的口径必须标注「待确认」，不能编造业务结论。 - 如果发现同名指标存在不同计算逻辑，必须在 PR 说明中列出口径冲突。

指标口径文档示例结构

下面是一段可以放进项目 docs 目录的结构示例。实际项目中，Codex 应该根据真实文件把字段、表名和 SQL 补齐。

指标名称	业务含义	计算公式	数据来源	风险说明
注册用户数	完成注册流程的用户数量	COUNT(DISTINCT user_id)	users / signup_events	不等于激活用户，不含游客。
激活用户数	完成关键激活动作的用户数量	COUNT(DISTINCT user_id) WHERE activated_at IS NOT NULL	user_activation_events	激活动作定义需业务确认。
注册转化率	访问注册页后完成注册的比例	注册成功用户数 / 访问注册页用户数	page_views + signup_events	分母需明确是否排除重复访问。
7 日留存率	注册后第 7 天仍有行为的用户比例	第 7 天活跃用户 / 注册用户	user_events	需明确自然日还是滚动 24 小时。
付费转化率	完成付费的用户占注册用户比例	付费用户数 / 注册用户数	orders + users	退款订单、测试订单需要过滤。

适合达灵感收录的任务指令模板

这类文章的重点不是教用户“指标文档是什么”，而是给用户一条可以直接放进 Codex 的任务指令。下面这条可以作为达灵感页面核心模板。

你是一个熟悉数据分析、BI 报表、SQL 和产品埋点的工程助手。目标：请基于当前项目，生成一份「指标口径说明文档」，用于统一产品、运营、数据和开发团队对核心指标的理解。请执行以下步骤： 1. 扫描项目中的 SQL、schema、dbt models、数据迁移、埋点、Dashboard、报表和 docs 文件。 2. 整理所有疑似业务指标，输出指标名称、出现位置、字段 / 表 / 事件来源。 3. 分析同名指标是否存在不同计算方式，不同名称是否存在重复口径。 4. 为每个核心指标生成标准口径说明，包括：业务含义、统计对象、统计周期、计算公式、数据来源、过滤条件、去重规则、刷新频率、适用场景、不适用场景和待确认问题。 5. 生成 docs/metrics/metric-definition.md。 6. 为核心指标补充示例 SQL 或伪 SQL，并说明验收方法。 7. 输出一份待人工确认的问题清单。限制： - 不要修改业务代码。 - 不要凭空编造指标含义。 - 所有不确定内容必须标注「待确认」。 - 结论必须尽量引用来源文件路径。 - 文档语言使用中文。完成标准： - 文档结构清晰，可直接给产品、运营、数据和开发共同评审。 - 至少覆盖项目中已有的核心业务指标。 - 明确列出冲突口径和无法确认的问题。 - 生成的文档能作为后续指标维护的基准。

进阶指令：让 Codex 生成指标字典 CSV

如果团队后续要导入 Notion、飞书多维表格或数据目录系统，可以让 Codex 额外生成 CSV。

请在生成 Markdown 文档的同时，额外生成 docs/metrics/metric-dictionary.csv。 CSV 字段请包含： metric_name, metric_key, business_meaning, owner, calculation, source_table, source_event, filters, dedup_rule, time_window, refresh_frequency, related_dashboard, status, open_questions 要求： - status 只能使用 confirmed / pending / conflict 三种状态。 - 如果口径冲突，status 标记为 conflict。 - 如果无法确认，status 标记为 pending。 - 不要为了填满字段而编造信息。

进阶指令：让 Codex 检查新指标是否缺少说明

当团队经常新增页面、报表或埋点时，可以让 Codex 做一次“指标文档缺失检查”。这比事后补文档更稳。

请检查当前分支是否新增或修改了业务指标相关逻辑。重点检查： - 新增 SQL 查询或统计字段 - 新增 analytics event 或 tracking 参数 - 新增 Dashboard 图表 - 新增报表接口或聚合逻辑 - 修改已有指标计算方式请判断 docs/metrics/metric-definition.md 是否需要更新。输出： 1. 新增或变更的指标 2. 关联文件路径 3. 当前文档是否已有说明 4. 缺失或需要更新的内容 5. 建议补充的文档片段限制： - 不要直接修改文件，先输出检查报告。

常见错误：不要让 Codex 这样生成指标文档

错误做法	问题	正确做法
直接说“帮我写指标文档”	Codex 缺少项目上下文，容易生成通用模板。	先让它扫描 SQL、埋点、报表和文档。
只让它输出指标名称	无法解决口径不一致问题。	要求输出计算公式、过滤条件、去重规则和来源文件。
让它自动统一所有口径	可能错误覆盖业务历史逻辑。	让它列出冲突，由人工确认后再统一。
不要求标注待确认	会把推断写成事实。	所有不确定内容必须明确标记。
不写维护规则	文档很快过期。	把指标维护要求写入 AGENTS.md 或 PR 检查清单。

验收清单：判断 Codex 生成的文档能不能用

每个核心指标是否都有业务含义，而不是只有字段名。
是否写清楚统计对象：用户、设备、订单、会话、页面还是事件。
是否写清楚统计周期：自然日、自然周、滚动窗口、实时还是 T+1。
是否写清楚计算公式、分子、分母和聚合方式。
是否写清楚过滤条件：测试账号、内部账号、退款订单、异常数据。
是否写清楚去重规则：user_id、device_id、order_id、session_id。
是否标注数据来源：表、字段、事件、接口、报表文件。
是否列出口径冲突和待确认问题，而不是强行给出确定答案。
是否能被产品、运营、开发和数据团队共同评审。
是否有后续维护规则，避免文档生成后很快失效。

FAQ

1. Codex 能不能直接决定哪个指标口径是正确的？

不能。Codex 可以从项目文件中提取证据，列出口径差异和疑点，但业务口径需要负责人确认。尤其是增长、收入、留存、激活这类指标，不应该让 AI 单方面拍板。

2. 没有数据仓库，只是普通后台项目，也能做吗？

可以。只要项目里有数据库表、接口、统计页面、埋点事件或报表 SQL，Codex 就可以先做指标线索整理。文档可以从小范围开始，比如只整理注册、登录、订单、付费、留存几个核心指标。

3. 指标文档应该放在哪里？

如果是技术项目，建议放在 docs/metrics/metric-definition.md。如果团队主要用 Notion 或飞书，也可以让 Codex 先生成 Markdown 和 CSV，再复制到协作工具中。

4. Codex 生成的指标文档需要人工复核吗？

必须复核。尤其要检查公式、过滤条件、时区、去重规则、测试数据排除、退款订单处理、埋点触发时机等内容。

5. 这篇文章适合在达灵感里怎么定位？

它适合归到“数据分析 / BI / 运营增长 / 项目文档”分类。用户搜索的不是理论概念，而是“怎么让 Codex 帮我把混乱的数据指标整理成文档”。

发布建议

标题建议：如何让 Codex 生成指标口径说明文档？
副标题建议：从 SQL、埋点、Dashboard 到指标字典的完整流程。
内链建议：链接到“如何用 Codex 分析渠道转化数据”“如何用 Codex 生成 BI 看板结构”“如何用 Codex 检查数据字段是否一致”。
页面转化建议：正文中间插入“复制这条 Codex 指令”模块，底部放“更多数据分析类 Codex 任务”。

参考资料

OpenAI Developers：Codex web、任务指令ing、AGENTS.md、Best practices。

• Codex web

• 任务指令ing

• Custom instructions with AGENTS.md

• Best practices

Codex办公数据BI指标口径数据字典