Imported from BlueChonk/skills (.agents/skills/github-doc-standards/SKILL.md). Install upstream with npx skills add BlueChonk/skills --skill github-doc-standards. Copyright stays with the author.

GitHub 项目文档规范

适用于所有个人日常开发中创建和维护的项目。

零、适用范围与边界

本规范明确覆盖与不覆盖的范围，避免误用。

覆盖范围

• 个人及小型团队 GitHub 项目的文档规范
• README / CONTRIBUTING / CHANGELOG 等核心文档模板
• 话题标签管理与脱敏规范
• 文档质量检查与故障排查
• 文档即代码实践与自动化工具链

不覆盖范围

判断标准： 如果文档内容涉及上述领域，建议先查找该领域的专项规范，本规范仅提供通用文档质量建议。

一、语言优先级

原则：

• 默认中文优先，README.md 必须是中文
• 个人小项目只需中文，热门/正式项目才考虑中英双语
• 多语言文档需保持内容同步，避免中英文版本信息不一致

二、项目话题标签

做项目与维护项目时，需要给项目合适的话题（topic）标签，便于分类和检索。

常用标签分类

使用规则

• 每个项目 3-8 个标签，不超过 10 个
• 标签使用小写字母 + 连字符（kebab-case）
• 优先使用 GitHub 已有热门标签，避免生造
• 必须包含：语言标签 + 至少一个领域/框架标签
• 在仓库 Settings → Topics 中添加

反模式（常见错误）

FAQ

Q：如何判断该用哪些标签？ A：先确定语言标签（必选），再选 1-2 个框架/库标签，最后选 1-2 个领域标签。总共不超过 8 个。

Q：标签可以随时修改吗？ A：可以。在仓库 Settings → Topics 中随时增删，建议项目稳定后固定下来。

Q：热门标签在哪里查？ A：访问 https://github.com/topics/ 浏览已有标签及其使用量。

Q：项目从活跃转为归档，标签需要调整吗？ A：需要。将 wip 替换为 archived，并添加说明项目已停止维护。在 README 顶部追加归档声明，避免新用户误用。

Q： Fork 仓库需要修改标签吗？ A：建议修改。Fork 后的项目用途可能与上游不同，保留原标签会造成误导。至少替换领域标签以反映实际用途。

Q：同一标签在多个层级重复（如 python 和 python3）怎么办？ A：只保留一个最精准的。GitHub 的标签系统不区分版本，python 已足够。多个相似标签反而降低检索效率。

Q：文档类仓库（如笔记、知识库）用什么领域标签？ A：推荐使用 documentation、notes、knowledge-base 等。若内容偏技术教程，可加 tutorial。避免使用过于宽泛的标签如 misc。

Q：如何处理"文档债务"？ A：文档债务指因长期未维护而导致文档与代码严重脱节的现象。偿还策略：

1. 识别债务：运行 git log --since="3 months ago" --name-only --pretty=format:"" | sort | uniq -c | sort -rn 找出高频变更文件
2. 优先偿还：变更频率高但文档未更新的文件优先处理
3. 批量修复：每周固定 30 分钟集中处理，而非一次性重写
4. 预防机制：将文档更新纳入 PR 模板检查项，代码变更必须同步更新文档

三、README.md 内容规范

结构要求

• 项目简介（一段话说清楚是什么）
• 目录结构
• 快速开始（安装、使用）
• 配置说明
• 常见问题
• 许可证

README 长度建议

完整 README 模板

# 项目名称

> 一句话描述项目是什么、解决什么问题

## 特性

- 核心功能 1
- 核心功能 2
- 核心功能 3

## 快速开始

### 环境要求

- 运行时/语言版本
- 依赖的第三方服务

### 安装

\`\`\`bash
# 克隆仓库
git clone https://github.com/用户名/项目名.git
cd 项目名

# 安装依赖
npm install
# 或
pip install -r requirements.txt
\`\`\`

### 使用

\`\`\`bash
# 启动命令
npm start
# 或
python main.py
\`\`\`

## 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `PARAM_A` | `default_a` | 参数 A 说明 |
| `PARAM_B` | `default_b` | 参数 B 说明 |

## 项目结构

\`\`\`
.
├── src/          # 源代码
├── docs/         # 文档
├── tests/        # 测试
└── README.md     # 本文件
\`\`\`

## 常见问题

**Q：问题描述？**
A：解答内容。

## 许可证

[MIT](LICENSE) © 作者名

真实项目示例参考

优秀 README 参考项目：

• microsoft/vscode — 结构清晰，信息密度高
• facebook/react — 简洁有力，快速上手
• vercel/next.js — 文档与代码分离，README 做导航

四、CONTRIBUTING.md 模板

当项目接受外部贡献时，必须提供此文件。

# 贡献指南

感谢你对本项目的兴趣！以下是参与贡献的指南。

## 如何贡献

1. Fork 本仓库
2. 创建你的功能分支 (`git checkout -b feature/xxx`)
3. 提交你的修改 (`git commit -m 'feat: 添加 xxx 功能'`)
4. 推送到分支 (`git push origin feature/xxx`)
5. 开启 Pull Request

## 提交规范

提交信息格式：`<type>(<scope>): <中文描述>`

type 类型：
- `feat`：新功能
- `fix`：修复 bug
- `docs`：文档变更
- `style`：代码格式调整
- `refactor`：重构
- `test`：测试相关
- `chore`：构建/工具变更

## 代码规范

- 代码风格遵循项目现有约定
- 新增功能需包含对应测试
- 所有测试必须通过

## 问题反馈

- 使用 Issue 提交问题
- 描述清楚复现步骤和环境信息

五、CHANGELOG.md 模板

记录项目版本变更历史，帮助用户了解更新内容。

# 变更日志

所有项目的显著变更都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [Unreleased]

### Added
- 新增功能描述

### Fixed
- 修复问题描述

## [1.0.0] - 2024-01-15

### Added
- 初始版本发布
- 核心功能实现

[Unreleased]: https://github.com/用户名/项目名/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/用户名/项目名/releases/tag/v1.0.0

六、文档脱敏规范

项目文档中禁止包含任何真实敏感数据，包括但不限于：

脱敏示例：

# 脱敏前
token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
qqNumber: "5729475454240175104"

# 脱敏后
token: "***"
qqNumber: "5729xxxx75104"

检查清单：

• 文档中无真实 API Key / Token
• 文档中无真实设备指纹 / 用户标识
• 文档中无真实 Cookie / Session
• 文档中无完整 RSA 密钥
• 截图中的敏感信息已打码

七、文档质量检查清单

发布前逐项检查，确保文档质量达标。

基础检查

• README.md 存在且内容完整
• 项目简介清晰，一句话说明项目用途
• 快速开始可复现（按步骤操作能跑起来）
• 许可证文件存在
• 话题标签已添加（3-8 个）

内容质量

• 无错别字、语法错误
• 链接有效（无 404）
• 代码示例可执行
• 截图清晰、已脱敏
• 目录结构（如有）与实际一致

进阶检查

• CONTRIBUTING.md 存在（接受贡献时）
• CHANGELOG.md 存在（版本化项目）
• 多语言文档内容同步
• 文档更新频率与代码变更匹配

八、文档质量故障排查

常见问题诊断与修复

文档质量自评问卷

发布前回答以下 10 个问题，每题 1-5 分，总分低于 35 分需改进。

评分结果处理：

• 45-50 分：优秀文档，可作为范例
• 35-44 分：合格文档，有小幅改进空间
• 25-34 分：需要改进，重点修复低分项
• 25 分以下：需要重写，建议从模板重新开始

九、最佳实践

文档更新检查清单

每次代码变更时，对照此清单同步更新文档。

代码变更触发条件：

• 新增/删除/修改功能 → 更新 README「特性」和「使用」章节
• 配置项变更 → 更新「配置」章节，标注版本兼容性
• API 接口变更 → 更新接口文档，标注废弃版本和迁移指南
• 依赖版本变更 → 更新「环境要求」和安装步骤
• Bug 修复 → 在 CHANGELOG 中记录，关闭相关 Issue
• 项目状态变更 → 更新话题标签和 README 状态标识

文档过期检测机制

# 检测超过 90 天未更新的文档文件
find . -name "*.md" -mtime +90 -not -path "./node_modules/*"

# 检测文档与源码修改时间差异
git log --since="6 months ago" --name-only --pretty=format:"" | sort | uniq -c | sort -rn | head -20

建议频率：

• 每次 PR 合并前：快速检查关联文档是否更新
• 每月一次：运行过期检测脚本，清理过时内容
• 每季度一次：全面审查文档质量，偿还文档债务

文档更新频率

文档自动化工具推荐

文档评分标准

十、多语言项目文档差异

建议： 个人项目默认中文，有海外用户考虑时再补充英文版本。

十一、文档即代码（Docs as Code）实践方案

核心理念

将文档与代码同等对待，使用版本控制、代码审查、CI/CD 等工程化手段管理文档。

实践清单

自动化生成工具链

TypeScript 项目：TypeDoc + Docusaurus

# 安装工具
npm install --save-dev typedoc typedoc-plugin-markdown docusaurus

# 从 TypeScript 源码生成 API 文档
npx typedoc --out docs/api src/index.ts

# 启动 Docusaurus 文档站点
npx docusaurus start

Python 项目：Sphinx + AutoDoc

# 安装工具
pip install sphinx sphinx-autodoc-typehints

# 从 docstring 生成文档
sphinx-apidoc -o docs/source src/
make html

多语言管理策略

文档版本管理方案

GitHub Actions 自动化示例

name: Documentation CI
on:
  pull_request:
    paths:
      - '**.md'
      - 'docs/**'

jobs:
  lint-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Markdown Lint
        uses: articulate/actions-markdownlint@v1
      - name: Link Check
        uses: lycheeverse/lychee-action@v1

附录：文档更新检查清单（速查表）

每次代码变更时快速对照。

代码变更时：
□ 功能新增 → 更新 README 特性章节
□ 配置变更 → 更新配置说明
□ API 变更 → 更新接口文档 + 迁移指南
□ 依赖更新 → 更新环境要求
□ Bug 修复 → 更新 CHANGELOG
□ 状态变更 → 更新话题标签

发布前：
□ 文档格式 lint 通过
□ 链接有效性检查通过
□ 代码示例可执行
□ 敏感信息已脱敏
□ 多语言版本同步

每月维护：
□ 运行过期检测脚本
□ 修复文档债务（高频变更文件优先）
□ 更新最后维护时间戳