readme-optimization

README 优化

你要处理的是那张决定开发者会尝试一个项目还是关闭标签页的单页。根据证据诊断现有 README，然后重写它，让陌生人能够快速、准确地评估项目——包括决定_不_使用它；这是正确的结果，绝不应为了优化指标而忽略。

README 不是一种文档类型。它是一个落地页和导航入口：几秒内回答是什么、为什么，然后引导读者继续了解。评判它的标准，是它能否让访客开始试用，而不是文档是否齐全。

把重写精力花在稀缺之处。对 393 个抽样 GitHub 仓库的调查（Prana 等人，2019 年，引用见 ./references/published-findings.md；该样本来自 2010 年代后期，应视为基线，而非全面普查）：

• 项目是什么：97.0%——基本要求。
• 如何使用：88.5%——基本要求。
• 为什么选择它而不是其他方案：25.7%——稀缺。
• 项目目前处于什么状态：21.4%——稀缺。

这两个稀缺类别，正是评估项目的开发者在采用任何方案之前必须了解的内容。

将工作限制在此页面及其仓库周边信息——描述、网站链接、主题和社交预览。当用户真正需要的是文档站点、入门指南、贡献流程、发行说明、发布活动或个人资料 README 时，请将他们引导至 Reference 下的配套 skill，而不是把 README 的覆盖范围无限扩大。GitHub 页面周边的平台功能——讨论区、发行通知、星标政策——应由 samber/developer-platform-skills@github-engagement-playbook 负责。

不要引用的民间统计数据

在自己的推理中或对用户交流时，绝不要重复以下民间统计数据——这三项说法都广为流传，但其出处是捏造的：

• “README 写得详细的仓库，贡献者多 50%”
• “星标历史图表能让星标转化率提高约 15%”
• “排名靠前的仓库中有 62% 带有 GIF 演示”

用户引用其中任何一项时，请说明它没有来源，不要以此为依据。此 skill 引用的每个数字都标注在 ./references/published-findings.md 中；向用户复述统计数据前，请先阅读该文件。

承诺让项目得到更好的评估，而不是承诺提升某个百分比。

调用示例和输出格式

常见请求：

• “审核这个仓库的 README”
• “我们的 GitHub 页面有流量，但没人安装”
• “在发布前重写 README 开头部分”
• “让评估我们项目的公司人员也能看懂 README”

每次运行都必须先输出评分卡，再撰写任何正文，格式如下：

README audit - acme/flowmatic   (audience: solo developer)
Band A: A1 pass · A2 FAIL (install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Verdict: does not pass - A2 and A3 blocking; B1 returns the most per hour spent

只有在用户认可诊断结果后，才继续重写。完整报告格式，包括声明核查、Band B 和修复顺序，见 ./references/audit-scorecard.md。

访谈

一次只问一个问题；能用选择题的尽量用选择题，并跳过那些你通过阅读仓库就能自行判断的问题。问题 1-4 决定是否重写——得到答案之前不要起草文案。

记忆：记录一些当前任务或项目背景信息。记忆保存在文件中时，请使用 devrel-context.md；如果使用的是其他记忆系统，则依赖该系统。将不同任务的信息分别放在不同部分。完成的任务要移除。为任务添加日期；一般项目背景信息不加日期。有些访谈回答可能因任务而异。

1. 是哪个仓库？我可以读取它并在其中运行命令吗？
2. 这个项目属于哪种类型：库或 SDK、CLI 工具、应用或服务、框架或平台，还是模板和学习资源？
3. 谁会来到这个页面：某一种语言生态系统中的开发者、使用多种语言的开发者、平台或运维工程师，还是安全和采购等非开发者评估人员？
4. 用户如何采用这个项目——由个人开发者自行安装并做决定，还是由公司采用，并由其他人审核许可证、安全状况和支持方案？两者兼有也是有效答案，而且会影响页面中间部分的内容。
5. 你希望获得哪种成效：更多安装、贡献者、星标、招聘吸引力、企业洽谈，还是更少重复的支持问题？
6. 项目目前的真实状态是什么：实验阶段、积极维护、稳定且功能冻结，还是正在寻找维护者？
7. 读者已经熟悉哪些替代方案？它们在哪些方面比你的项目做得更好？
8. 出于法律或政策原因，必须包含哪些内容——许可证条款、商标声明、出口或合规声明、雇主披露？
9. 是否已有需要 README 与之保持一致的品牌素材——徽标、标语、网站上使用的定位语？
10. README 是否也会发布在其他地方：软件包注册页面、镜像、文档网站着陆页？不同的呈现目标有不同规则。
11. 是否有必须完成此事的日期——发布、会议、融资洽谈等？还是说这个页面只是早该更新了？
12. 你想在那个日期之前取得一次性的成效，还是打造一项持续产生价值的资产：一句定位语和一种页面结构，供未来两年反复使用？
13. 你的资源上限是什么——一个下午、一周的人力、征求客户授权使用徽标的权限，还是你愿意承担无法轻易撤销的治理或基金会承诺？

回答 11-13 会重新排列以下所有事项的优先顺序；制定计划时，请说明哪个回答改变了哪项修复的优先级。

• 时间紧迫（问题 11）——优先处理一小时内可完成的修复，本轮不做漏斗重构。
• 持续增值（问题 12）——优先撰写差异化段落并重构页面；其中的一句话定位语还会延伸到软件包注册页面、发布公告和每个链接预览中。
• 资源有限（问题 13）——直接删掉终端演示和企业信号，而不是把它们放在列表底部。

如果用户答不上问题 7，就把它视为一项发现，而不是阻碍。维护者通常说不出替代方案，README 往往也无法凸显项目的差异化；这是你最值得解决的问题。

步骤 1 - 声明受众，然后确认 README 是否是瓶颈

回答 4 决定整个审查的方向。企业评估者和独立开发者需要的内容结构截然不同，为其中一方优化会损害另一方：业余爱好者会被满屏的合规徽章劝退，而采购人员则会因页面没有安全或治理方面的信息而心生疑虑。请在评分表顶部写明声明的受众，这样之后的每项判断都能据此核查。

然后确认问题确实出在 README 上。如果代码托管平台提供流量数据，请查看过去两周的独立访客数和克隆数。

• 流量尚可，但克隆数与访客数的比率只有百分之几：这正是此技能要处理的情况——人们来了，却没有被说服。
• 一开始访客就很少：这是分发问题，不是文案问题——应将用户引导至发布或分发相关工作，而不是重写几乎没人阅读的页面。

“百分之几”只是实用经验值，并非基准；如果数值处于临界位置，应查看引荐来源，而不是直接下结论。

步骤 2 - 收集证据

绝不要凭对优秀 README 的印象来进行审查。

1. 通读 README，并记录你自己感到困惑的地方。你首次阅读时的困惑，是最接近真实新读者体验的参考。
2. 运行机械审查：scripts/readme-audit.sh <repo-root>。它会报告：
   • 被遮蔽的副本
   • 截断风险
   • 标题层级
   • 与中位数 7 相比的章节数
   • 第一个可复制命令之前的字数
   • 徽章数量
   • 缺失的替代文本
   • 不利于软件包注册表显示的原始 HTML
   • 失效的相对链接
   • 占位文本
   • 缺失的内容类别
3. 查看 README 所在的代码仓库：用于确认实际运行时要求的清单文件、许可证文件、近期提交日期、未关闭议题数量，以及 README 引用的示例是否确实存在于磁盘上。
4. 如果你的环境可以浏览网页，请打开项目的软件包注册表页面，并将其与代码托管平台上的渲染效果进行比较。相对链接和原始 HTML 经常会在注册表页面上出错，而且该页面的流量往往更高。如果已发布的软件包中缺少 README，这是打包问题：交由 samber/developer-platform-skills@sdk-package-publishing 处理。
5. 如果你的环境具备持久记忆，请复用已存储的项目定位陈述、受众定义或竞品列表，而不要重新推导。

你可以选择加入结构化 README 评分工具和代码托管平台的社区标准检查清单，作为第二种意见，并将二者视为基本规范检查——请参阅 ./references/tooling-and-measurement.md 中关于有效性上限的说明。脚本报告的是事实，而非判断：章节数为 25 是一个需要回答的问题，不是判决。

步骤 3 - 为当前 README 评分

按照 ./references/audit-scorecard.md 逐项审查，并按上述格式填写评分表。

• A 档：五项阻断性检查——身份说明、安装后确实能运行、每项声明都可核实、状态如实、许可证可访问。
• B 档：八项评分检查，每项 2 分。

为每项检查附上证据——行号、引用的句子，或你运行的命令的终端输出。在重写之前先取得用户对分数的认可：维护者若不接受诊断，就不会接受处理方案；他们有时确实是对的，因为仓库中看不出的限制，可能足以说明某项检查得 0 分是合理的。

对修复项排序

按照每小时投入带来的回报来排列修复项，而不是按编写难度或修复的损害程度排列——这三种排序并不一致，因此要全部列出，并以第三种排序为准：

• 投入，最少优先：status line == badge row > claim check > install path > differentiation paragraph > funnel restructure
• 价值，最高优先：install path > differentiation paragraph > claim check > status line > funnel restructure > badge row
• 效率，优先处理：status line > install path > claim check > differentiation paragraph > badge row > funnel restructure

状态行和徽章行的投入相同：各自只需编辑一个区块，根据维护者已有的知识编写，无需核验任何内容——不用运行命令，也不用阅读源码。它们的价值则不同：状态行回答的问题只有 21.4% 的 README 会回答，而徽章行回答的问题有 61% 的贡献者会忽略。

首次修改时，默认优先处理前三项；等阻塞性检查全部通过后再继续，或者在冷读者测试中，有问题未能由这三项中的任何一项解决时再继续。

漏斗重构在每轮排序中都垫底——它需要一两天，而其他修复一小时内就能完成——因此这种排序对最能让页面发挥作用的改动投入不足。如果冷读者答错，是因为他们根本没往下滚动到足够远的位置，或者审核是为了上线而做，就应提高它的优先级，并说明这是违背投入产出比的调整。

这个排序是默认方案，不是铁律，而且会随执行者不同而变化。根据你已知的情况重新排序：

• 能用一句话说出替代方案的维护者，几乎不费力就能写出差异化段落，因此应将它排在安装路径之前。
• 没有安装命令的项目——例如规范、数据集或模板——应直接删除该项，而不是永远给它打零分。

如果答案 13 中的上限规则排除了某项修复，就删除它，而不是把它列在最后。

第 4 步 - 根据源码核验每项声明

README 是一组关于代码库的声明，每项都可以核验。Agent 和维护者同样会凭记忆编写内容，因为 API 通常看起来是什么样；读者无法分辨某一行是经过核验还是凭空编造的，而你可以，因为你有代码仓库。

列出每项声明：

• 命令
• 标志
• 默认值
• 环境变量
• 配置键
• 端点
• 导出符号
• 文件路径
• 版本要求
• 隐藏在动词中的行为断言，例如“自动重新连接”“重试三次”“不区分大小写”

根据每项声明各自的事实来源进行核验——参数解析器、定义位置、路由表、变更日志——通过阅读核验，而不是凭记忆。README 中记录了某个标志，但解析器中却没有，这属于幻觉，不是笔误。

然后实际运行安装路径，因为这最能发现真实问题：

1. 从干净状态开始——容器、新建的虚拟环境、临时目录，或环境支持的其他方式。如果无法执行命令，就明确说明，并请用户运行这组命令后粘贴输出；绝不要仅凭检查就将此项标记为通过。
2. 严格按照文档原样执行安装命令，然后严格按照文档原样执行第一个使用示例。
3. 记录所有差异：文档未说明的运行时版本、默认存在的系统软件包、必需的环境变量，或与 README 不符的输出。
4. 将每项差异明确写入 README，作为前置条件或核验步骤，然后再次从干净状态运行整套流程。

重复上述步骤，直到文档中的路径无需任何未记录的步骤即可端到端运行。任何性能数据、兼容性矩阵、规模限制或“可用于生产环境”的声明，都必须有代码仓库内的来源——例如基准测试脚本、CI 矩阵或变更日志——否则就应删除。如果无法核验某项内容，就将声明缩小到可核验的范围，并说明哪部分尚未确认。

步骤 5 - 选择结构，然后逐节改写

从 ./references/readme-skeletons.md 中选择与读者正在_做出的决定_相匹配的骨架，而不是与代码碰巧采用的结构相匹配的骨架。

• 阅读库介绍的读者，正在判断它是否适合现有代码库。
• 阅读 CLI 介绍的读者，正在将它与已安装的工具进行比较。
• 阅读框架介绍的读者，正在做出影响数年的选择。

按读者能多快据此排除项目的顺序安排各个章节。这就是 Kira 在 Art of README 中所说的认知漏斗：先呈现范围最广、最能排除项目的信息，再逐步深入细节，只有决心继续阅读的人才会看到这些细节。因此，不宽松的许可证应放在靠前的位置，因为它能最快让读者排除项目；把它藏起来只会浪费读者的时间。

动笔之前，先明确构思项目的定位，而不是直接采用第一个想到的说法。围绕不同角度拟出三个候选的一句话介绍：

• 它在机制上做什么
• 它消除了什么问题
• 它让你不再需要使用什么

展示每个版本及其取舍，并给出你的建议，让用户选择。这句话会延伸到仓库简介、注册表页面和每个链接预览中。

每次只起草一个章节，并在继续之前征得认可；逐节审批能趁分歧仍然容易解决时及时发现。对每个章节：

1. 写出完整回答该章节问题所需的最短版本。
2. 将每个无法证伪的说法（“简单”“快如闪电”“对开发者友好”）替换为读者能够核实的内容——一个数字、依赖项数量、受支持平台列表，或明确的取舍。
3. 为项目所属生态圈之外的读者可能不熟悉的每个术语添加链接。
4. 说明项目有意不做什么，以及何时应改用其他方案。这是大多数 README 中最能建立信任的一句话，而且只需一行。
5. 将篇幅超过一屏的内容移到有链接指向的文档中，并留下一行指引。内容过长就移出去，绝不删除。

不要把社区健康相关内容放进这个文件——贡献指南、行为准则、安全漏洞披露和支持政策。每项内容都应放在各自被广泛认可的文件中，代码托管平台会在相关时机展示这些文件；将它们内嵌只会增加读者做出决定前的滚动距离。只有一个例外：许可证文件必须随仓库一起发布，因此仅设置组织级默认许可证并不足够。

呈现之前，先用你偏好的人工润色技能检查完成后的文案。读起来像机器生成的文案会削弱页面其他内容正在建立的可信度，而且开发者很容易察觉。

请参阅 ./references/before-after-examples.md，其中提供了开头句、差异化章节、状态说明、徽章行、安装代码块和用法片段的正反示例。

第 6 步——让徽章与证据相符

徽章是 README 中唯一有严谨证据支持的元素：Trockman 等人研究了 294,941 个 npm 包（ICSE 2018）。应依据研究中的区分，而不是个人喜好。

• 保留评估信号——由第三方检查支持，且只有底层事实成立时才能通过的徽章：CI 状态、覆盖率、已发布版本、依赖项新鲜度。
• 移除惯例信号——仅仅表达意愿的徽章，例如“欢迎提交 PR”，却没有任何验证机制。它们毫无信号价值。
• 限制徽章行的数量。在已经广受欢迎的包中，过度使用徽章与人气_下降_相关，而采用徽章并不会提高人气——只是热门项目更有可能带有徽章。研究给出了这种关联方向；此处将最多四个作为实用默认值，而非已发表的数据，因此应说明每个保留的徽章回答了读者的什么问题，而不是争论数量。
• 预计维护者会高估徽章的价值。研究附带的小型调查发现，维护者远比贡献者更常将徽章视为质量指标，而且大多数贡献者表示徽章对他们毫无影响。维护者若不愿删减徽章行，请引用 ./references/published-findings.md 中的数据。

第 7 步——整理仓库配套信息和渲染机制

有三件事要争夺这一步的时间，但优先级并不接近：

• 效率优先，先做：furniture > render mechanics > terminal demo

• 配套信息几乎不费力，却能改善读者打开仓库前唯一能看到的内容：搜索结果中会显示描述、网站链接和主题标签，而社交预览则会在有人把链接粘贴到聊天中时展开显示。

• 渲染机制大约需要一小时，能让那些看不到代码托管平台渲染效果的读者正常阅读页面——包括注册表页面、终端和屏幕阅读器。

• 终端演示要花一两天才能做好，之后还会成为一项长期维护工作，每当输出发生变化就会过时。

这个顺序最容易牺牲的是演示；但对于 CLI 或可视化工具而言，演示是页面上价值最高的元素，因为输出_本身_就是产品。只有在这种情况下，才应将演示排在渲染机制之前；并用脚本生成，而不是手动录制，这样重新渲染的成本才足够低，能将其作为长期维护工作保留下来。对于没有可见输出的库，应删除演示——展示一条导入语句毫无价值——而不是留着它，让它日后再次成为工作范围的一部分。

先整理配套信息，再处理文件本身的渲染方式：

1. 为每张图片添加替代文本，并将截图和动画演示中的所有说明、命令或与决策相关的事实移到文本中。读者会在终端、会剥除 HTML 的注册表页面以及屏幕阅读器中查看 README——这三者都无法看到动画演示。
2. 删除手写的目录；代码托管平台会根据标题生成大纲，而手动维护的副本会逐渐过时。
3. 检查相对链接是否能从默认分支上的仓库根目录解析，并确认剥除原始 HTML 后页面仍然易于阅读。
4. 只保留一个渲染版 README。如果托管平台优先渲染 .github/ 中的副本，注册表和镜像发布的仍是根目录中的副本，因此两个版本会在不知不觉中分歧。
5. 在单体仓库中，应让根目录的 README 指引读者前往各个包的 README，而不是在根目录中逐一介绍所有包。

如果演示确实值得保留，就应让它简短、对比鲜明，并在嵌入显示尺寸下清晰易读；将它放在标语之后。应把它带来的转化收益视为从业者共识，而非经过测量的结果——没有研究对其进行量化，这也是默认情况下不应让它排在成本更低的两项之前的另一个原因。

步骤 8 - 仅在受众需要时添加企业信任信号

仅当步骤 1 声明受众是公司或采购人员时，才运行此步骤。

企业决策者看重的是决策的可辩护性，而非技术匹配度最高，因此，第三方认可信号——基金会级别、审计、证明、知名采用者——比新颖的宣传更有说服力。已发布的评估清单对维护活跃度、许可证清晰度和安全状况的权重高于呈现质量；相关来源见 ./references/published-findings.md。

有六种信号可供选择，其成本相差两个数量级：

• 工作量，从低到高：support expectation == release cadence > security policy > supply-chain attestation > named adopters > governance and maintainer depth > foundation affiliation
• 价值，从高到低：foundation affiliation > named adopters > security policy > governance and maintainer depth > supply-chain attestation > release cadence == support expectation
• 合规成本：
  • 基金会关联需要转让商标或 IP，并获得无法撤回的法律签批
  • 知名采用者需要获得每家公司的营销审批；虽然可以撤回，但只能再次提出请求
  • 安全政策会公开承诺响应时限，之后必须兑现
  • 其余三项无需审核，提交一个 commit 即可撤回
• 效率，优先顺序：support expectation == release cadence > security policy > named adopters > supply-chain attestation > governance and maintainer depth > foundation affiliation

支持预期和发布节奏的优先级两次并列：它们各自只需一句话说明已经成立的情况，不需要任何人的许可，除了查看 commit 日志外也无需额外工作。供应链证明需要大约一天来设置和测试发布流水线；知名采用者则需要大约一周时间，逐一向各家公司申请审批。知名采用者的效率仍排第一——证明能说服原本就会同意的工程师，而知名 Logo 能说服签字的人。

默认选择前三项，总计花一个下午即可完成，足以满足评估清单中大部分要求。当有交易在谈，且有人问“还有谁在用这个项目”时，再加入知名采用者。

基金会关联是这套排序中最难优先推进的项目：它在页面上是最强的信号，却需要四分之一或更多的工作量，因此按投入产出比永远排不上前列，而以 README 为驱动的计划也不会做到这一步。当项目被作为基础设施而非依赖项采用时，或当基金会级别正是你屡屡败给竞争对手的原因时，再优先考虑它——然后把决定权交给用户，因为它的可撤回成本并非文档成本。

删除所有被规则 13 排除的信号，不要把它们列为未来工作：没有处理法律事务的意愿，就不要列出基金会关联；独立维护者应如实写明支持预期，而不是添加空洞的治理标题。

步骤 9 - 重新评分并进行冷读者测试

重新运行评分表。README 通过的条件是五项阻断性检查全部通过，且评分项总分至少达到 14/16——这是这里采用的默认标准，并非已发布的门槛，因此如果用户有明确理由要调整，应允许其调整并在报告中记录。

然后按照评分表中的定义进行冷读者测试——五道问题，限时 60 秒，答对五道才算通过——如果用户能找到人，就请真人测试；否则开启一个没有仓库上下文的新 Agent 会话。每道错题都对应一项具体检查，因此测试失败能明确指出需要修复的地方。

如果你的环境具有持久记忆，请存储双方认可的一句话定位、受众定义、竞争对手列表和最终分数。相关工作——发布公告、文档落地页、会议摘要——都应基于这一定位展开，而不是另起炉灶。

后续要跟踪的指标

README 上的归因力度很弱。记录上线日期，对比前后各一个完整周期，并标注混杂因素，而不是声称变化是由某项改动造成的。四到六周后重新测量；更短的时间窗口只会带来噪声。

• 效率，优先跟踪：support load > conversion rate > contributor conversion

• 支持负担的跟踪成本为零，而且几周内就会变化：统计每月“如何安装这个”以及“这个是做什么的”这类问题的数量，并观察其是否下降。

• 转化率——克隆或下载量除以独立访客数——用主机的流量数据整理出来只需一小时，是最真实的单一数字，但在前后各经过一个完整周期之前，它说明不了任何问题。

• 贡献者转化见效最慢，也最容易受到混杂因素影响；过一个季度再查看。

彻底从跟踪计划中删除星标，即使回答 5 将星标列为目标也是如此：星标只会增加，因此该指标无法显示退步，而且即使改动让页面变差，也会报告成功。改为提供转化率。

如果克隆量上升，但贡献者数量没有变化，那么出问题的是贡献流程，而不是 README。测量方式及其注意事项见：./references/tooling-and-measurement.md。

常见失败模式

未诊断就重写。 重写修好了文案，却保留了有问题的安装流程，那就什么也没解决。在审查模式下，除非有人提出要求，否则完全不要重写。

为了显得严肃而堆砌内容。 一半的 README 介于 5 到 12 个章节之间，中位数为 7。单一用途项目的 README 只有四个章节也很完整；给一个 200 行的实用工具添加架构和路线图章节，会让它看起来像是无人维护，而不是更成熟。

营销腔。 对这个受众而言，没有证据支持的最高级表述只会显得空洞，还会直接降低信任度。每项声明都应该可以核实，否则就删掉。

只检查一种渲染环境。 注册目录页面的流量通常更多，规则也不同。只在一个托管平台上正常显示的 README，对很大一部分读者来说就是坏的。

捏造状态。 绝不要写“可用于生产”“经过实战检验”，也不要写未经用户提供的用户数量。只要看一眼提交历史，夸大的声明就会被戳穿，造成的信任损失远大于诚实地称其为“早期测试版”。

优先处理最省事的修复。 徽章行是清单中最快能完成的事项之一，价值却几乎最低。按照“修复顺序”来安排展示顺序，而不是按照你最先能完成的顺序。

参考资料

• ./references/audit-scorecard.md - 评分标准、阈值、冷读者测试和报告格式。
• ./references/published-findings.md - 所有有来源的数据以及常见误传列表。
• ./references/readme-skeletons.md - 各项目类型的章节顺序。
• ./references/before-after-examples.md - 正面和负面实例详解。
• ./references/tooling-and-measurement.md - 评分、代码检查和归因工具。
• ./scripts/readme-audit.sh - 评分标准所依赖的机械检查事实。
• samber/developer-relations-skills@developer-quickstart-guide - 专门的入门指南页面。
• samber/developer-relations-skills@developer-docs-structure-audit - 文档站点结构。
• samber/developer-relations-skills@oss-contributor-onboarding - CONTRIBUTING.md 和首次贡献流程。
• samber/developer-relations-skills@changelog-writing - 发布说明和变更日志结构。
• samber/developer-relations-skills@oss-launch - 发布规划与执行。
• samber/developer-relations-skills@oss-distribution-strategy - 哪些渠道会将读者引导至这个仓库页面。