大多数 README 都栽在安装这一步。读者在第 3 行碰到一个缺失的 peer 依赖就走了，根本没看到真正出彩的部分。修法并不花哨：能跑的安装步骤放最上面，第一屏就给能跑的 quickstart，“安装失败怎么办”那一块要放在任何营销文案之前。下面 12 个 Prompt 会逼出这个顺序。日常维护可以配合 代码审查 Prompt 和 Changelog Prompt 一起用。
一句话总结
- 一份好的 README，在第一屏就回答三个问题：这是什么、怎么装、装好后怎么跑一次。
- 顺序比篇幅更重要。安装和能跑的 quickstart 要排在特性、badge、项目故事之前。
- Prompt 1–3 是骨干（骨架、quickstart、安装排错），先跑这三个；其余按需取用。
- 把真实入口和公开导出喂给能读代码的 agent，它才会照你真实的 API 写，而不是凭空猜。
该用哪个 AI 工具来跑（2026 年 6 月）
下面的 Prompt 你用惯了的模型都能粘进去跑。但凡是要反映真实代码的，优先用能读仓库的 agent，而不是只粘一个文件：
- Claude Code 只跑 Anthropic 自家模型（日常起草用 Sonnet 4.6，需要跨多文件推理时用 Opus 4.7）。截至 2026 年 6 月，两者标准上下文都是 100 万 token，能一次装下一个中等规模仓库。随 Claude Pro 套餐（每月 20 美元）一起提供。
- Cursor（Hobby 免费、Pro 每月 20 美元）在本地为整个项目建索引，可以用 @ 引用文件。于是像”用
src/index.ts写 quickstart”这样的 Prompt 不用手动复制就能拉到正确代码。 - ChatGPT（免费、Plus 每月 20 美元、GPT-5.5）和 Gemini 3.1 Pro（Google AI Pro 每月 19.99 美元）适合下面那些纯模板类 Prompt——这类需要你自己把代码片段粘进去。
对于写着 粘贴 的 Prompt，已经有仓库访问权限的 agent 可以直接跳过粘贴这一步。生成的 quickstart 在提交前，务必对照线上真实代码核一遍。
这套 Prompt 适合用在哪
- OSS 库与框架
- 公司内部工具
- 独立产品与副业项目
- 模板、starter、boilerplate
- 发布到 npm、pip、cargo 的 CLI 工具
1. 最小 README 骨架
项目：[name]。1 句话：[x]。目标读者：[who]。
请按此顺序只生成这些节：
1. Tagline（1 句，不超过 80 字符）
2. Install（最多 3 条命令）
3. Quickstart（不超过 30 行代码，演示最常见用法）
4. What's next（3 条链接：深入文档、示例、贡献）
不要"About"、不要"Features"清单、暂不要 badge。2. 一屏 quickstart
下面是项目入口 + 关键公开 API。
请写不超过 30 行的 quickstart，端到端演示最常见用法（import、init、调用、打印结果）。
读者粘贴就能看到输出，不用读别的。
代码块后加 3 行，解释刚才发生了什么。
入口 + API：[粘贴]3. 安装排错块
项目 install 步骤：[清单]。需要的语言 / 运行时：[列版本]。
加 "If install fails" 段，覆盖此技术栈最常见的 5 种失败：
- peer 依赖冲突
- 版本不匹配（Node / Python / 运行时）
- 缺系统依赖（build tools、libssl 等）
- 权限 / sudo 问题
- 网络 / 代理 / 企业防火墙
每种给：如何识别（错误信息片段）、如何修（1-2 条命令）。4. 示例长廊
为 [name] 生成 5 个简短示例，覆盖不同用法（不是同一种的 5 个变体）。
每个：(a) 1 段背景——谁在什么场景下用，(b) 完整可跑代码块，(c) 1 行说明预期输出。
由简到难排序。每个相关联 1 个更深文档的链接。5. API 速查表
下面是模块的公开导出。请生成 1 张速查表，列：
名 | 类型（函数 / 类 / 常量） | 1 行描述 | 深入文档链接
排序：按使用频率，不按字母。
废弃 API 用删除线标记，加"改用 X"。
模块导出：[粘贴]6. 与替代品对比
[name] 与 [A]、[B]、[C] 竞争。诚实、不吹。
请写对比节：
- 1 段引言："如果 X 用 [name]，如果 Y 用 [A]"
- 4 行表，维度：速度、易用、范围、生态成熟度
- 用 对勾 / 叉 / 部分 标各家赢点
- 至少有 1 行替代品赢
末尾给替代品官网链接。7. CONTRIBUTING
请生成 CONTRIBUTING 段，不超过 200 字，覆盖：
- 本地搭（clone、装 dev 依赖、起 watcher）
- 跑测试（全套 + 单条）
- 代码风格（linter / formatter 命令，不写规则）
- PR 清单（加了测试、更新 CHANGELOG、conventional commit）
- 怎么找 "good first issue"
余下链接到详细的 CONTRIBUTING.md。8. 审计已有 README
按清单审下面这份 README：
- 第一屏能找到 install 路径吗？
- 有可粘贴就能跑的 quickstart 吗？
- 常见 install 失败处理了吗？
- API 面 30 秒内能扫完吗？
- 对比节是据实，还是夸张？
每条失败给具体行号 + 1 行改写。
README：[粘贴]9. badge 与 shields 策略
为 [name]（[语言、包管理器]），建议哪些 badge 该放 README 顶、哪些是噪声。
输出：badge | 给读者传递什么信号 | 放（yes / no / only-if-X） | 理由。
最终清单不超过 5 个。优先影响 install 决策的（CI、版本、协议），而不是虚荣指标（下载、star）。10. 封装 LLM 的库的 README
项目：一个 [语言] 库，封装 [LLM API]。
请生成 README，处理大多数封装库忽略的 LLM 特有问题：
- API key 设置（env var、.env、密钥管理器）+ 安全警告
- 成本预期（每次调用估算、何时启用缓存）
- 限流与重试行为
- 流式 vs 阻塞模式
- "什么场景下不要用这个"段
Quickstart 不超过 30 行。展示 1 个流式和 1 个阻塞示例。这一类 README 漂移得最快，因为模型名和价格一直在变。给个参照，方便你的封装库引用：截至 2026 年 6 月，Claude Opus 4.7 的 API 是每百万输入 / 输出 token 5 / 25 美元，Sonnet 4.6 是 3 / 15，GPT-5.5 是 5 / 30，Gemini 3.1 Pro 是 2 / 12。让模型给每个这类数字都标上”截至 [日期]“，读者才知道这是某个时间点的快照，而不是承诺。
11. CLI 工具 README
项目：名为 [name] 的 CLI，做 [什么]。
请生成 CLI 形态的 README：
- Install（homebrew / npm / pip / curl 一行，按分发方式）
- 30 秒用法：3 个示例调用，每个附预期 stdout
- 参数表：flag | 类型 | 默认值 | 作用
- 配置文件（若有）：路径、格式、示例
- 退出码
- 1 个真实错误 + 修复的排错示例12. 旧版本 README 改写
下面是当前 README，18 个月没动了。项目期间 [变了什么]。
请改写到反映今天的现实，不要让文件膨胀：
- 删失效链接和废弃 API
- 替换过时 install 指令
- 砍不再适用的节
- 自然位置加入 2-3 个最重要的新特性
输出：改写后的 README + 删了什么 / 为什么删的简短 changelog。
当前 README：[粘贴]
近期变更：[粘贴]怎么读生成出来的草稿
模型很乐意凭空编一个不存在的 import 路径或参数。提交之前：
- 在一个干净 checkout 里自己跑一遍 quickstart。一报错，说明 README 已经坏了。
- 在生成的代码里 grep 那些不在你公开导出里的符号。
- 如果跨平台发布，每条 install 命令都在第二个操作系统上确认一遍（Windows 或企业网络这条路，正是 README 悄悄流失读者的地方）。
- 检查每个版本号或价格数字是否带”截至”日期。
容易踩的坑
- install 前有大段营销，没耐心的读者直接跑了。
- Quickstart 跑不起来，因为引用了已删 API 或漏了 import。
- 没有”安装失败怎么办”，那 20% 在 Windows / 企业网络里的读者会悄无声息地放弃。
- API 速查按字母排而不是按使用频率，读者刚好滚过他要找的那条。
- 对比节假装竞品没有任何赢点，整个 README 读起来就像广告。
常见问题
README 该写多长？ 长到一个陌生人能装好、能跑一次就够，再长就多余。如果项目有详细文档，README 是一个指向它们的着陆页，而不是它们的替代品。第一屏是大多数读者唯一会看的部分。
能让 AI 完全无人监督地写完整份 README 吗？ 不能。结构、安装失败那一段、API 表，这些用 AI 能真正省时间。但提交前一定要在干净 checkout 里跑一遍 quickstart。最常见的翻车是：粘贴版 quickstart 引用了项目早就删掉的 API。
这些 Prompt 该用哪个模型？ 纯模板类 Prompt（badge、对比、贡献），任何当前模型都行：GPT-5.5、Claude Sonnet 4.6 或 Gemini 3.1 Pro。需要真实代码的 Prompt（quickstart、API 表、旧版改写），用 Claude Code 或 Cursor 这类能读仓库的 agent，让它照你真实的导出写，而不是猜。
怎么让 README 不过期？ 把它当代码对待。加一个 CI 步骤，每次发版都跑一遍 quickstart；每次发大版本时用第 12 个 Prompt 走一遍。再配合 Changelog Prompt，让 README 和 changelog 一起更新。
哪一节杠杆最高？ “安装失败怎么办”那一块。它只占几行，却救回了那些本会无声离开的读者——而这些人恰恰是你永远听不到反馈的那群。