用机器学习项目检验规格驱动 AI 开发

先写规格，再让 AI 改代码，能减少多少返工？作者拿一个足球比赛预测项目做了小实验：把写死的训练、测试年份改成参数，走完 Spec-Driven Development（SDD，规格驱动开发）流程，再按规格核对结果。

结论相当克制：规格提供了一份有效的验收清单，却没有提前阻止遗漏。四份文档、约 20 分钟、两个文件的修改，也不足以证明这套流程比直接写提示词更高效。对日常用 AI 改代码的程序员，这种边界比方法介绍更有参考价值。

先写规格，到底约束了什么

短提示词经常只写目标，省略约束。模型只能自行补齐，而有些错误要等实现完成才能暴露。

作者的 Brasileirão Pro Analytics 就出过问题：早期版本拿整赛季累计的控球、抢断、进球数据，预测同一赛季的比赛。预测某场比赛时，特征里已经混入之后才发生的结果，属于数据泄漏（data leakage）。作者在 commit b96e6ba 修正了计算逻辑，只使用每场比赛之前的数据。

这次修复发生在 SDD 实验之前，不能算作 SDD 的成果。它说明的是：代码能运行，并不代表计算遵守了业务边界。

SDD 希望把这些边界提前写下来。原文引用 Birgitta Böckeler 在 2025 年 10 月 15 日的分析，区分了三个层次：

• spec-first：先写规格，用它指导 AI 开发。
• spec-anchored：功能完成后继续维护规格，让它跟着功能演进。
• spec-as-source：规格成为主要源文件，人不直接修改代码。

单项功能规格也不同于 memory bank。前者描述这次功能应该怎样工作，后者保存产品与代码库的通用知识。Spec Kit 用 constitution 承担高层原则的角色，相当于每次修改都要遵守的项目规则。

原文引用的 GitHub Blog 文章发表于 2025 年 9 月 2 日，将流程分为 specify、plan、tasks、implement：先明确用户、问题和成功标准，再决定技术方案，然后拆出可单独实现和验证的任务，最后由代理执行、人来审查。加上前置的 constitution，就是作者此次采用的流程。

给年份加参数，为什么还会漏东西

项目从 CSV 读取比赛，计算历史特征，用 2025 赛季训练 Poisson 回归，再用 2026 年已完成的比赛测试。

实验起点是 commit b9e399f。年份散落在 src/features.py、src/app.py 和 src/avaliar_modelo.py。文件名原本就按 partidas_{ano}.csv 生成，真正需要处理的是年份的来源。

作者把四份文档放在 .spec/，并非 Spec Kit CLI 使用的 .specify/。文档总共 40 行，内容并不长：

• constitution.md 要求兼容 Python 3.10+、禁止数据泄漏、为新增方法及特征或架构变化在 /tests 添加自动化测试，并让 README.md 反映现状与模型限制。
• specify.md 要求原有 tests/test_features.py 继续通过，2025、2026 组合保持 48.0% 准确率和 1.020 log loss，Streamlit 面板照常渲染，加载逻辑中不再散落年份。
• plan.md 计划让 features.py 接收 ano_treino、ano_teste，在 app.py 设置 ANO_TREINO、ANO_TESTE，并让 avaliar_modelo.py 从 sys.argv 读取年份，默认仍为 2025、2026。
• tasks.md 按三个文件拆出三项任务。

实现提交是 b21411b，时间为 2026 年 10 月 28 日 21:51。app.py 新增 8 行、删除 4 行；avaliar_modelo.py 新增 15 行、删除 13 行；features.py 没改。

原因很关键：计划以为 features.py 内有固定路径，但实际的 carregar_partidas 已经接收 temporadas，并按年份拼文件名。

规格可以写得清楚，计划仍然可能建立在错误的代码理解上。

事后核对还发现，features.py 保留着默认值 (2025, 2026)，没有新增测试，也没有更新 README，面板结果缺少记录。作者将这些视为规格或项目规则落实上的缺口。仓库只有一次实现提交，无法还原中间是否发生过错误或修正。

这些文档完成后没有继续更新，任务也未勾选，所以这次属于 spec-first，不能当成持续维护规格的实践。

旧指标不变，离参数化完成还有多远

验证里最容易误读的是：experimento/depois_previsoes.txt 与 antes_previsoes.txt 完全一致。

听起来很稳，但生成这些预测的测试并没有经过本次修改的 app.py 和 avaliar_modelo.py。作者明确指出，验证变化靠的是指标比较，不能拿输出文件相同替代对修改路径的检查。

新年份进一步暴露了边界。仓库没有 partidas_2027.csv，当时也没有 2027 年比赛结果。作者临时创建文件验证，但这些文件未提交到仓库：

• 文件为空时，评估脚本以 EmptyDataError 结束，应用显示读取错误。
• 只有表头时，两条路径都因没有样本，触发 StandardScaler 的 ValueError。
• 有赛程但没有比分时，应用能显示预测，却把无比赛可评估显示成 0.0% 准确率；评估脚本仍报相同的 ValueError。

年份参数能传进去，只证明代码可以选择另一份数据。它没有解决数据为空、只有未来赛程、尚无评估结果的问题。

尤其是 0.0%：它看起来表示全部预测错误，实际却是根本没有可评估的比赛。对数据面板而言，这两种状态必须区分。

我的判断

我认可这次实验最实用的部分：把验收要求写下来，再逐项对照提交。没有这一步，遗漏很容易被「代码跑通了」掩盖。

但它没有证明完整 SDD 流程更有效。experimento/tempo.txt 记录开始于 21:32，21:51 提交实现，总计约 20 分钟。时间没有按写文档、编码、验证拆分，也没有直接提示词的对照实验，无法判断谁更快、返工更少。

这次得到验证的是验收清单的价值，完整流程的收益仍不清楚。

四份文档服务于两个文件的修改，作者觉得偏重，这是有依据的感受，但仍是单个项目、单项功能的经验之谈。相比之下，小改动可以先尝试一份短说明，集中写目标、约束和验收方式；是否需要拆成多份文件，要看协作与审查需求。

原文引用的外部分析也应分开看。Böckeler 提到 Kiro 曾把一个小 bug 扩成 4 个 user stories、16 条验收标准，也观察到代理忽略指令、重建已有类。这些是她的案例，并非本次实验结果。

Thoughtworks 在 2025 年 11 月 Technology Radar 中把 SDD 放在 Assess，建议探索，同时提醒流程复杂、工具表现依任务而异、长规格难审查。原文还说明该条目已不在当前版，因此不能把那次评级当作持续有效的推荐。

作者猜测 SDD 更适合网页抓取流水线、数据库迁移等存在多个失败点的改动，但没有实测。这个方向可以尝试，尚不足以成为团队统一采用的理由。

能拿来做什么

• 用 AI 改参数或配置前，先写清默认值、入口、历史行为和验收方式。小改动可以从一份短清单开始，再决定是否拆分规格与计划。
• 让 AI 制订计划前先核对现有函数和调用链。尤其要确认功能是否已经支持参数，避免像本例一样，为不存在的固定路径安排修改。
• 验证必须经过真正改动的入口。前端或 Node 项目也一样，底层函数测试通过，不能替代对页面入口、命令行参数或接口路径的检查。
• 给数据面板明确区分「有结果可评估」「只有待预测数据」「没有数据」。没有样本时显示原因，不要用 0.0% 冒充评估结果。