README 不是门面，而是工具的首次成功路径

README 最容易骗过的人，是作者自己

作者打开自己的仓库时，环境已经装好，目录也熟，报错后知道该查哪里。于是 README 从架构图、功能列表和愿景开始，看上去信息很多。

陌生人看到的却是另一条路：这是网页还是命令行工具？应该下载压缩包还是克隆仓库？Node.js、Python、Docker 是三选一还是全都要？启动以后应该去浏览器找结果，还是去输出目录找文件？

GitHub 会在仓库首页展示符合位置规则的 README，它往往就是用户接触代码前看到的第一个产品界面。这个界面的首要任务很具体：让一个不认识作者的人，在没人提示的情况下完成第一次成功。

README 写得长不代表这条路已经存在。真正的入口必须能被陌生人独立走完。

先定义“第一次成功”是什么

写文档前，我会先写一句可观察的成功结果：

用户从一个刚打开的终端开始，在不询问作者的情况下，让示例输入产生预期输出。

这句话还要继续具体化。比如一个 Markdown 转 HTML 工具，第一次成功可以是：

• 用户准备一个示例 Markdown。
• 运行一条明确命令。
• 终端没有报错。
• 指定目录出现 HTML。
• 浏览器打开后能看到标题和正文。

“项目成功启动”太含糊。用户需要知道成功长什么样，以及结果在哪里。

一条首次路径由七块组成

1. 先说结果，不先讲愿景

顶部第一屏回答三个问题：

• 这个工具把什么输入变成什么输出。
• 谁现在会需要它。
• 最小成功大约要做几步。

“下一代智能内容基础设施”无法帮助用户判断是否值得安装。“把 Markdown 转成可预览的公众号 HTML”则可以。

2. 把不适用情况写出来

限制不是减分项。它能阻止错误用户进入一条注定失败的路径。

例如明确写：

• 当前只支持本地文件，不读取在线文档。
• 没有 Windows 实测，不保证路径行为一致。
• 不负责自动发布。
• 示例不包含真实 API Key。
• 生产数据使用前需要自行备份。

用户越早看到边界，后面的支持成本越低。

3. 前置条件必须能检查

不要只写“需要 Node.js”。至少给出支持范围和检查方法：

node --version
npm --version

还要说明命令在哪里运行，以及什么输出代表满足要求。如果项目要求特定主版本，写清版本范围；如果只是官方示例，不要假装所有版本都测试过。

4. 克隆、进入目录、安装、启动要分行

下面是结构示例，不是可直接运行的真实仓库地址：

git clone YOUR_REPOSITORY_URL
cd YOUR_PROJECT_DIRECTORY
npm install
npm run dev

占位符必须大写或明确标注。最糟糕的文档会让新手把“仓库地址”“项目目录”几个字原样复制到终端，然后认为自己不会用 Git。

每条命令旁边还应说明它改变了什么。git clone 下载仓库，cd 切换当前目录，npm install 安装依赖，npm run dev 启动开发服务。这些对作者显而易见，对第一次使用的人不是。

5. 给一个安全、可丢弃的示例输入

不要让用户第一次运行就接触自己的重要数据。项目应附带最小示例，或者告诉用户怎样创建一个无风险文件。

示例应该小到能人工核对结果。一次处理一千个文件看起来厉害，却让新手无法判断其中九百九十九个是否正确。

6. 把成功画面写出来

成功说明至少包含：

• 终端会出现哪类信息。
• 进程是否需要保持运行。
• 浏览器应该打开哪个地址。
• 输出文件保存在哪里。
• 停止程序使用什么操作。
• 再运行一次会不会覆盖数据。

如果页面打开但空白，也要告诉用户这是成功还是失败。

7. 把第一批失败按层分类

FAQ 不应该收集所有可能报错。先覆盖首次路径最常见的四层：

下载层：地址错误、仓库私有、网络不可达。

环境层：运行时未安装、版本不兼容、命令不在 PATH。

依赖层：安装中断、系统库缺失、锁文件冲突。

运行层：端口占用、配置缺失、进程退出、输出路径错误。

每一层告诉用户先保留什么证据，例如完整错误文本、运行时版本、当前目录和日志，而不是只说“重装试试”。

一个常见的坏 README 怎样改

坏版本通常这样开始：

本项目采用先进架构，支持多模型、多平台、多 Agent 协同，具有高度扩展性。

它没有告诉用户第一步做什么。

更有效的顶部可以是：

这个工具做什么
把一个本地 Markdown 文件转换为可在浏览器预览的 HTML。

你会得到什么
运行示例后，output/ 目录出现 demo.html。

开始前需要
Node.js 20 或项目当前声明的支持版本。

最短路径
克隆 -> 安装 -> 运行示例 -> 打开输出。

当前不做什么
不会登录公众号，也不会自动发布。

功能列表、架构和扩展机制可以放后面。README 不是只能写给新手，而是先让新手找到入口，再让高级用户继续深入。

怎样测试 README，而不是自己读一遍

作者自己复读文档很难发现盲点，因为脑中会自动补全缺失步骤。我更看重一次观察测试：

1. 找一个没参与开发的人。
2. 只给仓库首页，不口头提示。
3. 记录他第一次停下的位置。
4. 不立刻解释，先问他原本以为下一步是什么。
5. 把这个阻塞补回首次路径。
6. 从干净目录重新走一次。

验收不是“对方觉得文档专业”，而是他完成了定义好的第一次成功。

如果没有第二个人，也可以新建一个干净目录，暂时隐藏本机已有配置，严格只执行 README 中出现的步骤。不要依赖自己记得但文档没写的命令。

README 不应该吞掉全部文档

GitHub 也建议 README 保留帮助开发者开始使用和参与项目所需的信息，更长的说明可以进入独立文档或 Wiki。

一个清楚的分层通常是：

• README：结果、适用范围、最短路径、成功标志、常见首错。
• docs：完整配置、架构、接口、部署和高级场景。
• CONTRIBUTING：开发与贡献流程。
• SECURITY：漏洞与敏感问题的报告方式。
• CHANGELOG：版本变化。

这样 README 不会因为“什么都重要”而变成找不到入口的长页面。

发布前最后检查一次敏感信息

示例配置、截图、日志和命令历史都可能暴露 API Key、Cookie、内部地址、邮箱或本地用户名。公开仓库里删除当前文件，不代表历史提交已经消失。

在发布前检查：

• 示例密钥是否全部为无效占位符。
• 截图是否露出账号和路径。
• .env 是否被忽略。
• 日志是否包含请求头和 Token。
• 文档链接是否指向内部系统。
• 复制命令是否会修改或删除重要数据。

README 写完以后，先别问它够不够专业。找一个干净目录，只执行文档里出现的步骤。只要中途还需要依赖作者记忆，这条首次成功路径就没有写完。