v0.5 — 禁令与构建测试并列第一 + 100 份人工核对实测准确率（ruleset_v0.1.8）

v0.5 — 禁令与构建测试并列第一；100 份人工核对落地（ruleset_v0.1.8）

数据集 v0.5（规则集 ruleset_v0.1.8）。行数与字段都不变（558 行 × 30 列），
但可用样本 511 → 516、多类判定规则都动过——所以不要把 v0.4 与 v0.5 的数字放进同一张表。

改了三处会动数字的地方

1. 禁令补上正文通式：do not / don't / must not / must never（排除
   do not need / hesitate / worry / forget 四种非禁令句式）。全库 2632 处命中、
   102 份文件因此多拿到 boundaries。此前正文通道只认 never commit /
   do not commit / must not 与中文模式——最常见的英文禁令写法整类漏掉。
2. 代码块里的 # 注释 不再当成标题：# 3. Build、# Run tests 是 shell 注释，
   此前被当成章节标题。129/558 份文件受影响，diffblue/cbmc 的章节数 146 → 92。
3. is_pointer 加反证闸：只要文件里有它自己的规则/约束/可执行命令，就不是"纯指针"。
   5 份"短但写了规则"的文件收回统计口径，指针 7 → 2，分母 511 → 516。

覆盖率（分母 516）

类别	v0.4（511）	v0.5（516）	差
boundaries 禁令	65.6%	85.7%（442）	+20.1pp
build_test 构建测试	85.9%	82.8%（427）	−3.1pp
workflow 流程	65.9%	67.1%（346）	+1.2
structure 架构	59.7%	59.1%（305）	−0.6
style 风格	56.8%	54.5%（281）	−2.3
environment 环境	44.4%	45.0%（232）	+0.6
overview 概览	34.8%	32.2%（166）	−2.6
agent_meta AI 行为规定	29.5%	25.8%（133）	−3.7
gotchas 坑	14.1%	13.6%（70）	−0.5

头条：两类并列第一。 boundaries 85.7% 与 build_test 82.8% 相差 2.9pp，
小于禁令通式约 3% 的已知假阳性幅度（LIMITATIONS.md §13），
所以说法是并列第一，不是"禁令压倒了构建测试"。

boundaries 必须报两个口径（它们回答不同问题）：

问法	定义	覆盖
有没有专门写禁令的章节？	章节标题命中 Not Allowed / Never commit / 禁止 …	45.2%（233 份）
任意一处出现禁令语句？	加上正文通式	85.7%（442 份）

100 份人工核对：第一次有实测准确率

组	份数	标注者	precision	recall
A 主样本（唯一能代表全体）	55	本智能体盲判	90%	75%
B 中文普查	26	用户独立盲判	80%	79%
D 稀有类加成	9	本智能体盲判	92%	84%

• 错标的量级已经压住（80–92%），漏标才是主要短板：gotchas recall 38%、
  overview 41%、agent_meta 55%（共同点：内容散在正文、没有专门章节）。
• 中文组暴露反方向的问题：build_test precision 只有 61%（"运行 / 命令 / 启动"
  这类动词在中文散文里被当成构建证据）。
• ⚠️ 这是 in-sample 上界：这 100 份正是驱动本轮规则改动的样本。
  真正的留出集估计需要新一轮未参与改规则的样本。
• 详见 work/audit/v0.5-human-vs-rule.md 与 LIMITATIONS.md §16。

一处自我更正：59.9% → 45.2%

v0.5 的文档初稿里写了"其中 59.9%（309 份） 是专门开了一节写禁令"。那个数字是错的：
写进文档时没有记录定义，事后用三种可定义的口径都复算不出来（标题通道 233、
标题∪强模式 302、全文兜底 315）。按"专门开一节"的字面定义（标题通道）重报为
45.2%（233/516），并把这个口径的定义写进表格。头条数字 85.7% 不受影响，
三站文案没有引用过这个数。全过程与教训：LIMITATIONS.md §17。

复算

pip install -e .                    # 或 pip install git+https://github.com/janzong/agent-charters
agent-charters stats                # 应打印 v0.5 / 516 份、boundaries 85.7% / build_test 82.8%
.venv/bin/python work/audit/boundaries_channels.py      # boundaries 三个口径
.venv/bin/python work/audit/human_vs_rule_v0.5.py       # 100 份核对逐类表
python work/dataset_diff.py --old data/processed/agent-charters-v0.4.parquet \
                            --new data/processed/agent-charters-v0.5.parquet --out /tmp/diff.md

测试：138 passed（新增围栏语言标记、块 3a/3b 的参数化锁、is_pointer 反证闸等）。

资产

• agent-charters-v0.5.parquet —— 主数据集（558 行 × 30 列，zstd）
• agent_charters_v0.5.jsonl —— 同内容的行式版
• SHA256SUMS —— 含 v0.2–v0.5 全部资产的校验和（旧资产继续保留，不静默替换）

v0.4 没有单独发 Release；v0.4 的数字请继续按 v0.4 引用，v0.5 起对外一律用
85.7% / 82.8%（并列第一）。改动清单：work/audit/v0.1.8-changelist.md。

v0.3 — 修正标题通道子串误命中（build_test 87.9% → 85.7%）

v0.3 — 修正标题通道的子串误命中（ruleset_v0.1.3）

数据集 v0.3（规则集 ruleset_v0.1.3）。字段与行数都不变（558 行 × 30 列），
只有判定规则变了——所以不要把 v0.2 与 v0.3 的数字放进同一张表。

修了什么

taxonomy.py 的标题通道原是 if k in heading.lower()——纯子串，没有词边界：

• ci 命中 De**ci**sions / Prin**ci**ples（一批没有构建内容的章节被算成"构建测试"）
• script 命中 Type**Script**、build 命中 allow**Build**s、review 命中 p**review**
• 另有一类不是子串、但同样误命中：裸词 make 是普通英文动词，Make changes 也算"构建"

修法（两处，都不动语料、不动九类定义）：

1. 词首匹配：命中点必须落在词首，连字符算词边界（commit 仍命中 Pre-Commit）。
   词首前缀命中保留（convention→Conventions、boundar→Boundary、test→Testing）。
2. build_test 删掉裸词 make，只留 makefile 与具体目标（make build / make dev …）。
   依据：511 份里 12 个标题命中裸词，逐条看 7 份是散文，只有 5 份真是构建工具。

影响（511 份可用样本）

类别	v0.2	v0.3	差
构建测试	87.9% (449)	85.7% (438)	−11 份
流程	66.1% (338)	65.9% (337)	−1
环境	44.8% (229)	44.4% (227)	−2
AI行为	36.8% (188)	36.4% (186)	−2
架构	59.9% (306)	59.7% (305)	−1
风格	56.9% (291)	56.8% (290)	−1
禁令 / 概览 / 坑	—	不变	0

• 23 处 (文件, 类别) 组合的标签只靠误命中撑着 → 18 处实际掉标签，无一例新增
• 其余 5 处被正文规则或强模式通道兜住：标签仍成立，只是证据列变干净
  （"证据错了"和"标签错了"是两件事，本项目分开判）

方向与排序完全不变：build_test 仍是第一名、仍明显领先第二名（65.9%）。

一处自我更正：84.7% → 85.7%

09-12 我把 build_test 的修正值说成 84.7%（433/511）——那个数是错的，
正确值是 85.7%（438/511）。

错因：我拿审计脚本打印的"误命中组合数（构建测试 16 处）"直接相减，
当成"会掉标签的文件数"。实际掉标签的是 11 份（另 5 处被兜底通道救回）。
推算出来的幅度不能直接进对外文案——教训与全过程写在 LIMITATIONS.md §11.4。

其他修正

• extract_report.md 的类别分布原先按 518 份（实质）算，与 category_coverage() 的
  511 份口径差 7 份；现统一
• CLI stats / compare / brief 的覆盖率由整数改为一位小数：
  整数取整会把 85.7% 印成 85%，与对外文案对不上
• work/substring_audit.py 改为对出错的那版快照跑，并同时输出
  "误命中组合数"与"实际掉标签数"（两者混用正是上面那次推算错误的根源）
• 新增 work/dataset_diff.py：任意两版数据集逐行比差集

复算

pip install -e .            # 或 pip install git+https://github.com/janzong/agent-charters
agent-charters stats        # 应打印 build_test 85.7%
python work/dataset_diff.py --old data/processed/agent-charters-v0.2.parquet \
                            --new data/processed/agent-charters-v0.3.parquet --out /tmp/diff.md

测试：51 passed + 1 xfailed（新增"词中命中不许打标签／词首前缀必须打标签"两组参数化锁）。

资产

• agent-charters-v0.3.parquet —— 主数据集（558 行 × 30 列，zstd）
• agent_charters_v0.3.jsonl —— 同内容的行式版
• SHA256SUMS —— 含 v0.2 与 v0.3 两份的校验和（v0.2 资产继续保留，不静默替换）

v0.2 的数字请继续按 v0.2 引用；v0.3 起对外一律用 85.7%。

v0.2 — 外部引用入库 / is_pointer 口径收紧

v0.2 — 外部引用入库 / is_pointer 口径收紧

数据集 v0.2（规则集 ruleset_v0.1.2，工具 0.3.1）。

⚠️ 与 v0.1.1 不可直接比较

这一版改了 is_pointer 的判定口径，可统计的实质文件 507 → 511，
九类覆盖率随之变动 ≤1 个百分点。请不要把 v0.1.1 与 v0.2 的数字放在同一张表里比。

• 旧口径：提到 ≥2 个 .md 文件名且体积 <2000B
• 新口径：薄（去链接去路径后 <400B）且在指向 或 作者自陈"本文件只是路由"

逐行用 ruleset_version 区分（ruleset_v0.1.1 / ruleset_v0.1.2）。详见 LIMITATIONS.md §10。

新增：4 个"知识放在哪里"的结构字段（26 → 30 字段）

九类按内容分类，量不出"我指向别处"。这一版把它补进数据集，可自行复算：

字段	含义	实测
imperative_route	祈使式转引（"read / 详见 X.md"）	49%
hard_route	指向知识库或规则目录（memories/、MEMORY.md、pitfalls、.cursor/rules…）	15%
routes_outward	上面两者任一	54%
ref_targets	指向几个路径	—

含义：近一半的章程是入口，不是全集——"一份 AGENTS.md 承载全部规约"这个假设，
对大多数样本不成立。

其他

• structure 标题词表补齐"分工 / 职责 / 归属 / ownership"类：33 个这类章节里 9 个原本完全无标签（58% → 59%）
• brief 的两个外部引用基准率改为从随包语料库实时计算（此前硬编码）
• 更正一处旧账：FINDINGS 16 表格原写"祈使转引 235 份 / 46%"，只算了英文正则、漏了中文 12 份；
  正确是 247/507 = 49%（标题里的 49% 一直是对的）
• 测试 34 项（含"数据集可由 raw 重放""跨哈希种子字节一致""发布校验和"三道刹车）

资产

• agent-charters-v0.2.parquet —— 主数据集（558 行 × 30 列，zstd）
• agent_charters_v0.2.jsonl —— 同内容的行式版

校验和见仓库 data/processed/SHA256SUMS。不含原文全文，只含衍生标注与统计特征。

v0.1.1 — 中文漏标修复 / 规则版数据集

数据集 v0.1.1

修订版数据集（分类法仍是 v0.1，但判定规则已升级，见下）。
若你用过 v0.1，请重新下载——覆盖率数字不可直接与 v0.1 比较。

改了什么

1. 中文文档不再被漏标（重要）

v0.1 的分类关键词以英文为主，中文章程常常"有内容但标题不含英文关键词"，
被判定成"什么都没有"。给出错误结论的工具比没有工具更糟，因此新增
强模式通道（总是运行，独立于标题通道），只收跨语言的高精确信号：

pytest / npm run build / ./gradlew / git pull … git push /
Conventional Commits / 🚫 / 会话中毒 踩坑 风控 等。

• 无任何标签的实质文件：15 份 → 7 份（2.1% → 1.4%）

2. 标题关键词扩充（中英同义词）

依据是"语料库里 2885 种标题从未被任何规则命中"，逐词统计影响面后再加：
技术栈 / 项目定位 / 模块 / 规则 / 准则 / 要求 / 调试 /
verification / validation / key files / where to look /
contributing / changelog / code quality / type hints / limitation …

3. 修两个假阳性（已写成回归测试）

• make \w+ 会命中 "make sure"
• gradle \w+ 会命中 "Gradle 9"（版本号）
• 另去掉 gotchas 的"失败原因/注意事项"——记录失败原因 ≠ 坑

数字变化（507 份实质文件）

类别	v0.1	v0.1.1
build_test	79%	87%
workflow	57%	66%
boundaries	61%	66%
structure	57%	58%
style	56%	57%
environment	45%	45%
agent_meta	36%	36%
overview	33%	34%
gotchas	13%	14%
平均标签数	4.4	4.7

新增字段

• retrieved_at —— 采集日期（与 commit_date＝内容时间区分开），判据 2 的可追溯要求
• strong_patterns —— 是否启用强模式通道（v0.1.1 全行为 true）
• ruleset_version —— 判定规则版本（taxonomy_version 是九类定义版本）。
  规则变了而定义没变时靠它机器校验可比性

资产

• agent-charters-v0.1.parquet —— 558 行 × 26 列（zstd）
• agent_charters_v0.1.jsonl —— 同上，逐行 JSON
• SHA256SUMS —— 校验和

工具

仓库内已含可复用包与命令行工具：

pip install -e .
agent-charters stats                      # 全局分布
agent-charters compare path/to/AGENTS.md  # 你的章程 vs 语料库基线
agent-charters show gotchas --limit 8     # 看某类别的真实写法

已知局限（务必先读）

分类由规则完成，未经逐份人工校验；v0.1.1 这轮改动只有抽验，
证据强度低于人工核对。中文样本仅 5%，中文章程上的结论请当作下界。
详见仓库 LIMITATIONS.md。

---

资产更新说明（同日，未发布前修正，0 下载）

初版资产在自查"能否复现"时发现两个数据格式问题，已重新生成并覆盖：

1. category_counts 改为定长稠密：九类全部在场、缺席为 0、顺序固定。
   旧写法（稀疏 dict）经 parquet 会被展开成 struct，缺席类别变成 None/NaN
   ——下游 d["gotchas"] >= 1 会报错或静默算错。
2. 产物确定性：原先 category_counts 的键顺序依赖 PYTHONHASHSEED，
   同一份数据两次生成字节不同、校验和不可复现。现已固定，
   并在测试中用两种哈希种子重跑比对字节。

数据内容（每一行的标注结果）未变，只是表示方式与字节稳定性。
若你在覆盖前已下载：请重新下载，并使用新的 SHA256SUMS 校验。

v0.1 — AGENTS.md 结构化语料库（558 份）

⚠️ 已被 v0.1.1 取代，建议使用新版。
v0.1.1 修复了中文文档被整体漏标的问题，并补了 retrieved_at / ruleset_version 字段。
两版覆盖率数字不可直接比较（如 build_test 79% → 87%），原因见新版说明。

---

558 份 AGENTS.md（来自 558 个公开仓库）的结构化标注数据集。

这是第一个完整闭环版本：抓取 → 抽取 → 打包 → 发布。

文件

文件	说明
agent-charters-v0.1.parquet	主数据集，558 行 × 23 列（推荐）
agent_charters_v0.1.jsonl	同上，JSONL 格式

快速开始

import pandas as pd
df = pd.read_parquet("agent-charters-v0.1.parquet")
df[df["is_substantive"] & ~df["is_pointer"]]

关键数字

• 558 份抓取，518 份实质内容，5.5 MB
• 9 类多标签，平均 4.4 个标签/份
• 覆盖最高的类别：build_test（79%）；最低：gotchas（12%）
• 内容模式：指令性 72% / 陈述性 15% / 混合 13%
• 中文文档仅 5%
• 70% 的仓库使用 MIT / Apache-2.0

请先读局限

抽样 12 份人工核对：准确 9 / 漏标 3 / 错标 0（精确率高、召回率偏低）。
真分类失败率 2.1%。样本偏向 AI/agent 话题仓库，中文样本仅 5%。

完整局限见仓库的 LIMITATIONS.md，请在使用前阅读。

版权

本数据集不含任何原文全文，仅含衍生标注与统计特征。
被采集文件的版权归各仓库原作者。