SPECMINE：规格驱动开发工件的大规模语料 —— 精读
论文链接：https://arxiv.org/abs/2608.25202 数据获取：Zenodo DOI 10.5281/zenodo.22102779；HuggingFace: ShyAgarwal/specmine；GitHub: shyamagarwal13/specmine-official 发表时间：2026年8月 机构：Carnegie Mellon University（Shyam Agarwal、Bogdan Vasilescu）——纯高校 领域标签：cs.SE —— 挖掘软件仓库 / 数据集论文（MSR 2027 Mining Challenge 数据集）
一、论文背景
1.1 什么是规格驱动开发（SDD）
Spec-Driven Development（SDD） 是 2025 年后迅速兴起的实践：开发者把「要构建什么」写成一个或多个结构化自然语言规格（Markdown 文档），由 AI coding agent 据此生成和修改代码。规格可以人写，但更多时候由 AI 从简短提示起草、再由人策展。工具浪潮随之而来——GitHub Spec Kit、AWS Kiro、OpenSpec、Conductor 等数十种。
关键变化在于：spec 而非代码，正在成为开发者编写、评审、维护的首要工件。就像建筑行业里，图纸逐渐比砖块更决定建筑质量——当实现外包给 agent，「写什么规格」成了人类的主要工作。
1.2 研究空白：从未被大规模研究的工件
此前没有任何数据集捕获这些工件：不知道有哪些工具、产出了什么、spec 与最终代码什么关系。最近的 MSR Challenge 数据集看的都是「模型输出侧」——DevGPT（MSR 2024）收集开发者与 ChatGPT 的对话，AIDev（MSR 2026）收集 agent 写的 PR。SPECMINE 填的是缺失的「意图层」：要构建什么的规格本身。
二、论文定位和关联工作
2.1 定位谱系
| 数据集 | 研究对象 | 层次 | 与 SPECMINE 区别 |
|---|---|---|---|
| DevGPT (MSR 2024) | 开发者-ChatGPT 对话 | 交互过程 | 模型输出侧，非持久化工件 |
| AIDev (MSR 2026) | agent 撰写的 PR | 代码变更 | 实现侧，无意图层 |
| 传统 MSR 语料（如 MSR 挑战历史数据集） | commit/issue/PR | 代码演化 | AI 时代之前，无 SDD 工件 |
| SPECMINE | spec 文件 + 其 PR + 引用索引 | 意图层 | 唯一覆盖 SDD 实践从诞生起的语料 |
2.2 与同团队 RAMP 论文的关系
值得注意：第二作者 Vasilescu 团队同期还有一篇 RAMP（本文 batch 中另一篇精读的主题），研究「团队 commit 的 AI 配置工件与代码质量的关系」。两篇共享对「版本控制中的 AI 工件」的关注：SPECMINE 做广度普查（生态全景），RAMP 做深度分析（成熟度与质量后果）。SPECMINE 的定位是基础设施型贡献——为社区提供研究素材，而非自己提出算法结论。
三、问题定义
具体问题：SDD 工件散落在 GitHub 数万仓库中，形态各异（spec.md / specs.md / .kiro/specs/…），由不同工具生成——如何把它们收集、归属到工具、并连接到代码？
核心洞察：工具归属可以靠路径指纹而非内容判断。每个 SDD 工具都会生成自己固定的目录布局（如 OpenSpec 的 openspec/、Spec Kit 的 specs/、Kiro 的 .kiro/specs/），因此「spec.md 文件名普查 + 目录路径指纹」就是一条幂等、确定性的归属通道——不依赖任何模型判断，可复查、可逆转。
形式化：给定 GitHub 公开仓库全集，构建四层语料：(1) broad census：spec.md/specs.md 文件普查及工具归属；(2) Kiro census：.kiro/specs 三件套独立普查；(3) PR 层：≥10 星仓库中所有触碰 spec 的 PR 及完整 changeset；(4) 追溯索引：spec 到代码/PR/issue 的类型化引用。约束：每一步可审计、可逆、幂等。
四、问题解法
4.1 四层数据结构
- Broad census（广度普查）：对 spec.md/specs.md 做文件名普查。GitHub 代码搜索有 1000 结果上限且 total_count 不可靠，作者用自适应大小分区（递归切分文件大小区间直到每叶低于上限，逐叶翻页到真正空页）绕过，并验证幂等（重跑新增约 0 文件）与确定性（独立抓取收敛）。原始 822,901 行 → 去重 575,633 → 过滤后保留 470,795（滤掉包缓存 97,757、vendored 依赖 376、2024 年前的 6,705——被滤行保留旗标与理由，可审计可反转）。
- Kiro census：AWS Kiro 因目录布局特殊（requirements/design/tasks 三件套）对文件名普查不可见，单独普查得 98,574 文件 / 12,910 仓库。
- PR 层：11 个工作流最清晰的工具、≥10 星的 949 仓库（963 仓库-工具对），抓取所有触碰 spec 的 PR 及完整逐文件 changeset（每个文件标记 is_spec/is_code），得 5,992 PR / 581 仓库。这使「spec 与实现在同一 PR 内共同变更」这一最简工作流直接可观测。
- 追溯索引：从 spec 正文、commit 消息、OpenSpec tasks.md、目录 git tree 四处汇编 2,421,323 条类型化引用（128 万指向代码文件、86 万指向兄弟文档、15 万指向 PR……）；对 OpenSpec 更进一步——把 tasks.md 里的任务→代码引用对 435,401 条在锚定 commit 的 git tree 上解析，记录任务是否勾选、文件当时是否存在。这提供了独立于 co-change 的第二条 spec→代码通道：一个任务指向从未出现的文件，就是「规格从未被实现」的证据。
每个 spec 还附完整 commit 历史（780,335 条）与 39 个结构特征（标题树、EARS/Gherkin 需求模板标记、未填占位符、TODO 等）。
4.2 工具归属验证
30 个跨 10 个命名工具的 spec 人工核对：归属 100% 正确——每个 spec 都在其工具目录下且匹配该工具公开模板。
五、评估指标与实验证据
数据集论文的「实验」是语料本身的统计画像与质量验证：
5.1 规模统计
| 数量 | 值 |
|---|---|
| spec 文件（broad census） | 470,795 |
| 不同仓库 / 所有者 | 73,030 / 44,521 |
| 命名工具 | 17（另加 Kiro 单独普查） |
| Kiro 工件 | 98,574 文件 / 12,910 仓库 |
| spec 文件 commit | 780,335 |
| spec 触碰 PR | 5,992 / 581 仓库（其中 81.2% 同 PR 改代码） |
| 类型化引用 | 2,421,323 |
| OpenSpec 任务→代码引用 | 435,401 |
| 语料体积 | 14.7 GB |
5.2 关键画像数字
- 从诞生起被记录：99.7% 的 spec 首次提交于 2025 年之后、92% 在 2026 年——语料完整覆盖这一实践从出现到现在的全程，与现有基准重叠 <0.05%。
- 工具生态：OpenSpec 文件最多（274,955），Spec Kit 覆盖仓库最广（10,619）；caffeine.ai 仓库数领先但属应用生成器（大量自动生成的一次性 app），开发者主动采用的前三是 Kiro、Spec Kit、OpenSpec。
- 成熟度提醒：73,030 仓库中仅 923 个 ≥100 星——语料必然混着教程、模板克隆与一次性实验，作者不做预过滤，但交付了画线所需的一切（fork/模板旗标、内容哈希、is_tiny/has_lorem/未填占位符标记），并要求使用者报告所用过滤器。
5.3 为什么这些设计能支撑研究
- 双通道 spec→代码：PR co-change 是启发式（81.2% 支持其合理性，但「先并 spec 后实现」等工作流对它不可见），追溯索引恰好覆盖 co-change 够不到的情形——两者交叉验证是论文明示的开放研究问题。
- 全部标识符是活 URL：任何一行可重抓、可与外部数据（issue、CI 日志）join——语料可生长而非快照固化。
- 三档发布：Zenodo 全量（DOI 固定版本可复现）+ HuggingFace Parquet（pandas/polars/DuckDB 直接读）+ GitHub 镜像与 500 仓库样本（分钟级克隆查询）。
六、效果优势的根源解释
为什么这个语料此前造不出来、现在能造？因果链：
- 客观障碍：GitHub 搜索 1000 上限使朴素普查必然丢数据——自适应大小分区把「不可枚举」变「可枚举且幂等」。
- 归属可靠性：若靠内容分类归属 47 万文件，误差会随规模放大且不可复现；路径指纹是确定性映射，30 抽样 100% 正确，且归属决策可逆转（被滤集保留）。
- 「spec 如何变成代码」可观测：这是 SDD 研究的核心问题，单靠快照或单靠 PR 都不够——PR 层给出共变证据、引用索引给出声明证据（包括「声明了但不存在」的负证据），git tree 解析使 435,401 条任务引用可核对。
- 从出生记录的价值：SDD 是 2025 年才出现的实践，晚一年普查就永久丢失起源期数据——99.7% 首提交在 2025 后说明这次快照恰好接住了实践的全生命周期，后续版本化 DOI 让纵向研究可对固定版本复现。
七、必要知识反推
- 领域知识层：SDD 工具生态的具体目录约定（17 个工具各自的布局指纹）；软件仓库挖掘的常规对象（PR/commit/issue 结构）；EARS、Gherkin 等需求工程语法——不知道这些设计不出 39 个结构特征。
- 方法论知识层：普查式（census）与抽样式研究的区别及各自适用；幂等性/确定性验证协议；co-change 启发式的适用边界分析；数据伦理（公开仓库的许可与再分发规则、个人信息剥离）。
- 工程知识层：绕过搜索上限的自适应分区算法；blob URL 去重键设计（file_url_sha16）；MySQL 主干 + Parquet/HuggingFace 多档发布的工程。
知识融合的关键节点：把「需求工程」这个老领域的概念（traceability、EARS、验证与确认）翻译到「AI 生成代码」的新语境——意识到 spec 是意图层的工件、其与代码的追溯关系（而非内容本身）才是社区最缺的研究资产，于是把主要工程预算花在追溯索引上。
八、论文中可以提取的通用性灵感
路径指纹优于内容判断，当结构约定存在时。证据：17 工具归属 30 抽样 100% 正确、幂等可逆。推广：任何有目录约定生态（前端框架脚手架、CI 配置、包管理器清单）的大规模挖掘都可先找「确定性指纹」再考虑模型分类。
新实践要从出生就开始记录。证据：99.7% spec 首提交在 2025 年后，快照恰好接住起源期。推广：对正在爆发的实践（agent 记忆文件、MCP 配置、模型卡）尽早做版本化普查——晚一年的代价是起源数据永久缺失。
负证据是数据集的一等公民。证据：任务指向的文件不存在 = 规格未被实现的证据，435,401 条引用里显式记录 exists_at_anchor。推广：需求-实现追踪、招聘-入职追踪、政策-执行追踪，都应显式记录「声明了但未发生」的负样本。
启发式要与独立通道配对发布。证据：co-change 启发式明确标注局限，追溯索引覆盖其盲区，两者差异本身被列为研究问题。推广：任何依赖启发式标注的数据集，交付独立第二通道比单通道加免责声明更有价值。
不预过滤，但交付过滤工具。证据：语料混有模板/教程，作者交 fork 旗标、内容哈希、占位符标记并要求使用者报告过滤规则。推广：开放数据集治理的通用模式——把「画线的权力」连同画线工具一起交给使用者，而非替社区做主观裁剪。
SPECMINE 不提出算法、不给出因果结论——它做的是更基础的事：为一个刚刚诞生的工程实践建立可研究的物质基础。当「写 spec」逐渐取代「写代码」成为人类开发者的主要动作，理解 spec 的解剖学、演化与命运，就是理解 AI 时代的软件工程本身。