awesome-python 的条目治理规则：CLAUDE.md 如何约束 AI Agent 添加与删除条目

本文以 awesome-python 仓库根目录下的 CLAUDE.md 为骨架，完整拆解这份"面向 AI 编码代理的治理指南"：它如何声明 README.md 是唯一的条目真源、如何在添加或删除任何一个条目时强制套用 CONTRIBUTING.md 的准入与淘汰规则，以及如何要求"每一个保留/删除理由都必须对照当前在线数据复核"。读完本篇，你将掌握该项目"意见化精选（opinionated curation）"的底层规则，理解从 PR 提交、逐条核验到按小节审计、再到赞助与选品彻底隔离的完整工作流，并能把同样的治理纪律迁移到你自己的精选类项目中。

一句话定位：README 是唯一真源，website 只是渲染层

CLAUDE.md 开头先给项目下了一个一句话定义——"An opinionated guide to the best Python frameworks, libraries, tools, and resources"（一份关于最佳 Python 框架、库、工具与资源的意见化指南），随即锁定全仓最重要的架构事实：

README.md is the single source of content truth; website/ renders it into the static site.

这句话确立了两层结构：内容真源在 README.md，而 website/ 目录只负责把它渲染成静态站点。这意味着所有条目的增删改都发生在 Markdown 里，而不是在数据库或前端代码里；前端只是 README 的"投影"。这一点在仓库里处处得到印证：

• Makefile 的 build 目标直接执行 uv run python website/build.py，输入就是 README.md 与 website/templates、website/static、website/data；
• Makefile 的 preview 目标用 watchfiles 监听 README.md website/templates website/static website/data 的变化再重新构建，再次确认 README 是内容入口；
• website/readme_parser.py 负责把 README 里的条目解析成站点数据，测试用例见 website/tests/test_readme_parser.py。

理解了"README 即真源"这条主线，后面所有规则都是在回答同一个问题：当一个 AI Agent 要去改这份 Markdown 时，它必须遵守哪些纪律？ 这正是 CLAUDE.md 的主体。

核心约束：任何增删条目都必须套用 CONTRIBUTING 的准入规则

CLAUDE.md 的 "Entry Rules" 一节第一句就是强制项：

CONTRIBUTING.md holds the admission rules, quality requirements, rejection rules, entry format, and ordering. Apply it whenever adding or removing an entry — direct commits included, not only PR reviews.

注意后半句"direct commits included, not only PR reviews"（直推提交也算，不只是 PR 评审）：它把治理纪律从"PR 审核流程"扩展到了任何一次直接提交。换言之，无论是走 PR 还是直接 push，只要动了条目，就得按 CONTRIBUTING.md 来。

CONTRIBUTING.md 给出这套规则的完整内容，CLAUDE.md 依赖它作为判定标准。理解 CLAUDE.md 的"治理"含义，必须先看到它引用的规则全貌：

质量门槛（全部满足才能进入评审），来自 CONTRIBUTING.md 的 "Quality Requirements"：

1. Serves Python Developers：服务于 Python 开发者即可，实现语言与打包方式无关——uv 和 ty 用 Rust 写、Agent skill pack 是 Markdown，都算数；没人用于 Python 工作的纯 Python 项目则不行。
2. Active：最近 12 个月内有提交。
3. Stable：生产可用，非 alpha/beta/experimental。
4. Documented：有清晰、带示例的 README。
5. Established：仓库至少 1 个月。

每个 Use Case 的容量上限（Cap），来自 CONTRIBUTING.md 与 CONTEXT.md：每个 Use Case 最多 3 个 Obvious Choice（显而易见之选）+ 2 个 Challenger（挑战者），硬上限 5 条。这是"先定性、后数字兜底"的天花板，而不是地板——一个刚建好的 Use Case 甚至可以只放 1 条。

Displacement（顶替）是唯一进入满员 Use Case 的路径：PR 必须点名要替换掉哪个已有条目，并论证新者干那件事干得更好——一进一出。

这套规则在 docs/adr/0001-shortlist-not-catalog.md 里有完整的决策背景：该 ADR 记录了项目在 2026 年中期把 576 条/75 节的"目录（catalog）"重定位成"精选短名单（shortlist）"的原因与后果，解释了为什么"多数未来的 PR 会因『满员』而非『不好』被拒"。

关键结论：CLAUDE.md 本身不复述这些规则，而是指路 + 强制执行。它把"具体判定标准"外置到 CONTRIBUTING.md，把"为什么这么定"外置到 docs/adr/0001-shortlist-not-catalog.md，自己只保留"必须执行 + 执行到什么程度"的治理约束。这是精选类项目把"标准"和"流程"解耦的典型写法。

证据纪律：每个保留/删除理由都必须对照"当前在线数据"核验

这是 CLAUDE.md 里信息密度最高的一条，也是它区别于普通贡献指南的地方。原文要求：

Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs.

也就是说，任何一次"保留"或"删除"的决定，理由都不能拍脑袋，而要对照决策时刻的在线数据逐条核对，核验对象包括：

• 下载量（PyPI download counts）；
• 仓库活跃度与是否已归档（repo activity and archived status）；
• PyPI 元数据（PyPI metadata）；
• 项目文档（project docs）。

紧接着是分层判定的证据要求：

Judging tiers — obvious choice vs challenger — also requires WebSearch evidence (adoption trajectory, community sentiment), not download counts alone.

判断一个条目属于"显而易见之选"还是"挑战者"这一层，光看下载量不够，还要有 WebSearch 证据——采用趋势（adoption trajectory）、社区口碑（community sentiment）等。

最后两句是全文最关键的"反幻觉"护栏：

Training-data recollections are not evidence; label anything unverifiable as a judgment call.

"训练数据里的记忆不算证据；任何无法核实的判断都要标注为主观判断（judgment call）。" 这条规则直指 AI Agent 的固有缺陷——模型倾向于凭训练语料"想当然"地断言一个项目"很火/很老"。CLAUDE.md 明确禁止把这种回忆当作依据，强制要求：查不到就承认查不到，并如实标注为主观判断。

这条"证据纪律"在仓库里有对应的数据获取工具支撑：

• website/fetch_pypi_downloads_via_clickpy.py、website/fetch_pypi_downloads_via_bigquery.py、website/fetch_pypi_downloads_via_pepy.py 提供多种 PyPI 下载量来源；
• website/fetch_github_stars.py 拉取 GitHub star 数与 owner 信息，其模块 docstring 明确写道：输出文件 data/github_stars.json 被 gitignore，CI 在部署时才拉取，本地运行只用于预览——数据永不提交，并且"从 README 删掉的条目只会留下无害的孤儿键"。

这恰好印证了 CLAUDE.md 的"对照当前数据核验"精神：数据是临时的、按决策时点取的，而不是被固化进仓库的静态快照。结合 CONTEXT.md 对 "Obvious Choice" 的定义（认证主要依据 PyPI 下载量而非 GitHub star，且判断会覆盖 CI 刷量、模型权重非 pip 安装等信号的已知失效模式），可见"证据纪律"是把"用什么数据、何时取、取不到怎么办"三件事都钉死在规则里。

提交粒度规则：一个条目一个 commit，以及三个明确例外

CLAUDE.md 的第三条规则约束提交粒度（commit granularity），原文是：

One entry per commit when adding or deleting entries. Exceptions: a prune sweep is one commit per section, its body listing each removal with its reason; format, wording, or categorization changes may be bundled. Cross-section re-homes ride the originating audit's commit (both sides of the move in one diff).

翻译过来是一条"一进一出、一次一条"的默认规则加三个例外：

1. 默认：新增或删除条目，一次 commit 只动一个条目。
2. 例外一——清扫式裁剪（prune sweep）：一次 commit 对应一个 section（小节），但必须在该 commit 的正文里逐条列出每一个被删除条目及其理由。
3. 例外二——可批量：格式、措辞、分类（categorization）这类非内容性改动可以合并进同一个 commit。
4. 例外三——跨小节搬家：条目在不同小节之间移动（re-home）时，搭原始那次审计（audit）的 commit，把"搬走的一边"和"搬入的一边"放进同一个 diff。

这条规则的设计意图很明确：让 git 历史本身成为可追溯的审计档案。每一个删除都能在自己的 commit 里找到理由，每一次搬家都能在单个 diff 里看到两端。

这与 docs/audit-logs.md 开篇的表述完全呼应：

Every entry gets re-verified against live data, and every removal lands in a commit whose body carries the reason. Git history is the archive.

（每个条目都会对照实时数据重新核验，每个删除都落在一个"正文携带理由"的 commit 里。Git 历史就是档案。）

进一步看，docs/audit-logs.md 还专门设了一个 "Overrides" 登记区，记录 CONTRIBUTING.md 允许维护者"针对某个条目或某个 Use Case 突破任何限制"的例外决定，并列出真实的命名例外（display name 与规范 PyPI 包名不一致，例如 pytorch 展示为 torch、django-rest-framework 展示为 djangorestframework、jinja 展示为 Jinja2）。这些命名例外在仓库里也有落地：website/data/pypi_name_overrides.json 正是站点渲染时用于纠正"展示名 ≠ 包名"的数据文件。

从源码结构看，这套"提交粒度 + 理由入 commit + git 历史即档案 + 例外需登记"的组合，构成了该项目可审计性的完整闭环：CLAUDE.md 定粒度规则，audit-logs 登记例外，pypi_name_overrides.json 落地命名修正。

范围边界：Resources 小节不是项目条目，website 从不解析它

CLAUDE.md 第四条划定了审计与解析的范围边界：

Resources sections are not project entries: out of audit scope, and the website never parses them.

含义有两层：

• 治理层面：Resources 类小节（如 Newsletters、Podcasts、Websites）不属于"项目条目"，因此不在审计范围内——审计流程（Audit）不对它们做保留/删除判定；
• 实现层面：website 的解析器从不解析这些小节，它们不会进入站点数据。

这与 docs/adr/0001-shortlist-not-catalog.md 的决策一致：该 ADR 在"决定"一节明确写道 "Resources sections (Newsletters, Podcasts, Websites) are out of scope for now"，并在"后果"里提到被删条目"直接删除——git history 是档案"。

把这条边界理解清楚很重要：它告诉 AI Agent"你改 README.md 时，Resources 小节既不用跑证据核验，也不会被 website/readme_parser.py 读到"。从源码结构看，这是一个"内容真源"里被刻意排除在渲染管线之外的子集——用一份 README 同时承载"被渲染的项目目录"和"不被渲染的资源链接"两种内容，并用解析器的行为来划清这条线。

赞助与选品彻底隔离

CLAUDE.md 最后一条是独立性护栏：

Sponsor placement never influences which projects get listed — see SPONSORSHIP.md.

赞助展示绝不影响哪些项目被收录。这条规则把"商业化"与"编辑判断"做了硬隔离，SPONSORSHIP.md 在 "Editorial Independence" 一节重申：赞助只是 README 头部的 logo/链接位，不影响收录——收录按常规 CONTRIBUTING.md 流程、凭能力（merit）筛选。

值得对照的是仓库里另有一份 AGENTS.md，它和 CLAUDE.md 内容高度一致（同一套 Entry Rules），但多了一句补充："website/templates/sponsorship.html separately defines the sponsorship content on the published website page"，即 website/templates/sponsorship.html 单独定义了发布站点的赞助内容页。两份文件共同强化了同一条治理底线：赞助是独立的展示面（模板、头部位），选品是独立的内容面（README 条目），二者互不渗透。

把这套纪律迁移到你自己的精选项目

CLAUDE.md 的价值不在于它有多长，而在于它把"精选类项目最容易失控的几个点"都写成了可执行的约束。梳理成一张可复用的清单：

治理关注点	CLAUDE.md 的约束	仓库里的落点
内容真源唯一	README 是 single source of truth，website 只渲染	README.md、Makefile、website/readme_parser.py
判定标准外置	增删必须套用 CONTRIBUTING 的准入/淘汰/格式/排序规则	CONTRIBUTING.md、CONTEXT.md
证据可核验	每个保留/删除理由对照当前在线数据（下载、活跃度、归档、PyPI、文档）	website/fetch_pypi_downloads_via_clickpy.py 等
反 AI 幻觉	训练记忆不算证据；查不到要标注为主观判断；分层判定需 WebSearch	见 CLAUDE.md "Entry Rules"
提交可审计	一个条目一个 commit；清扫式裁剪按 section 一 commit 且正文列理由；跨小节搬家同 diff	docs/audit-logs.md
范围边界	Resources 小节不在审计范围，website 从不解析	docs/adr/0001-shortlist-not-catalog.md
赞助隔离	赞助永不影响收录	SPONSORSHIP.md、AGENTS.md

迁移到自己项目时，可以直接借用这套"三层解耦"：把判定标准写进 CONTRIBUTING、把决策背景写进 ADR、把例外与命名修正登记进 audit log，再用一个 README 作为唯一内容真源、用解析器行为划清"被渲染 / 不被渲染"的边界。这样无论后续由人工还是 AI Agent 维护，每一次增删都有据可查、有理由可追溯，git 历史本身就成为项目的档案库。