good-readme

优秀 README

理念

核心原则：README 是项目的入口。它应该在 30 秒内回答“这是什么、为什么值得关注，以及如何使用？”每个章节都应满足读者的实际需求，才有存在的价值——不要用套话凑篇幅。

优秀的 README便于快速浏览、内容真实，并且考虑了目标读者。它们开门见山地说明价值主张，展示真实的用法示例，并尊重读者的时间。评估项目的开发者会在不到一分钟内决定是否进一步投入时间——README 就是你的项目推介。

糟糕的 README要么是毫无结构的长篇大论，要么是没人会看的自动生成套话，要么是寥寥几句、迫使读者去翻源代码。同样糟糕的还有过度详尽的 README：重复 /docs 中已有的内容，或在文档中逐一列出所有 API 方法。

请参阅 anatomy.md，了解各章节的撰写指南；参阅 examples.md，了解优秀项目中的模式；参阅 anti-patterns.md，了解常见问题；参阅 cloudflare.md，了解 Cloudflare 生态系统的惯例。

模式

此技能有两种模式：

1. 创建 — 新建 README

适用于没有 README 或需要从头撰写 README 的项目。

开始撰写前：

• 阅读项目的源代码，了解项目的功能
• 确定目标读者（最终用户、开发者，还是两者？）
• 检查现有文档、配置文件和 CI 设置，了解项目惯例
• 查看 package.json / Cargo.toml / pyproject.toml / go.mod 等文件，了解项目元数据
• 根据源代码整理事实清单：包名、入口点、导出的函数/类、CLI 命令/标志、配置项，以及所需的运行时版本
• 对于计划记录的每个 API、命令或导入项，在命名之前都要对照当前源代码或清单文件核实
• 询问用户：“这份 README 面向哪些人？你最希望他们理解的一件事是什么？”

撰写流程：

• 起草标题和一句话描述（吸引读者的开场）
• 撰写简洁的“是什么与为什么”章节（最多 2-4 句话）
• 添加快速入门，让读者用最少的步骤从零开始并成功运行
• 包含真实且经过测试的代码示例，而非伪代码
• 根据生态系统添加相应的安装说明
• 只添加此项目需要的章节（参见 anatomy.md）
• 定稿前将草稿交由用户审阅

2. 改进 — 优化现有 README

适用于需要完善 README 的项目。

先进行审查：

• 完整阅读当前 README
• 阅读项目源代码，检查 README 是否准确且内容是否最新
• 检查 API/CLI 是否存在偏差：提取 README 中的导入项、函数、命令、标志和配置项，并与当前公开导出项、入口点和架构定义逐一比对
• 根据质量检查清单进行评分
• 找出内容缺失、已过时或不必要的章节，以及有源代码依据的偏差
• 向用户说明发现的问题，并给出具体建议，同时指出支持事实修正的源文件/清单文件

然后进行改进：

• 首先修正事实错误（错误的安装命令、过时的 API 示例等），并注明用于验证修正的源文件或清单文件
• 解决结构问题（缺少章节、顺序不合理）
• 提高内容的清晰度和易读性（标题、代码块、列表）
• 删除没有价值的套话
• 只有在确认相关项已导出或定义后，才用当前的导入项、函数、签名和命令重写过时示例；不要为缺失的名称编造兼容性封装
• 验证所有代码示例均可运行，或说明哪些检查无法执行
• 将修改交由用户审批

核心原则

1. 以价值为先 — 前 3 行决定读者是否会继续阅读
2. 展示胜于描述 — 代码示例 > 文字描述
3. 如实说明范围 — 说明项目能做什么，也说明不能做什么
4. 遵循生态惯例 — npm 项目与 Rust crate 的呈现方式不同
5. 保持维护 — 会误导读者的 README 比没有 README 更糟
6. 链接而非重复 — 深入内容请参阅 docs/，让 README 聚焦
7. 测试示例 — 有问题的代码示例会立刻摧毁信任
8. 以源代码为准，而非记忆 — README 示例、以前的文档和模型记忆都应视为不可靠，直至对照当前源代码和清单核实

以源代码为依据的 API 漂移处理流程

每当 README 提及可能已与代码不一致的函数、类、导入语句、命令行命令、标志、配置键或示例时，都使用此流程。

1. 提取文档中的符号 — 编辑前列出 README 中的每个导入语句、公共 API 名称、命令、标志、选项和配置键。
2. 查找权威定义 — 检查包清单（exports、bin、入口点）、公共导出文件（__init__.py、index.ts、lib.rs、go.mod 模块路径）、命令行解析器、配置架构和类型声明。
3. 确认是否存在及其签名 — 查找定义，而不只是字符串匹配。核实导入路径、参数名称、必需选项、返回值／输出格式和弃用说明。
4. 明确归类漂移情况 — 将每处不一致标记为已重命名、已移除、已迁移、签名已变更、未记录或不明确。提供源文件证据，例如 src/package/__init__.py 或 package.json#bin。
5. 依据源代码重写，而非猜测 — 使用当前导出的 API 替换过时示例。只有在说明漂移／迁移情况时才提及旧名称；除非源代码证实兼容，否则不得将其描述为当前名称。
6. 如实处理不确定性 — 如果源代码未揭示替代方案，请说明这一点并询问用户，或留下供维护者处理的占位说明。不要臆造包装器、别名、基准测试、兼容性声明或实现。
7. 验证修正后的代码片段 — 条件允许时，运行文档中的命令／示例。如果无法运行，请明确说明未进行的具体验证。

报告审查结果时，对于 API 漂移发现，请附上简洁的“已检查源代码”说明或表格，列出过时的 README 符号、当前源代码中的符号、证据文件和修正后的代码片段。

分节检查清单

[ ] Title is clear and descriptive (not clever)
[ ] One-liner explains what + why in plain language
[ ] Quick-start gets reader to "it works" in ≤5 steps
[ ] Code examples are real, tested, and copy-pasteable
[ ] Installation covers the project's actual ecosystem
[ ] No orphan sections (every section serves a purpose)
[ ] Badges are useful, not decorative
[ ] License is stated
[ ] Contributing section exists if accepting contributions