agent 写的 README 为什么装不上：一条"没有出处就删掉"的规则
用 agent 生成 README，结果经常是：章节齐全，照着做却跑不起来。
安装命令指向一个从没发布过的包，配置项在代码里搜不到，路线图里的功能被写成已经能用。读一遍没觉得哪里奇怪，动手第一步就报错。
我把这类失败归到证据上：写之前没有核对仓库里到底有什么。文笔不是瓶颈。
为了验证这个判断，我做了一个开源 Skill（README Atlas），用一条规则约束自己：README 里的每个命令、每项功能声明、每个环境要求，都必须能在仓库里找到出处；找不到出处的，删掉，而不是换个说法。
下面是我在做的过程中的几个具体决定，以及为什么。
一、先建事实地图，再动笔
写第一句之前，先读这些：package manifest（package.json / pyproject.toml / Cargo.toml）、入口脚本、示例目录、测试、CI 配置、已有文档、release 记录。
读完会得到一张事实地图：
- 项目怎么启动（哪个文件、哪个命令、需不需要先装依赖）
- 最低运行时是什么（版本号来自 manifest 里的字段，不来自印象）
- 哪些能力有代码和测试支撑，哪些只写在 issue 里
- 有没有发布包，发布在哪里
README 只写这张地图支撑得住的内容。
这一步慢，但它是唯一能让"安装命令"不出错的办法。凭标题和目录猜测，猜错的概率很高。
二、没有出处就删掉，不改写
改写是最容易犯的错。一句没有依据的话，第二版往往变得更模糊，看起来安全了，实际上还是假的。
例如"最快的日志平台"改成"性能出色的日志平台"，两个版本都没有任何基准测试支撑。区别只是后者更难被指出错。
删除就干脆得多：没有基准测试，就不提性能。删掉之后，读者少了误导，作者少了一句要维护的谎。
同一套规则也用在未能验证的内容上。核对不了的功能不写成功能，写成"限制"或"未验证"。读者看到"这个选项还没在 Windows 上验证过"，比看到一个会在 Windows 上失败的示例强。
三、结构从 200 个真实项目里来
删掉错的内容之后，还有个问题：对的内容该放在哪儿。
我读了 200 个项目的 README，每个仓库至少 1,000 Star，把每份原文固定到具体提交并留下源链接。其中 32 个做成详细案例，记录组织方式、值得借鉴的部分、照搬时会踩的坑；另外 168 个按 14 个领域整理成结构研究，每组 12 个项目（Web 框架、语言与构建、CLI 与 Shell、库与 SDK、数据与存储、基础设施、测试与代码质量、创作软件、开发者应用、科学计算与 ML、安全与网络、嵌入式与机器人、文档与学习、内容与领域应用）。
图注：研究集构成。数量与核验日期记在仓库的 research/ 目录里，核验日期 2026-10-16。
结论很直接：不同类别的项目，开头的写法不该一样。
- React、Vite 这类框架，读者多半要先跑起来看效果，安装命令和最小示例要早出现。
- Linux、Zephyr 这类系统，读者找的是构建入口和平台支持范围。
- 一个命令行小工具，三行说明加一段命令和输出就够，塞贡献指南反而挡住路。
- 周刊类项目，最新一期和归档的位置就是首页。
所以 Skill 里没有统一模板。它先判断项目属于哪一类，再读对应领域的参考资料。
四、一个故意写错的例子
仓库里带了一个很小的演示项目：一个用标准库写的日志行筛选脚本，配一份故意写坏的 README 草稿。
草稿原文：
Log Slice is the fastest, production-ready log platform. Install the published package with
pip install logslice, then runlogslice. Works on every operating system.
这段三十来个单词里，五个说法都站不住：这个"包"没有发布；logslice 不是可执行文件，是目录里的 .py；没有任何性能数据；"生产就绪"没有任何依据；"支持所有操作系统"从未验证。同时它漏掉了三件必需的信息：要传的文件、要传的级别、跑完应该看到什么。
改写后的对应部分：
Log Slice ... A local Python script that prints log lines for one selected level.
Requires Python 3.10+. The script uses the standard library; no package installation is needed.
cd examples/fixtures/log-slice
python logslice.py sample.log --level ERROR
预期输出一行：ERROR database unavailable。最后补一句匹配限制：级别必须在行首且后面跟一个空格，所以 2026-10-16 ERROR failed 这种带时间戳的行不会匹配。
图注：左侧是故意写坏的草稿，右侧是改写后的 README 节选。文字均摘自仓库示例文件。
图注：命令实际跑一遍，退出码和输出都记录在仓库里。
README 里出现的命令，我自己跑一遍。跑不通的命令不写。这条听着像常识，但把它当成硬性检查，能拦掉相当一部分问题。
五、安装与用法
Skill 本身是纯 Markdown 指令加按需读取的参考文件，没有运行时，不需要 API key：
npx skills add chromoany/readme-atlas
它会装进 skills CLI 识别到的 agent，并在 Claude Code 和 Codex 里建立链接。装完直接用，比如：
用 $readme-atlas 审查 README.md，不要改文件。
找出一个新用户照着做会在哪一步卡住，每条都要给出仓库里的依据。
用 $readme-atlas 把 README 翻译成中文，每个命令和功能声明都必须能在仓库里找到出处。
六、三个我还不确定的地方
写出来，免得读者以为这套东西已经验证透了。
第一，200 个仓库的研究只覆盖结构，不覆盖质量。它回答"这类项目的 README 通常怎么组织"，不回答"这个项目值不值得用"。
第二，"删掉没有出处的声明"这条规则偏激进。对安装命令和配置项我认为是对的，写错的命令比没有命令更糟。对路线图类的内容，保留句子并标注未验证往往更好。这条界线是判断，我没做过对照实验。
第三，它是指令，不是 linter。没有 CI 会在声明没有出处时失败，得由 agent 真的去读仓库。这比直接生成文本慢，慢的地方也正是它的价值。
代码和参考资料都在这里：github.com/chromoany/readme-atlas（MIT）。
如果你拿它试了手头的项目，最有用的反馈是"它在哪里还在猜"：哪条命令没核对就写了，哪一节是按模板摆的而不是按读者需求摆的。
