开源项目的“规范”到底写在哪:治理文件清单、GitHub 的硬编码路径与 AGENTS.md 的来历
开源项目的“规范”到底写在哪:治理文件清单、GitHub 的硬编码路径与 AGENTS.md 的来历
核心背景:起因是要做一个高校 Wiki 目录站。这个站只登记各高校学生自建 Wiki 的名称与网址,不复制任何正文。项目是我自己发起的,没有事先征询过各个站点的负责人,所以最大的风险不是技术,而是“被人挑出毛病”。为了对冲这个风险,我需要一整套项目规范,但真动手时才发现一个更基础的问题:所谓“规范”到底写在哪个文件里?为什么一个只有九条数据的目录站,仓库里会多出七个 Markdown 文件?
本文结构:前半部分是清单——一个项目的规范具体由哪些文件构成、每个文件写什么;后半部分是问答——把这几个月我踩出来的十个疑问逐个答掉。
第一部分:一个项目的规范具体有哪些
1. 一张地图:按“谁会打开它”分类
我一开始按文件夹去理解这些文件(.github/、根目录、docs/),越看越乱。真正清晰的切法只有一条轴——读者是谁。同一件事要写给四种读者,就会散落成四个文件:
| 读者 | 文件 | 什么时候生效 |
|---|---|---|
| 第一次点进仓库的人 | README.md |
GitHub 仓库首页自动显示 |
| 想改内容的人 | CONTRIBUTING.md |
对方点“新建 PR”时,GitHub 提示他先读 |
| 想知道“我能不能拿去用”的人 | LICENSE、LICENSE-CONTENT.md |
GitHub 自动识别,侧栏直接显示成 MIT / CC BY-NC-SA-4.0 |
| 提 PR 的人 | .github/PULL_REQUEST_TEMPLATE.md |
自动出现在 PR 描述框里 |
| 提 issue 的人 | .github/ISSUE_TEMPLATE/*.yml |
“新建 issue”下拉里的那几个表单 |
| AI 编程助手 | AGENTS.md |
接上这个仓库的 AI 进来先读它 |
| 网站访客 | src/content/docs/*.md |
这才是发出去的网页,不是仓库规范 |
一句话记法:给人看的进 CONTRIBUTING,给工具看的进 AGENTS,给访客看的进内容目录,给 GitHub 机器看的必须放在它规定的路径上。
2. 每个文件具体写什么
README.md——回答“这是什么、能不能用、怎么跑起来”。我这个目录站里包含四块:项目定位(只登记入口,不复制正文)、每个条目记录哪些字段、状态词定义表、下架与更正通道,最后是本地运行命令与技术栈。
CONTRIBUTING.md——回答“想改该怎么走流程”。四节:
- commit 规范:
type(scope): 中文描述 - PR 规范:标题同格式,且必须附核查证据
- 命名规范:文件名、slug、日期、状态词
- 语言规范:什么用中文、什么必须用英文
LICENSE + LICENSE-CONTENT.md——回答“谁能怎么用”。代码一份(MIT),内容与数据一份(CC BY-NC-SA 4.0)。为什么必须拆,见第 5 问。
.github/PULL_REQUEST_TEMPLATE.md——提 PR 时描述框里预填的清单。它的作用不是提醒,而是把证据变成必答项,见第 4 问。
.github/ISSUE_TEMPLATE/*.yml——GitHub 官方 YAML 表单。目录类项目最少三个:收录申请、信息更正、下架请求。
AGENTS.md——给 AI 助手的仓库说明书:哪些文件能改哪些不能改、这个框架的已知坑、改完必须跑什么验证。见第 6 问。
内容目录里的对外声明——站内“关于本站”页要承担规范中“对外”的那一面:非官方声明、免责、维护带宽、下架通道。这部分是给公众看的,不是给贡献者看的,别混进 CONTRIBUTING。
3. 最小清单:一个静态小站需要哪几个
| 目的 | 文件 | 必要性 |
|---|---|---|
| 别人看得懂项目 | README.md |
必须 |
| 别人知道怎么改 | CONTRIBUTING.md |
必须 |
| 界定谁能怎么用 | LICENSE(代码)+ LICENSE-CONTENT.md(内容) |
Wiki / 数据型项目必须 |
| 提交时交出证据 | .github/PULL_REQUEST_TEMPLATE.md |
有外部贡献者就必须 |
| 权利人有一步到位的通道 | .github/ISSUE_TEMPLATE/*.yml |
聚合、索引类项目最重要的一条 |
| 别让 AI 自作主张 | AGENTS.md |
项目会被 AI 接手就必须 |
| 自动化校验 | .github/workflows/、schema、lint |
可以推迟,但要写明“是推迟不是遗漏” |
我这次实际落地是 786 行治理文件,配的是一座只有 9 条数据的目录站。
第二部分:十个疑问
第 1 问:为什么不能合并成一个文件?
我原本的设想是写一个大文档,把 commit、PR、命名、语言规范全放进去,觉得拆七个文件是形式主义。
实际情况是:这些位置不是社区习惯,是 GitHub 产品里写死的路径匹配规则。
- 表单必须放在
.github/ISSUE_TEMPLATE/,文件名就是template=xxx.yml里那个名字; - PR 模板必须叫
PULL_REQUEST_TEMPLATE.md,放在.github/、根目录或docs/三处之一; CONTRIBUTING.md必须叫这个名字,GitHub 才会在开 PR 时给贡献者弹出提示链接;LICENSE必须叫这个名字,侧栏的许可证标签才会从 “View license” 变成具体的MIT。
内容塞进一个叫 规范.md 的文件,人类读者或许能看到,但所有自动化触点全部失效:没有表单下拉、没有描述框预填、没有贡献提示、没有许可证识别。等于没写。
第 2 问:commit 规范该定多严?
规范最容易犯的错,是照着一个自己根本达不到的标准写。所以我先去查同类项目实际怎么提交——同一个主题下四个仓库的 git log:
| 项目 | 实际提交信息 |
|---|---|
| 南开 NKUwiki | feat(food): 整张卡片可点开详情弹窗、docs(buildings): 校园建筑改为一座教学楼一篇、fix(theme): 悬浮球阅读进度以正文为准而非整页 |
| 西邮 Wiki | docs: 更新实验室列表、fix: 修正兴趣群展示页面的在线表格链接 (#10),也混着 添加了一些细节,删除了过时的内容 (#11) |
| 华北电力 Wiki | Update 05.DeepSeek Harness实战指南:….md、CS2决赛、联系方式更新,偶有 feat: 支持按作者隐藏邮箱与姓名 |
| SJTU Wiki | edit 军训、Add 吉星派对 to game list、update config |
结论很直接:严格 Conventional Commits 加中文描述这一档,只有南开做到了;多数项目只做一半。 于是我的选择是照南开那一档写要求——它是同类项目里现成的、被验证可行的做法,而不是我凭空定的规矩。
落到文件里:
type只用datadocsfixfeatchoreci六个,全小写 ASCII;scope用学校英文简称(nankai、sjtu),跨多校时可省略;- 描述用中文,不超过 72 字符,句末不加句号;
- 一次 commit 只做一件事,“改八个学校的核查日期”和“重排表格对齐”不许混在同一个 commit 里。
type 与 scope 保持 ASCII 是为了让工具链认得,描述用中文是为了让中文读者读得懂。
第 3 问:“不要中英文混杂”怎么变成可执行标准?
规范里最容易写成口号的就是语言。写了“统一语言”四个字,三个月后自己就开始写“这个 feature 需要 refactor”。
能执行的标准是看句子的主体语言,而不是看有没有英文单词:
- 专名照写原名,不加引号、不硬翻:VitePress、Astro、MediaWiki、Wiki.js、GitHub Pages;
- 术语首次出现给原文,之后用中文:「可达状态(地址能否打开)」;
- 不允许把英文词当口头禅插进中文句子;
- 翻译不过来就保留原文,不要生造中文对应词。
配套的命名规则:文件名、目录名、URL slug 全小写 ASCII kebab-case,禁止中文文件名(URL 转义与 git 工具链都会出问题);日期一律 ISO 8601 写 2026-10-24,不写“10 月 24 日”也不写“最近”;状态词只有 可访问 待核实 已失效 停更 四个,一字不许改——最后这条看似琐碎,但它决定目录能不能被机器统计、被读者横向比较。
顺手一个实测事实:我核的那九个高校 Wiki 站点里,七个用 VitePress,其中四个还是同一个 2.0.0-alpha.20。这个圈子技术选型高度趋同,语言规范按中文主体来定,没什么可纠结的。
第 4 问:规范写了没人遵守怎么办?
靠文档里喊话是没用的,有效的写法是让不合规的提交在物理上填不完。
PR 模板里我只做了一件事,把证据变成必答项:
- 抓取方式(浏览器打开 / curl / 其他):
- 返回内容大小:
- 页面 `<title>` 原文:
- 校名关键词出现次数:
并写明一条硬要求:只写“能打开”“我看过没问题”不视为通过。
理由来自真实踩坑。核查九个站点时:
- 重庆大学
cqu-openlib.cn首页只有 2.5 KB,是个 React 外壳,只看状态码 200 会误判成空站;但它的/nav-index.json有 555 KB 的课程树,生成时间就在那两天。 - 南开
freshnkuer.wiki返回 23 KB,<title>是「首页 | NKUwiki - 南开校园知识库」,页面里“南开”出现 21 次——这才叫确认。 - 成都航空那个地址,DNS 能解析但 TLS 握手直接断,
http与https都返回 0 字节。本机连不上不等于站点失效:我先标待核实,换手机网络复测仍然打不开,才改成已失效,并把证据和日期一起写进状态那一栏。
静态托管的 404 页、空壳首页、域名停放页都会返回 200。状态码不是证据,所以模板不许把状态码当证据。
第 5 问:许可为什么要拆成两个文件?
因为一个仓库里同时存在两种版权客体:
- 代码(构建配置、模板、样式)适合 MIT,别人拿去改、拿去用都行;
- 内容与数据(条目、文档、目录结构)适合 CC BY-NC-SA 4.0——要求署名、禁止商用、演绎必须同协议共享。
我上一站是整个仓库一份 MIT,正文也一起 MIT 了。这在 Wiki 型项目里是错的默认:MIT 等于允许别人把内容拿去商用转载。
同类项目早就把这个做法固化了。南开仓库根目录同时放着 LICENSE(MIT)和 LICENSE-CONTENT.md,README 里明写“本项目采用双协议许可:源代码 MIT License,文档内容 CC BY-NC-SA 4.0”。
我照这个结构写,并针对目录站的特殊性,把最要紧的一句话放在第一节:被链接的各高校 Wiki 站点及其全部内容归各自权利人所有,本项目不对其主张任何权利,也无权代为授权。 面对“没征询过各方就建目录”这件事,这句话比任何解释都管用——它把“我没说你的内容是我的”讲在最显眼的位置。
两个细节:
- CC 协议全文不要手抄。 我把南开文件里的法律条款抽出来,跟 creativecommons.org 官方页面做了忽略大小写的逐句比对,八个小节标题与若干长句全部一致,只有 HTML 渲染时的大小写不同,确认是原文才嵌进自己的
LICENSE-CONTENT.md。手抄一份许可证,是给自己制造法律文件里的错别字。 - “贡献即授权”要写进许可文件,而不只写在 CONTRIBUTING:提交 PR 即同意按同样条款发布。git 历史无法安全擦除,所以这个授权不可撤回。
第 6 问:AGENTS.md 是不是抢了 CONTRIBUTING 的活?
疑问很合理——前 AI 时代这些规范不就是给人看的吗?
对,那一份还在,就是 CONTRIBUTING.md,没有被取代。两者分工不同:
| CONTRIBUTING.md | AGENTS.md | |
|---|---|---|
| 读者 | 人类贡献者 | AI 编程助手 |
| 回答的问题 | 怎么参与、流程是什么 | 哪些文件能动、哪些不能动、框架有什么坑、改完跑什么验证 |
| 典型内容 | fork → 改 → 构建 → 提 PR | 「不要写自定义组件」「这两条构建警告可以忽略」 |
这条约定大约从 2024 年起成型,现在 Cursor、Copilot、Claude Code 这类工具接入仓库时都会优先读它。判断它是否已成默认基建有个省事的证据:我用 Astro 官方模板初始化项目时,AGENTS.md 是模板自带的(内容是通用的 Astro 开发说明)。官方已经把它当作默认交付物。
我上一站踩过它的早期版本:CLAUDE.md。那个文件里我写的全是“CSS 变量必须复用、组件文件 PascalCase、不要引入大型 UI 框架”。回头看,那本来就是写给工具的活,我却当成给人类的规范来写,所以从没起到作用。给工具写的规则要具体到“哪个文件不能碰”,给人类写的规则要具体到“第一步做什么”,混在一起就两边都不执行。
AGENTS.md 里大概最有用的一条是:
不要引入 CI 校验、schema、lint、husky、自动检查工作流,除非维护者明确要求。这类东西目前是明确推迟状态,不是遗漏。
因为 AI 助手看到“少了一个 CI”会手痒补齐。把“这是故意不做的”写进文件,才能防止下一个接手的工具自作主张。
第 7 问:规范里最容易写错的是哪一条?
是维护承诺。这一条我写完所有文件之后又回去删掉了一半。
我在 README、站内文档、CONTRIBUTING 和 issue 表单四个地方都写了同一句话:“每月一次批量核查地址可达性”。听起来很负责——有周期、有承诺、有可考核的指标。
写完就后悔了,因为它本质上是给自己签了一份 KPI:
- 条目从 9 个涨到 90 个时,“每月一次”就从顺手小事变成还不清的债;
- 一旦写明周期,别人就可以正当地质问“这个月你怎么没核查”;
- 项目做不下去的原因,通常不是内容太多,而是承诺太大。
于是四处全部改成“由维护者利用课余时间不定期人工核查,不做实时更新,也不为响应速度设定任何指标、周期或时间表”。
但同批文件里另一句承诺我留下了:“站点负责人要求下架,确认收到后 7 天内处理。” 两者性质不同:
| 每月批量核查 | 7 天内下架 | |
|---|---|---|
| 劳动形态 | 周期性,会随条目数滚雪 | 单次动作,删一行表格两分钟 |
| 谁在等 | 没有具体的人在等 | 一个明确的权利人正在等 |
| 违约代价 | 被质疑“你不守时” | 可能升级为“你未经同意挂我链接”的正式纠纷 |
给维护速度立指标是自我剥削,给下架设时限是对权利人的基本尊重。 规范文件里同时存在两类承诺时,要一条一条问“这是谁的诉求”,而不是笼统地全删或全留。
第 8 问:防御性语言要自己写吗?
不需要,同类项目早就写好范本,抄就行。三份原件:
其一,awesome 宣言,链接聚合类项目的行业祖宗条款:
If you want your list to be included in
awesome, try to only include actual awesome stuff in your list. After all, it’s a curation, not a collection.
一句话解决“你是不是链接农场”的质疑:这是筛选,不是收集。把“宁缺毋滥”写进规范,比事后解释“为什么这个也收”省力得多。
其二,大学生活质量指北的免责声明,同类高校信息项目的成熟写法:
本站内容来源于网络和问卷收集,由于数据的准确性无法保证,建议仅将本站内容作为参考……如您因本站数据有误而错误择校,本站不承担相应责任。
它甚至主动承认“部分国内高校可能未被准确分类到省市目录中,敬请谅解”。先把缺陷讲出来,比被指出来再解释强。
其三,指北站的四类举报表单:侵权举报、数据纠错、恶意数据举报、高校更名。这是“没事先征询意见”的标准答案——不预先取得授权,但给出一条随时可用的下架与更正通道。
我自己加的一条:
失效条目不删除,只把状态改为“已失效”并保留核查证据。悄悄删掉一条记录,比挂出一条过期链接更难解释。
过期链接是无能,偷偷删除是心虚,这两件事必须在文档里分开。
第 9 问:CI、schema、lint 要不要一起上?
这次全部没做,而且是明确推迟。
判断依据是项目当前的体量与读者:9 条 Markdown 表格数据,配一套 schema 校验、死链检查、双语一致性检查,成本全落在一个人身上,收益是“看起来更专业”。而规范本身(CONTRIBUTING 加 PR 模板的必答项)已经能拦住绝大多数不合规提交。
但推迟必须写明,否则它会一直被误解成遗漏——被我误解,也被接手这个仓库的 AI 误解。所以两处各留一句:治理文档里按“必须 / 视情况 / 可推迟”分档,AGENTS.md 里写成禁止事项:“不要引入 CI 校验、schema、lint,除非维护者明确要求。这类东西目前是明确推迟状态,不是遗漏。”
第 10 问:怎么判断一条规范该不该加?
只有一个标准:一年后我还会不会照它执行。
不会执行的规定写下来就是给未来欠债,也是给别人递上一把指控自己不守法的刀。
这也是这个项目和我上一站最大的区别:规范的作用不是显得专业,而是替你拒绝掉一部分未来的工作。每一条写下来的“我们不做 X”,都是给自己减掉的维护量。


