repo-health

repo-health

仓库基石技能。负责规范为任何代码仓库奠定基础的社区健康文件：

• README.md — 项目的入口（Standard Readme 规范）。
• LICENSE — 法律协议（交由 choosealicense.com 选择；doc-master 不负责挑选）。
• CONTRIBUTING.md — 外部贡献者如何提议更改。
• CODE_OF_CONDUCT.md — 行为规范（默认采用 Contributor Covenant 3.0；备选为 2.1）。
• SECURITY.md — 漏洞报告政策。
• SUPPORT.md — 用户寻求帮助的渠道（小型仓库通常可选）。
• .github/ 模板 — issue / PR / CODEOWNERS / FUNDING / CITATION。
• REUSE 3.3 + SPDX — 每个文件的版权和许可证元数据。

每个基石文件都有一份参考文件，介绍其结构、常见问题和路由说明。本 SKILL.md 是精简入口——按需加载参考文件。

先诊断，不要自动创建

doc-master 会在建议创建任何基石文件之前，先进行四问诊断：

1. 受众 — 谁会在什么情况下阅读？（顺手贡献者？安全研究人员？困惑的用户？合规审计员？）
2. 是否已存在？ — 许多仓库已经有名称或位置不同的等效文件。先查找，再编写。
3. 应该放在哪里？ — 顶层目录、.github/、docs/？每个基石文件都有惯用位置。
4. 由谁负责？ — 指定一位负责人或别名。“团队”不是负责人。CODEOWNERS 的存在正是因为所有权很重要。

只要任何一个答案是“否”或“我们不知道”，就先不要创建文件。 大多数小型仓库不需要 SUPPORT.md，不需要 FUNDING.yml，也不需要每个文件都添加 REUSE 标头。盲目照搬基石文件只会产生无人阅读、无人维护的文档——这与 ADR 所遵循的反凑数原则相同。

默认建议

对于任何对原始团队以外人员可见的代码仓库：

基石文件	默认建议
README.md	是 — 必需。使用 Standard Readme 结构。参见 references/readme-canon.md。
LICENSE	是 — 任何将被复用的代码都必须有许可证。doc-master 会将选择工作交由 choosealicense.com；不会代为选择。参见 references/license-routing.md。
CONTRIBUTING.md	是 — 接受外部贡献时必需。只读仓库可省略。参见 references/contributing-canon.md。
CODE_OF_CONDUCT.md	是 — 存在任何外部参与时必需。默认采用 Contributor Covenant 3.0；仍然有效的旧版备选为 2.1。参见 references/code-of-conduct-canon.md。
SECURITY.md	是 — 代码会处理不可信输入、处理机密、部署到生产环境或存在任何用户可见攻击面时必需。参见 references/security-canon.md。
SUPPORT.md	大概不需要 — 大多数小型仓库都不需要。仅当用户错误地将 issue 跟踪器用于支持问题时添加。参见 references/support-canon.md。
Issue / PR / CODEOWNERS / CITATION / FUNDING	视情况而定。 每项都有实际适用条件。参见 references/templates-canon.md。
REUSE 3.3 / SPDX 标头	是 — 仓库汇总了采用多种许可证的代码、将部署到要求提供 SBOM 的环境，或需要机器可验证的许可证元数据时必需。参见 references/reuse-spdx-canon.md。

如何运行初始化或审计

当用户要求设置仓库文档时：

1. 清点现有内容（README*、LICENSE*、CONTRIBUTING*、CODE_OF_CONDUCT*、SECURITY*、SUPPORT*、.github/）。
2. 对每项核心文档进行四问诊断。
3. 一次针对一个文件，建议新建、合并或保持不变。不要批量生成。
4. 对于应新建的文件，加载匹配的参考内容；生成包含占位符的草稿，供用户填写。绝不要编造维护者姓名、联系别名、许可证选择或 SLA 时限。
5. 许可证选择是引导而非代选。该技能列出常见默认选项（MIT、Apache-2.0、BSD-3-Clause、GPL-3.0、MPL-2.0），并指向 choosealicense.com；由人来决定。

当用户要求审计仓库文档时：

1. 执行相同的清点。
2. 对每项已有的核心文档，与规范进行比较，并标出偏差、缺失章节、过时日期或仅列出单个维护者的联系信息。
3. 对每项缺失的核心文档，询问四问诊断的答案是否足以支持创建——大多数缺失的 SUPPORT.md 和 FUNDING.yml 都应继续保持缺失。
4. 生成编号的保留 / 重写 / 新建 / 删除列表。不要批量重写。

硬性规则

• doc-master 不选择许可证。 必须引导用户前往 choosealicense.com。该技能会列出常见默认选项；由人来选择。
• 行为准则的联系信息必须是共享别名，绝不能是个人邮箱。 可以是 [email protected]、community@… 或审核团队；绝不能是个人收件箱。单人维护是拒绝条件。
• SECURITY.md 的联系信息必须是共享别名或协作渠道（GitHub Security Advisories、指定计划、security@…）。拒绝使用单个维护者的邮箱。
• 禁止填充冗余内容。 每个建议创建的文件都必须通过四问诊断。若无法回答这四个问题，就不应创建该文件。
• 每轮只处理一项发现。 审计时，该技能遵循 adr-critique / markdown-style 的方式：注明行号、引用原文、指出规则名称、提出改写方案，并逐项征求批准。

路由——此技能不负责的内容

• Markdown 格式——核心文档创建后，使用 markdown-style（/doc-lint）进行检查。
• 架构决策的 ADR——使用 doc-diagnostic / adr-drafting。“我们采用了 REUSE”可能属于 ADR；各文件本身的 REUSE 标头则不属于。
• 变更日志——../doc-diagnostic/references/changelog-canon.md。
• 运行手册 / 事后分析 / 未决问题登记表——../doc-diagnostic/references/{runbook,postmortem,open-questions}-canon.md。
• AI Agent 上下文的 AGENTS.md——../doc-diagnostic/references/agentic-docs-canon.md。

示例

我刚启动了一个新的开源项目。仓库根目录需要哪些文档？ 遵循 opensource.guide 的四文件规范：README.md、LICENSE、CONTRIBUTING.md、CODE_OF_CONDUCT.md。如果代码会处理不可信输入，再添加 SECURITY.md。新项目通常不需要 SUPPORT.md。正在加载 `repo-health`；我们会逐个文件检查这四个问题。许可证选择会引导至 choosealicense.com——我不会替你选择。 我应该为“我们采用了 Contributor Covenant 3.0”编写 ADR 吗？ 不用——这是采用 CODE_OF_CONDUCT.md，而不是 ADR。默认采用 Contributor Covenant 3.0（四级执行阶梯）；2.1 是较旧但仍有效的备选方案。联系邮箱必须是共享别名，不能是单个维护者的地址。正在加载 `repo-health` 参考文档 `code-of-conduct-canon.md`。 审查一下我们的社区健康文件。 正在加载 `repo-health`。先列出清单，然后逐个文件进行四项诊断，最后给出编号的保留 / 重写 / 新建 / 删除列表。我会将 SECURITY.md / CODE_OF_CONDUCT.md 中指向单个维护者的联系方式标记为拒绝条件。 我需要 CITATION.cff 吗？ 如果仓库属于研究软件，或预期会被学术引用：需要——CITATION.cff 是目前趋于统一的格式。否则不需要。架构说明见 `references/templates-canon.md`。

参考资料

• references/readme-canon.md — Standard Readme 规范；九个标准章节。
• references/license-routing.md — 常见许可证默认选择及引导规则（doc-master 不替你选择）。
• references/contributing-canon.md — CONTRIBUTING.md 结构、Conventional Commits 1.0、DCO。
• references/code-of-conduct-canon.md — 默认采用 Contributor Covenant 3.0，2.1 为备选；执行阶梯；共享别名规则。
• references/security-canon.md — SECURITY.md 章节；私密报告渠道；响应时限下限。
• references/support-canon.md — SUPPORT.md 渠道；多数仓库可跳过的情形。
• references/templates-canon.md — .github/ISSUE_TEMPLATE/*.yml、PULL_REQUEST_TEMPLATE.md、CODEOWNERS、FUNDING.yml、CITATION.cff。
• references/reuse-spdx-canon.md — REUSE 3.3 文件级标头、LICENSES/ 文件夹、REUSE.toml、.license 伴随文件；SPDX 标识符目录。