write-readme

write-readme

为注意力有限的读者撰写 README：说明它是什么、何时使用、如何开始，以及不要对它抱有什么期待。

工作流

1. 收集背景信息：解决的问题、目标受众、现有替代方案、最突出的价值或证据，以及非目标。
2. 只分类一次：库、CLI/工具或 Agent 工具。如有不清楚之处，请提问。
3. 添加之前先精简：删除重复的清单、无关徽章、营销说法，以及复制粘贴的 --help 表格。
4. 按倒金字塔顺序起草：直白说明价值、安装、常见用法、适用边界，然后是可选参考资料。
5. 将最常用的调用方式或导入路径放在前 30 行内。
6. 仅将 REFERENCE.md 用于选择章节，不要把它当作必需模板。
7. 最后检查：每一行都必须回答读者可能提出的问题，或改变他们接下来的行动。

开篇规则

• 开篇直述具体价值：指标、明确的能力或鲜明的差异化优势。
• 切勿以“A library/tool that...”开头；应先展示读者能获得什么。
• 尽早说明目标受众和非目标。
• 说法必须有证据或方法说明支撑。
• 真诚表达。避免使用“无缝”“即时”“强大”“无需重复解释”等广告文案用语，除非 README 能证明这些说法。
• 优先采用普通用户的口吻，而非产品说明书的口吻。若第一人称说明提及真实的日常用途，也可以保留；如果变成品味宣扬、炒作或玩笑，就删掉。
• 先从工具解决的实际困境切入，再说明其工作机制。“我当时遇到了这个问题，这个工具帮上了忙”胜过“此解决方案能够实现……”。

严格精简

删除或压缩以下内容：

• 重复的平台支持或集成清单。在影响命令语法或安装的位置说明一次即可。
• 如果 --help、生成的文档或软件包文档已涵盖完整标志/参考表，就不要再重复列出。
• 不影响信任或安装决策的徽章。
• 分别阐述相同内容的“功能”“特性”和“原因”章节。
• 冗长的注意事项。保留适用边界，但用简短的操作性事实表述。

Agent 工具

对于面向编码 Agent 调用的 CLI：

• 将 README 视为工具的函数签名。
• 展示准确的命令格式、必需参数、重要标志，以及有助于 Agent 验证工作的预期成功/错误输出形式。
• 添加“Not for X”限制提示，避免 Agent 误用。
• 核心接口应便于浏览，无需展开 <details>。

不可妥协的要求

• 安装/快速入门应放在架构介绍之前。
• 限制应单独设标题，不要埋在注意事项中。
• 宽泛的支持声明必须列出具体平台、格式、语言或集成。
• 只有在故障常见且有可操作的解决方法时，才在 README 中加入故障排除内容。
• 仅在高级配置、原始数据、方法说明或替代设置方式中使用 <details>。
• 不使用营销形容词；用数字、示例和明确的证据来说明。
• 默认不要采用戏剧化的连接句式：破折号、箭头以及“并非只有 X，而是 Y”都应有充分理由才使用。

模板、徽章模式、截图指南、语气说明和最终检查提示请参阅 REFERENCE.md。