先说我自己的背景这两三年我一直在做数据分析和 BI 相关的工作日常除了写 SQL、写 Python 脚本还要应付各种“这个指标口径不对”“图表里为什么多了一个 null 值”“能不能再加一个维度”这类需求。后来我慢慢把工作流从“打开编辑器就写代码”改成了“先写 Spec再让 AI 编程工具照着 Spec 生成代码”也就是常说的 Spec Coding。这个思路放到数据分析场景里解决的不只是“写代码”的问题更关键的是把需求、数据口径、输出格式这些容易扯皮的东西提前用一份所有人都能读懂的规格文件钉死。这篇文章我就用自己实际做过的一个项目来拆解如何用 Spec Coding 做数据分析。如果你手里也有那种“数据文件不小、业务口径绕、需求方今天一个想法明天一个想法”的分析任务或者你想用 Claude Code、Codex 这类 AI 编程工具做数据分析但总觉得生成的代码不够可控那这篇文章应该对你有用。我会把完整思路、规格文件怎么写、AI 工具怎么调、中间踩过哪些坑都讲清楚你可以直接照着复制。1. Spec Coding 的整体设计与数据分析适配性1.1 传统数据分析脚本为什么总是“越改越乱”以前我做数据分析最常见的流程是需求方口头说一句“帮我看一下最近三个月的用户复购情况”我脑子里自动脑补出一堆细节——复购周期是多久是按订单算还是按用户算金额去不去除退款然后我打开 Jupyter Notebook 或写一个 Python 脚本边写边猜写完第一版发给对方对方说“不对复购应该是同一个用户在不同月份都购买”我一看自己统计的是 30 天内多次购买口径完全对不上。这种问题的根源不在于“写代码”的能力而在于从一开始就没有把需求变成一份“无歧义的定义”。我在项目组里见过太多脚本变量名是df1、df2指标逻辑像“考古现场”一样今天加一个条件明天补一个过滤最后根本没有人敢动它。哪怕你用了 AI 编程工具如果你给 AI 的指令还是“帮我做一下复购分析”它生成的代码也只是“看起来合理”的猜测该错还是错。1.2 Spec Coding 是什么一份规格文件同时给人看和给 AI 看Spec Coding 说白了就是先把“你要做什么”写清楚再让工具去写“怎么做”。我理解的规格不是那种厚重的几十页需求文档而是结构化的、字段级别的定义集合。它至少要包含分析目标、数据来源和字段说明、指标口径定义、输出交付物格式、数据边界和异常处理方式。这样做的好处是你可以把这份规格直接粘贴给 Claude Code 或 Codex让 AI 编程工具按照规格去执行而不是让 AI 自己去“设计需求”。人和 AI 读的是同一份文件这就在最大程度上避免了“AI 自由发挥”的情况。我在实际项目中还会在规格里标注“哪些是硬性要求哪些是建议项”这样 AI 在生成代码时就有了明确的决策依据。提示Spec Coding 不是“用英文写需求给 AI”而是“用结构化语言描述数据分析任务的全部约束条件”。约束越明确AI 生成的代码就越接近于你真正想要的东西。1.3 为什么数据分析场景特别适合 Spec Coding数据分析有一个天然优势数据字段、指标公式、输出格式都非常适合“规格化”。比如你写“GMV 订单实付金额之和”这句话没有任何歧义你写“复购率 在统计周期内出现 2 次及以上有效订单的用户数 / 有效用户总数的百分比其中有效用户是首次支付时间落在统计周期内的用户”这也能被精确转换成代码。而其他场景比如“写一个用户登录的微服务”规格化就没那么容易因为涉及系统交互、权限、状态流转光靠一段文字描述很难覆盖完整。但数据分析的任务相对收敛输入是表输出是表或图中间是计算逻辑整个链路都很适合 Spec Coding。我自己后来把 SQL 分析、Python 报告、甚至一部分 pcap 流量数据统计都搬到了这个框架里效率提升非常明显。2. 环境准备与工具选型用哪套组合最稳2.1 AI 编程工具的选择Claude Code、Codex 还是纯 API先说工具选型。现在市面上能用来做 Spec Coding 的 AI 编程工具不少我用得比较多的是 Claude Code 和 Codex。如果你有条件直接使用这些工具我建议你关注三个能力维度一是长上下文处理能力因为规格文件经常有几千字加上数据结构说明工具能不能一次读完很关键二是多文件编辑能力因为数据分析通常要同时改配置、脚本、输出目录三是“主动执行”能力也就是能不能自己在终端里跑命令、看报错、再修复。我自己个人的使用习惯是复杂项目用 Claude Code靠它的长上下文和文件感知能力来一次定位多个文件简单脚本用 Codex启动快、改单个文件很顺手。如果你的环境里没有这些工具用 API 方式写一个简单的循环也能实现类似效果核心逻辑就是“把规格文件读进来加上明确指令让模型生成代码再自动跑测试”只是工程化程度低一些。注意不管用哪款工具都要把“规格文件”作为最优先级的上下文。你可以把 specs 目录放在工作目录里并在第一条指令里写明“请先阅读 specs/analysis_spec.md严格按照其中的定义执行不要自行补充或修改指标口径”。否则 AI 很容易凭自己的常识去“脑补”业务场景。2.2 数据分析基础环境Python pandas 还是 SQL数据分析的执行环境我建议根据数据量来定。如果你的数据落在数据库里比如企业内部的 MySQL、PostgreSQL或者你写的是网约车那种 hive/spark 大数据项目那就直接让 AI 编程工具生成 SQL或者用 PySpark 脚本去跑。如果数据是 CSV、Excel 或者单机就能放下的规模那 Python pandas 是最省事的选择配合 matplotlib 或 pyecharts 做可视化输出也方便。我在这次项目中用的是 Python 3.11 pandas 2.x数据集是一个模拟电商订单表大概 20 万行。这个规模用 pandas 很轻松几秒就能跑完 groupby 和 merge。规格文件里我会写清楚“运行环境是 Python 3.11依赖 pandas、matplotlib、openpyxl”这样 AI 生成代码后依赖环境也不会跑偏。2.3 目录结构与规格文件的位置规划做 Spec Coding 项目时我强烈建议你把目录结构从一开始就定好这能显著减少 AI 编程工具的“迷茫”。我常用的结构是这样的project/ ├── specs/ │ ├── analysis_spec.md │ └── data_dictionary.md ├── data/ │ ├── raw/ │ └── processed/ ├── src/ │ ├── steps/ │ └── utils/ ├── outputs/ │ ├── tables/ │ ├── charts/ │ └── report.md └── run_all.py目录分清楚以后你可以在规格里明确写“所有输入数据放在 data/raw/ 下所有结果输出到 outputs/tables/ 和 outputs/charts/报告统一写到 outputs/report.md”。AI 编程工具就会自动往这些路径里读和写不会出现“结果文件散落在桌面上”的情况。我实际用下来这个习惯让整个项目变得异常清晰哪怕三个月后再回来看我也知道每个文件是干嘛的。3. 核心规格文件怎么写一份可以让 AI 读懂的数据分析规格3.1 分析目标与业务背景先讲清楚“为什么做这个分析”规格文件的第一段我通常写“分析背景和分析目标”。这段不是废话它决定了 AI 在做技术选型时的方向。比如你写“本分析用于评估某电商平台近三个月的用户复购情况核心目的是找出复购率下降的可能原因”AI 就会倾向于做趋势分析、留存分析、按渠道拆解如果你写“本分析用于生成财务报表”AI 就会更注重金额口径和汇总逻辑。我在analysis_spec.md里会这样写# 电商用户复购数据分析规格 ## 1. 分析背景 本分析针对某电商平台近 3 个月的订单数据目标是为运营团队提供复购现状和趋势的量化描述。 ## 2. 核心问题 - 整体复购率是多少按月趋势如何 - 不同新老用户的复购率差异 - 从下单到二次购买的时间间隔分布如何 - 哪些商品类别的复购贡献最高这个部分不需要太长但要能回答“这个项目到底在算什么”。有一次我偷懒没写背景只写了一个“复购分析”AI 生成的代码把“未支付订单”也算进去了我跑完才发现数据偏得离谱。从那以后背景部分再也不敢省。3.2 数据字典与字段级约定让 AI 不瞎猜字段含义数据分析中最大的坑就是字段理解不一致。同一个order_status可能在不同库存放的是paid、已完成、1这些不同的值。所以我会在规格文件里放一份字段级的数据字典明确每个字段的类型、枚举值、是否可能为空。例如这份订单表的字段定义字段名类型说明示例值空值处理order_idstring订单唯一编号OD20250101001为空则删除该行user_idstring用户唯一编号U100023为空则删除该行order_timedatetime下单时间北京时间2025-01-01 12:20:33无法解析则置 NULLpay_timedatetime支付时间2025-01-01 12:21:02未支付则为 NULLpay_amountfloat实付金额元199.00非数值则改为 0 并标记goods_idstring商品 IDG1024为空则填充 unknowncategorystring商品一级类目数码为空则填充 unknown你可能会觉得这有点啰嗦但正是这份字典让 AI 生成的代码从一开始就用了正确的字段名和类型转换方法而不是靠正则表达式猜。我把这个表格放在独立的数据字典文件里并在规格主文件里用include的方式引用它。提示字段定义越细调试成本越低。尤其要注意“空值处理”你如果不告诉 AI 空值怎么处理它可能会直接 dropna把大量有效数据丢掉你根本发现不了。3.3 指标口径定义复购率、GMV、留存率一个都不能含糊数据分析里最核心的部分是指标口径。这一节我建议逐字写清楚最好精确到“分子是什么、分母是什么、在什么范围上聚合、时间窗口怎么滑”。不要觉得这些“太基础”团队里每个人对“复购率”的理解都可能不同AI 更不知道你想表达的是哪一个。我在规格文件里会这么定义## 3. 核心指标定义 - 有效订单支付时间在统计周期内且 pay_amount 0 的订单。 - 有效用户拥有至少 1 笔有效订单的用户。 - 首次购买用户在统计周期内首次产生有效订单的用户。 - 复购用户在统计周期内产生过至少 2 笔有效订单的用户。 - 复购率 复购用户数 / 首次购买用户数 * 100%。 - 月度复购率当月首次购买用户中在当月或后续月份再次购买的人占比。你看这样定义之后“月复购率”是按当月新客去跟踪后续月份和“固定窗口内多次购买”是完全不同的算法。AI 拿到这个定义生成逻辑时会直接写groupby(user_id).filter(lambda x: len(x) 2)然后按首次购买月份去归集而不是简单统计一笔订单里买了几个商品。这样产出的结果才真正能用于业务决策。3.4 输出交付物定义表格、图表、结论分别放在哪里规格文件里还需要写清楚“交付物长什么样”。我通常约定四类输出汇总结果表outputs/tables/summary_statistics.csv行是指标名列是数值。按月趋势图outputs/charts/monthly_trends.png折线图包含订单量、用户量、复购率三条线。用户间隔分布图outputs/charts/repeat_interval.png直方图。结论报告outputs/report.md包含关键数字、图表引用和 3-5 条业务结论。如果你不做这个约定AI 可能会输出一堆print到控制台虽然逻辑对但交付体验很差。我一般会在规格里再加一句“所有输出结果必须写入约定路径不能只打印在终端里”。这能让最终产物变成一个可以被后续流程自动调用的东西而非一次性截图。3.5 给 AI 的分步执行指令模板最后我还习惯在规格文件的末尾附上一段“执行建议”相当于给 AI 编程工具一个工作流程。这段不是让 AI 必须照做的命令而是给它一个操作顺序建议。比如执行步骤建议 1. 读取 data/raw/orders.csv使用 pandas 加载。 2. 按数据字典清洗数据删除无效 order_id 行。 3. 生成有效订单表保存到 data/processed/valid_orders.csv。 4. 按指标定义进行聚合计算。 5. 生成三张图表保存到 outputs/charts/ 目录。 6. 汇总关键指标写入 outputs/tables/summary_statistics.csv。 7. 根据所有结果编写 outputs/report.md结论不超过 5 条。这一步做完你基本上就等于把“数据分析任务”翻译成了一个“AI 可以执行的工程任务清单”。接下来要做的就是把它喂给 Claude Code 或 Codex在终端里看它一步步完成。4. 实操过程让 AI 按规格完成一次完整数据分析4.1 数据体检先行让 AI 先跑探索性分析别急着算指标我每次都会在正式计算前加一步“数据体检”也就是让 AI 编程工具先对原始数据做探索性数据分析EDA。这一步的目的不是出最终结论而是快速暴露数据质量问题比如字段类型不对、空值比例过高、时间字段解析失败等。我会给工具指定一个轻量任务。请先读取 data/raw/orders.csv并输出 1. 数据整体 shape前 5 行预览。 2. 每列的非空值数量、唯一值数量、示例值。 3. pay_time 的空值比例order_time 能否正常解析为 datetime。 4. pay_amount 的最小、最大、平均值检查是否有负数或异常值。 不需要做任何聚合分析只需要给我数据质量报告。这一步非常值得做。我遇到过几次数据文件里时间格式有“2025/01/01 12:20:33”和“2025-01-01 12:20:33”混着来如果直接按字符串分组月份会被拆得七零八落。提前做数据体检就能把这类问题一次性暴露在明面上后面的核心计算就不会被脏数据带偏。4.2 核心逻辑生成按规格定义让 AI 写出可追溯的代码数据体检做完接下来就是把规格文件里的核心指标定义交给 AI 编程工具让它生成聚合逻辑。这里我会明确指定“按规格文件中第 3 节指标定义生成代码”而不是让它上网搜“怎么算复购率”。假设规格文件里已经定义了首次购买用户和复购用户AI 生成的代码大概会长这样import pandas as pd # 读取有效订单 orders pd.read_csv(data/processed/valid_orders.csv, parse_dates[order_time, pay_time]) # 统计每个用户的有效订单数和首次支付时间 user_stats ( orders.groupby(user_id) .agg( first_pay_time(pay_time, min), order_count(order_id, nunique), total_amount(pay_amount, sum), ) .reset_index() ) # 定义首次购买用户首次支付时间落在统计周期内 # 这里以 2025-01-01 到 2025-03-31 为例 start_date pd.Timestamp(2025-01-01) end_date pd.Timestamp(2025-03-31) first_time_users user_stats[ (user_stats[first_pay_time] start_date) (user_stats[first_pay_time] end_date) ].copy() # 定义复购用户有效订单数 2 first_time_users[is_repeat] first_time_users[order_count] 2 # 计算复购率 repeat_rate first_time_users[is_repeat].mean() * 100 print(f首次购买用户数: {len(first_time_users)}) print(f复购用户数: {first_time_users[is_repeat].sum()}) print(f复购率: {repeat_rate:.2f}%)你会发现这段代码的每一步都能在规格文件里找到影子比如first_pay_time的来源、order_count 2这个阈值、时间范围的设定这些都是规格里先定义好的。AI 在这里承担的不是“设计业务逻辑”的角色而是“把人类已确认的业务定义翻译成代码”。这一步非常重要因为它保证了代码可审计、可解释——业务方问起来你能指着规格说“这就是咱俩约定好的口径”。4.3 按月趋势与用户间隔分布在规格框架下扩展分析视角核心复购率算完我再让 AI 按规格文件里的要求扩展出两个分析视角一是按月趋势二是用户两次购买的时间间隔分布。按月趋势我给出的指令是请基于 data/processed/valid_orders.csv 计算 2025 年 1 月到 3 月每个月的 - 有效订单数 - 有效用户数 - 首次购买用户数 - 当月新客在当月产生复购的人数 - 月复购率 输出为 outputs/tables/monthly_summary.csv并生成折线图 outputs/charts/monthly_trends.png。这个环节的关键是“当月新客在当月产生复购”这个口径。因为新客可能是在 1 月 30 日首次购买到 2 月才第二次购买你不能简单地把“当月订单里购买了 2 次的用户”作为新客月复购的口径。AI 在生成代码时会因为规格里写了“复购用户 至少 2 笔有效订单”而自动处理好这个细节但你的提示词里最好还是要强调“按首次购买月份进行归集”。用户两次购买的时间间隔分布我用的是计算每个复购用户从首次购买到第二次购买的天数间隔输出直方图保存到 outputs/charts/repeat_interval.png 同时输出间隔中位数和 P25/P75 分位数。这个数据对运营来说很有用能看出用户通常在第几天被“唤醒”。我自己之前做活动复盘时发现很多用户是在首次购买后 7 天左右产生复购于是把优惠券的有效期设置成了 7 天内有效效果比 30 天有效期的券好了很多。4.4 可视化自动生成与核验图表也要人肉检查AI 编程工具生成图表很方便但图表能不能用人一定要看一眼。我的习惯是让工具生成图表之后马上打开文件检查三件事坐标轴单位是否正确、是否有异常极值导致图形失真以及图表标题和图例是否和规格文件里描述的一致。有一次 AI 生成的折线图里多了一条线我检查规格文件才发现是它自动把“用户数”和“订单量”放到同一张图上但 y 轴刻度没做归一化订单量的数值把用户量的变化趋势完全压扁了。我随后在规格文件里补充了一句“所有趋势图中如果存在数据量级差异较大的多个指标请使用双 y 轴或分开绘图”再让 AI 重新生成效果好多了。注意AI 编程工具能很快地画出图但图表语义的正确性必须由人来把控。别只顾着“它跑通了”就跳过核验环节。4.5 多轮迭代时的规格更新方法实际项目中需求方看到第一版结果后一定会提出新的修改意见比如“复购的统计周期改成 90 天”“再加一个城市维度”“图表里把毛利率也带出来”。这时候不要直接在终端里跟 AI 说“把复购改成 90 天”你需要回去更新规格文件把新需求写进去然后再让 AI 重新执行。我一般会在规格文件里加一个“变更记录”小节例如## 9. 变更记录 v1.12025-04-02 - 调整复购周期为 90 天。 - 新增城市维度分组输出。 - 图表新增毛利率走势。这样 AI 编程工具在重新读取规格时能明确知道目标和过去版本之间的差异不会出现“旧逻辑和新逻辑混用”的情况。同时你手里也留下了一份完整的项目演进记录对后续复盘很有价值。5. 常见问题与排查技巧实录5.1 规格写得太“代码化”AI 只会照抄不会思考我第一次写规格时几乎把每一个数据处理步骤都写成了伪代码比如“用 groupby 按 user_id 分组后 count 订单数”。结果 AI 生成代码的时候反而很死板遇到字段名不完全一致的情况就会直接报错因为它的“思考空间”被我压缩得太小。后来我调整了写法在规格里只约定“目标和口径”不约定“实现方式”。比如我会写“统计每个用户的订单数量”而不是“用 groupby 函数统计每个用户的订单数量”。这样 AI 可以根据实际数据情况选择合适的实现方式自由度更高也不容易出错。经验规格描述“做什么”和“做到什么程度”代码实现交给 AI 去发挥。如果你把两个层面混在一起反而会让 AI 编程工具束手束脚。5.2 数据文件编码、时间格式不一致导致的诡异报错中文数据文件最常见的坑是编码问题。如果你的 CSV 是 GBK 编码而 AI 生成的代码用 utf-8 去读就会抛 UnicodeDecodeError。我在规格文件里会专门写一行“所有原始 CSV 文件均为 UTF-8 编码如遇解码错误请尝试 GBK 编码读取”这样 AI 遇到报错时就能自己切换编码不需要你手动介入。时间字段格式不一致是另一个高频问题。我的解决办法是在数据体检阶段就把order_time统一成pd.to_datetime()并强制指定格式为mixed让 pandas 自动兼容多种格式。如果你发现日期里混入了纯日期和时间戳可以先写一个小脚本来归一化再进入正式分析流程。5.3 AI 生成的结论不可信如何独立验证分析结果AI 生成一份报告很容易但报告里的数字对不对必须有独立验证。我的做法是让 AI 编程工具在执行完核心计算后额外输出一个“计算口径确认模块”把我用的关键中间表保存下来比如first_time_users.csv我再抽样几个用户去原始数据里手动核对。比如我随机抽 5 个 user_id打开原始订单表看这些用户的第一笔支付时间是否和first_pay_time一致再看他们的订单数是否和order_count一致。只要抽样 5~10 个就能发现大部分逻辑性问题。这个方法虽然原始但非常可靠。如果你连账都对不上后面的结论写得再漂亮也没有说服力。5.4 常见问题速查表问题表现可能原因排查与解决复购率偏高或偏低很多口径定义不清例如把“订单数”和“用户数”混用回到规格文件第 3.3 节核对分子分母定义用中间表抽样验证图表 y 轴被某一指标压扁量级差异大单 y 轴不适配规格里补充“双 y 轴或拆分图表”要求重新生成输出文件路径缺失AI 未读取规格文件中的目录约定检查工作目录是否包含 specs/ 文件夹并在提示词里强调“请先阅读规格文件”数据清洗后行数异常少空值处理约定不明确AI 直接 dropna更新数据字典逐字段定义空值填充方式月度汇总时间错位时间字段存在多种格式解析出错数据体检阶段用 pd.to_datetime 统一转换再保存中间表这张表是我实际工作中不断积累出来的。每次遇到新问题我都会把它写进自己的问题库下次项目开始时直接对照一遍能少走很多弯路。6. 踩坑心得与 Spec Coding 数据分析的扩展方向6.1 一次把“需求评审”省掉的教训有次我接手一个内部数据统计任务需求方只给了 three 行描述我当时觉得项目小没写规格就直接让 AI 编程工具生成代码跑数据。结果跑出来之后需求方说“我要的是累计值不是当月值”整个分析方向全错了。那一次让我彻底改了习惯哪怕是一个 20 分钟能跑完的小分析我也至少用 5 分钟把口径写在文件里先给需求方看一眼确认了再动手。这件事给我的启发是Spec Coding 的核心价值不是“让 AI 写代码更快”而是“让人类沟通需求更精确”。那些你觉得“这么简单不用写”的话往往是后续返工的最大隐患。规格文件就是用来逼你把模糊的需求变成清晰的文字的。6.2 从单一脚本到分析体系把规格变成可复用的资产当你手上有越来越多的数据分析任务后你会发现自己可以沉淀一套“分析规格模板库”。比如电商复购分析、运营活动效果分析、用户留存分析、RFM 模型分析这些项目的规格文件 80% 可以复用。换一个数据集时只需要改一下数据字典、时间范围、指标定义里的业务参数就能快速得到新项目的结果。我自己就在团队里建了一个specs_templates/目录按分析主题分类。新同事接手数据分析任务时先挑一个最接近的模板改几个字段再找业务方确认口径效率比从零开始高很多。这也算 Spec Coding 带来的一个隐藏收益——它让个人经验变成了组织可复用的资产。6.3 扩展到 SQL、Spark 和大数据场景如果你处理的是 hive 或 spark 级别的数据Spec Coding 的思路同样适用只是执行引擎从 pandas 换成了 SQL 或 PySpark。你可以在规格文件里写明“采用 Spark DataFrame API输出为 parquet 格式”然后让 AI 编程工具生成对应的 PySpark 代码。我处理网约车订单数据时数据量一天就有上千万行单机 pandas 根本跑不动。当时的做法是把规格文件里的数据口径原样保留只把“运行环境”一节改成了“Spark 3.4 集群模式”AI 生成的代码也相应变成了 Spark DataFrame 操作。因为你把指标定义写清楚了AI 只是换一套 API 实现底层逻辑完全一致迁移成本很低。6.4 最后提一个我自己常用的工作流技巧我现在日常做数据分析固定节奏是这样的拿到需求后先写规格然后自己花 3 分钟虚读一遍如果有看不懂的地方就说明规格不够清楚先改到能看得懂为止再拿着规格去找需求方确认确认完再喂给 AI 编程工具工具跑完后我先验证关键数字再验证图表文字最后才输出报告。整个流程看起来比“直接写代码”多了一步但返工率降了不止一半。至于 AI 编程工具怎么选我的观点是它们都在快速迭代不必太纠结某一家。真正拉开差距的是你手里的规格写得好不好、数据口径是否清楚、验证流程是否严格。工具只是执行者规格才是项目的灵魂。