writing-a-readme

编写 README

首次响应

调用此技能时，首先询问：“这个项目是做什么的？请用一句话说明。”

为什么这很重要

人们阅读 README 时，往往会在不到一分钟内决定是否继续读下去。GitHub 生态中的数千个模板仓库逐渐形成了相当统一的结构，正是因为这种结构有效：先说明“这是什么，为什么值得关注”，再介绍“如何配置高级选项”。偏离这一顺序——即使内容很出色——也会让 README 更难浏览，更容易被读者关掉。

模板领域有三种主流风格，值得了解它们，因为它们分别针对不同目标进行了优化：

• othneildrew/Best-README-Template 及其众多分支——徽章和 Logo 较多，注重视觉效果，适合希望吸引贡献者和获得 Star 的项目。常见于个人项目、作品集，以及面向广大受众的开源库。
• richardlitt/standard-readme——一套严格的规范（包括章节名称、顺序、必需项和可选项），旨在让同一组织或生态系统中的多个仓库保持一致，在 Node/npm 领域历来较为常见。视觉效果不那么花哨，但更可预测。
• makeareadme.com——更轻量、注重讲解的指南，而非僵化的模板：提供一个精简的起始框架，以及一份可选章节清单，并说明每个章节的作用。它旨在帮助任何编程项目（不只是 npm 包）快速达到合理的基准。其他两种风格通常会略过的两个章节便源自此处——支持（如何寻求帮助：问题跟踪器、聊天、电子邮件）和项目状态（如果项目进展放缓、已归档或正在寻找维护者，应在顶部注明）。只要适用，这两个章节都值得添加，即使你采用了另外两种风格之一作为基础模板。

选择符合需求的风格（也可以混合使用——采用 Best-README-Template 的徽章、standard-readme 对章节顺序的规范，以及 makeareadme.com 的支持和项目状态习惯），不要不假思索地对所有项目都使用同一个模板。各类模板的完整示例见 references/templates.md。

第 1 步：确定 README 的类型

先问问自己（或简单询问用户），项目实际属于以下哪一类——这会影响哪些章节最重要：

• 库／软件包（npm、pip、gem、crate 等）——通过软件包管理器安装、可运行的代码示例和 API 参考是核心内容。版本、下载量和构建状态徽章在此很有参考价值。
• CLI 工具——先介绍安装，再用一个 用法 代码块展示实际命令和标志，通常还会提供 --help 输出或 GIF/asciinema 录屏。跳过“API 参考”。
• 应用／服务（Web 应用、可自托管的工具）——截图或演示链接比代码片段更重要。“快速入门”通常指“如何部署或运行”，而不是“如何导入”。
• GitHub 个人资料 README（仓库名称与用户名完全相同）——这是一种完全不同的类型：简短、个性化，介绍的是个人而非代码库。不要套用库的 README 结构。
• 单体仓库／组织级 README——主要用作导航：说明其中包含哪些软件包、链接到各软件包自己的 README，以及如何统一构建／测试整个项目。

如果根据上下文无法判断，值得先简短确认一下（“这是一个别人会用 npm install 安装的库，还是一个别人会运行／部署的应用？”），再开始起草——两者所需的章节确实不同，猜错了就得重写。

第 2 步：收集原始材料

不要编造项目事实。起草前，请查找（并向用户询问无法查明的内容）：

• 现有的 package.json / pyproject.toml / Cargo.toml / go.mod 等文件，以确认真实的项目名称、描述、许可证和依赖项。
• 该生态系统中实际的安装命令（npm install <name>、pip install <name>、cargo add <name>……）——切勿猜测软件包名称。
• 一个真实且可运行的用法示例——从测试、examples/ 中获取，或请用户提供其标准的“hello world”用例。README 的可信度很大程度上取决于第一个代码块粘贴后是否能正常运行。
• 许可证（检查是否有 LICENSE 文件）和贡献规范（是否已有 CONTRIBUTING.md？），不要默认声称采用“MIT”许可证或“欢迎提交 PR”。
• 仓库中是否已有可复用的徽标、截图或演示 GIF——不要虚构指向不存在文件的 images/logo.png。

如果这些信息缺失且无法查明，请留下清晰标记的占位符（``），不要编造看似可信的细节——自信地给出错误的安装命令，比坦诚承认信息缺失更糟。

第 3 步：结构

无论采用哪种风格，README 各章节通常都有固定顺序，因为每一节都回答读者接下来会提出的问题。默认使用以下骨架，不适用的章节直接删除，不要留空：

# Project Name

[badges: build status, version, license, ...]

One or two sentences: what this is and who it's for.

[optional: screenshot, GIF, or logo]

## Table of Contents
[only for READMEs long enough to need one — roughly 200+ lines / 5+ sections]

## About / Features
What it does and why it exists. What makes it different from the obvious alternative.

## Getting Started
### Prerequisites
### Installation

## Usage
The real, runnable example. This is the section people actually read.

## Configuration / API Reference
[if applicable — options, environment variables, exported functions]

## Support
[optional — where to get help: issue tracker, chat/Discord, email]

## Roadmap
[optional — link to Issues instead if the roadmap lives there]

## Contributing
[can be one paragraph + a link to CONTRIBUTING.md instead of inlining the whole process]

## Authors and Acknowledgment / Contact
[optional — trim if it's just a list of unrelated link dumps]

## License

## Project Status
[optional — only if development has slowed or stopped; say so explicitly and
mention if you're open to someone forking or stepping in as maintainer]

关于顺序的说明，结合两种风格：

• 安装始终排在用法之前，而用法始终排在 API/配置参考之前——读者会先评估“我能用它吗？”，再考虑“我该如何自定义它？”。
• 许可证放在接近末尾的位置，而不是开头——许可证很重要，但通常不会决定读者是否继续阅读。
• 项目状态放在最末尾（如果项目已停滞，也可以在开头附近作为提示）——这是 makeareadme.com 的惯例。如果项目已停止维护，请明确说明，不要等到用户提交问题却始终得不到回复后才让他们发现。
• 对于较长的 README，目录是值得借鉴的 standard-readme 惯例；短 README 则应省略，否则只会让页面顶部显得杂乱。
• 精简内容时（见下方第 5 步），请记住 makeareadme.com 的经验法则：太长的 README 仍胜过太短的 README——如果内容显得臃肿，通常应该把内容拆分到 wiki 或文档网站，而不是直接删掉。
• 不要仅仅因为模板里有某个章节就把它加进去。一个人的周末项目不需要路线图或行为准则链接；内部工具也不需要贡献者徽章。空白章节或模板化内容只会让文档显得更像套用模板，而不是更专业。

第 4 步：徽章（如果采用徽章较多的风格）

徽章（shields.io）最适合展示真实且最新的信息——构建状态、已发布版本、许可证、下载量——而不是纯粹装饰。指南如下：

• 使用 https://shields.io/ 或生态系统自带的徽章（npm、PyPI、crates.io 都会生成各自的徽章）。不要手工制作 SVG。
• 通常使用 3 到 5 个徽章即可；一长排十几个徽章会显得杂乱，往往也像是未经定制、直接复制自 Best-README-Template 的模板内容。
• 交付的 README 中绝不能保留占位徽章（例如 build-shield，或指向无效地址的 contributors-shield）——要么将它们关联到真实的 CI/软件包，要么删掉。
• 顺序：构建/CI 状态、软件包版本、许可证、社交信息（通常最多放一个社交徽章，例如 Discord/LinkedIn 链接，且仅在确有相关性时添加）。

第 5 步：撰写，然后精简

先完成 README 草稿，再以挑剔的陌生人的视角重新阅读，并删掉以下内容：

• 没有实质内容支撑的营销形容词（例如“快如闪电”“可用于生产环境”），除非有基准测试或过往记录作为依据。
• 只用正文重复章节标题的章节（例如“## Contributing \n 我们欢迎贡献！”除此之外别无内容——要么提供真正有用的指导，要么链接到 CONTRIBUTING.md，然后继续）。
• 从模板本身复制来的注释（Best-README-Template 中解释如何使用模板的 HTML 注释应该删除，而不是保留）。
• 无法实际访问的引用式链接定义、图片路径或徽章 URL——README 首屏中的失效链接会损害读者对其余内容的信任。

参考资料

references/templates.md 提供了完整的示例模板：库 README、CLI 工具 README 和 GitHub 个人资料 README；此外还包括 standard-readme 的必备章节清单，以及 makeareadme.com 的最简起始模板和完整章节清单。如果用户需要可直接复制粘贴的内容而非指导，或者正在编写上述某一种 README，请先阅读该文件。