30K Corpus: AI Instruction Quality Dataset

这是一个包含28,721个GitHub仓库的数据集，用于分析五种编码代理（Claude、Codex、Copilot、Cursor和Gemini）的AI指令质量。数据集包括每个项目的配置代理、星标数、语言、许可证和主题等信息，以及支持文章中每个表格的汇总统计数据和样本分类。

This is a dataset containing 28,721 GitHub repositories, designed to analyze the AI instruction quality of five coding agents: Claude, Codex, Copilot, Cursor, and Gemini. The dataset includes information such as the configured agent, star count, programming language, license, and topics for each project, as well as summary statistics and sample classifications that support each table in the accompanying article.

原始信息汇总

30K Corpus: AI指令质量数据集概述

数据集基本信息

• 数据集名称：30K Corpus: AI Instruction Quality Dataset
• 关联研究："The State of AI Instruction Quality"
• 数据来源：通过Reporails CLI提供的28,721个包含五种编码代理指令文件的GitHub仓库语料库分析。
• 许可证：CC-BY-4.0

数据集内容与文件

文件	记录数	描述
repos.jsonl	28,721	每个项目的数据：配置的代理、星标数、语言、许可证、主题
stats_public.json	1	支撑文章中每个表格的聚合统计数据
validation_key.csv	2,814	样本分类：原子文本、工具标签、源代码位置

数据字典

repos.jsonl

每行是一个JSON对象，包含以下字段：

• full_name (string): 所有者/项目
• canonical_agents (string[]): 去重后检测到的代理：claude、codex、copilot、cursor、gemini
• stars (int): 收集时的GitHub星标数
• primary_language (string?): GitHub检测到的主要语言
• license (string?): SPDX许可证标识符
• archived (bool): 仓库是否已归档
• topics (string[]): GitHub主题

stats_public.json

按部分组织的聚合统计数据：

• headline: 总项目数、文件数、原子数、带电原子数
• agent_distribution: 每个代理的项目数、多代理直方图、共现对
• band_distribution: 每个代理的合规性等级分布（低/中/高）
• specificity: 命名原子与抽象原子计数，每个代理的细分
• config_types: 按配置类型（基础/规则/技能/代理）的文件数和特异性，每个代理的细分
• content_length: 每个配置类型的中位原子数、指令数、令牌数
• descriptive: 文件大小、指令比率、指令长度、顶部文件名
• skills_quality: 前30项技能的采用率和特异性（命名%）
• subagents_quality: 前15个子代理角色的每个角色特异性
• top_rules: 整个语料库中最常见的诊断类别
• multi_agent_delta: 多代理项目数，每个代理的赢/输计数
• file_count_quality: 按指令文件数的质量等级分布

validation_key.csv

来自语料库的样本分类，涵盖星标层级（前100名、中层级、长尾仓库）。每行显示工具的分类以及用于检查的源文本。

• id (int): 样本标识符
• project (string): 仓库名称
• agent (string): 代理配置类型
• file_path (string): 仓库内的路径
• line (int): 源文件中的行号
• text (string): 被分类的指令文本
• tool_charge (string): 工具分类：CONSTRAINT、DIRECTIVE、IMPERATIVE 或 NEUTRAL
• tool_modality (string): 检测方法：direct、imperative 或 none
• tool_specificity (string): 命名（引用特定构造）或抽象（类别级别）

采样与方法论

收集

1. 来源：GitHub REST API搜索，查询包含五种编码代理指令文件的仓库。
2. 去重：每个项目的代理检测重叠已解决——匹配多个代理模式的文件被分配给最具体的匹配项。
3. 时间窗口：收集于2026年3月至4月。
4. 总计：经过去重和过滤后，获得28,721个具有可分析指令内容的项目。

分析

每个指令文件均由Reporails内置分类器处理：

• 解析：Markdown到原子单元（一个语义块 = 一个原子）。
• 电荷分类：三阶段确定性流水线（否定检测、情态助动词检测、句法依存解析）。未使用LLM。第一个明确匹配项胜出。
• 特异性：二元判断——指令是否命名了特定构造（工具、文件、命令、标志）或保持在类别级别？
• 文件分类：基础配置、规则、技能或子代理——基于每个代理的文件路径约定。

已知偏差

• 仅限GitHub：不包含GitLab、Bitbucket或私有仓库。
• 英语偏向：GitHub API搜索偏向英语仓库。
• 仅限公开：不包含企业和私有配置。
• 活动偏差：仓库必须有足够的活动才能出现在GitHub搜索结果中。
• 无流行度加权：一个10星标的业余项目与一个5万星标的生产仓库权重相同。
• 快照：指令实践正在迅速变化。这些数字描述了收集时的生态系统状态。

数据集中不包含的内容

• 指令文件内容：指令文件的实际文本属于仓库所有者。本数据集仅包含结构元数据和聚合统计数据。
• 持续质量分数：每个文件和每个项目的质量分数是使用专有校准常数在服务器端计算的，不包含在内。合规性等级包含在内，因为它们不暴露校准值。
• 嵌入向量：不包含指令内容的向量表示。

搜集汇总

数据集介绍

构建方式

在人工智能辅助编程工具日益普及的背景下，30K Corpus数据集通过系统性的方法构建而成。研究者利用GitHub REST API进行搜索，专门收集了包含五种主流编码智能体指令文件的公开仓库，时间窗口设定在2026年3月至4月。通过严格的去重与过滤流程，最终纳入了28,721个具有可分析指令内容的项目。每个指令文件均经由Reporails CLI内置的分类器处理，该工具采用确定性的三阶段流水线进行解析与分类，确保了分析过程的可复现性与透明度。

特点

该数据集的核心特征在于其多维度、结构化的元数据表征。它不仅记录了每个仓库的基本信息，如配置的智能体类型、星标数量、主要编程语言和主题标签，更通过聚合统计深入揭示了指令质量的多项指标。数据集涵盖了指令的具体性分析、配置类型分布、内容长度统计以及技能采纳情况等丰富维度，并提供了经过人工验证的分类样本以供校准。这些特征共同构成了一幅关于当前AI指令编写实践生态的精细图谱。

使用方法

研究人员可利用该数据集对AI指令质量进行深入的实证分析。通过解析`repos.jsonl`文件，可以探索不同智能体的采用模式与共存情况；查阅`stats_public.json`中的聚合统计数据，能够验证关于指令特异性、配置复杂性等研究发现；而`validation_key.csv`则为分类方法的可靠性提供了检验基准。数据集附带的验证脚本使得所有文章中的主张均可被独立复现，用户亦可使用开源的Reporails CLI工具对任意子集仓库进行本地分析，实现研究过程的完全透明与可验证。

背景与挑战

背景概述

随着人工智能编码助手在软件开发领域的广泛应用，针对这些智能体的指令质量评估逐渐成为提升人机协作效率的关键研究议题。30K Corpus: AI Instruction Quality Dataset 由 Reporails 团队于2026年3月至4月期间构建，旨在系统分析GitHub平台上28,721个包含五种主流编码助手（如Claude、Codex、Copilot等）配置文件的代码仓库。该数据集通过解析指令文件的结构化元数据与聚合统计，深入探究了AI指令的分布特征、配置模式及质量差异，为理解当前开发者如何指导AI编码行为提供了首个大规模实证基准，对优化智能体指令工程与评估框架具有重要参考价值。

当前挑战

该数据集致力于解决AI指令质量评估领域的核心挑战，即如何在大规模开源代码库中自动化、标准化地量化与比较不同编码助手的指令配置效果。构建过程中的挑战主要体现在数据采集与处理层面：首先，GitHub平台的数据覆盖存在局限，如仅包含公开仓库且以英语项目为主，可能导致样本代表性偏差；其次，指令文件的异构性（如多样化的命名规范与格式）增加了自动化解析与分类的复杂度；此外，指令质量的动态演变特性使得静态快照数据难以持续反映实践趋势，而依赖确定性规则而非大语言模型的分类方法虽保障了可复现性，但可能无法完全捕捉语义层面的细微差别。

常用场景

经典使用场景

在人工智能辅助编程领域，30K Corpus数据集为研究者提供了大规模、结构化的指令质量分析基础。该数据集通过解析近三万份GitHub仓库中的指令文件，系统性地揭示了Claude、Codex、Copilot、Cursor和Gemini等主流编码助手的配置模式与指令特征。经典使用场景包括对指令文件的原子化解析、电荷分类及特异性检测，从而支撑对AI指令编写实践的量化评估与趋势洞察。

实际应用

在实际应用层面，该数据集为AI工具开发者提供了生态洞察，助力优化默认指令模板与用户引导策略。企业团队可参照数据集中的合规性分布与多代理配置模式，制定内部AI编码助手部署规范。教育机构也能基于指令特异性分析，设计更具针对性的提示工程培训课程，提升开发者与AI协作的实践能力。

衍生相关工作

围绕该数据集衍生的经典工作主要集中在智能体配置优化与指令质量评估框架构建。例如基于多代理协同模式的分析研究，揭示了工具组合使用的效率增益规律；另有学者利用指令特异性指标开发了自动化质量检测工具，实现了对指令清晰度与可操作性的量化评分。这些工作共同推动了AI指令工程向系统化、可复现的研究方向发展。