README编写器 是做什么的?
README只有一个任务:在一分钟内让访问者从“这是什么?”到成功运行第一个命令,然后展示如何进一步使用和如何帮助。
何时使用
- 为新项目编写README,或重写内容单薄或冗长的README
- 在项目发布或1.0版本前审查README
- 用户表示项目有访问量但没有加星、安装量或贡献者
何时不使用
- API参考文档(从代码生成;在README中链接到它)
- 长教程或架构文档:放在
docs/目录并链接
工作流程
-
在编写前收集事实。 读取清单文件(
pyproject.toml、package.json、composer.json、Cargo.toml...)、CLI的--help或主入口点、现有文档和许可证。找到真正的安装命令和真实的示例。永远不要发明标志、输出、基准测试或特性。 -
只向用户询问代码无法告诉你的信息: 项目的目标用户、它解决的单一问题、以及它为什么比明显的替代方案更好。如果用户无法提供,则从代码编写一个中立的简介,并标记以供审查。
-
检查当前README(如果有)。
scripts/相对于此技能:python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
按照structure.md中的结构编写,从模板开始。顺序很重要:标题+徽章、简介、(演示图片)、快速入门、功能、用法/示例、配置、常见问题、路线图、贡献指南、许可证。
-
应用编写规则:
- 简介:一句话,不超过200个字符,不使用空泛的宣传词。模式:“
<名称>是一个<类别>,它<做什么>为<受众>,<关键差异化>。” - 第一个代码块在第60行之前。每个命令必须可复制粘贴且真实。
- 在命令后显示有用的输出(
# => ...或单独的代码块)。 - 使用表格表示选项和比较,使用列表表示功能(先说好处)。
- 链接而不是粘贴:长文档、变更日志和API参考放在别处。
- 每个图片都有alt文本;优先选择SVG或展示主要流程的短视频GIF。
- 简介:一句话,不超过200个字符,不使用空泛的宣传词。模式:“
-
徽章。 只使用真实且维护中的徽章,顺序如下:CI状态、最新版本(PyPI/npm/Packagist/release)、下载量(可选)、许可证。示例见structure.md。
-
重新lint 直到没有错误。解决警告,或告诉用户为什么无法解决。
-
检查lint无法检测的链接: 绝对URL和锚点。点击测试或说明哪些未经验证。
输出
- 新的或更新的README.md(对于重写,显示差异摘要)。
- 最终的lint结果。
- 一个简短的列表,列出你无法验证的事实以及用户必须填充的占位符(演示GIF、截图、基准测试数据)。
Lint规则
| 规则 | 级别 | 含义 |
|---|---|---|
| title | error/warning | 恰好一个H1 |
| pitch | error/warning | 标题下的一段简短简介 |
| badges | warning | 未找到徽章 |
| install | error/warning | 安装(或快速入门)章节,包含代码块 |
| quickstart | error/warning | 用法、快速入门或示例章节,包含代码 |
| code | error | 完全没有代码块 |
| scroll | warning | 第一个代码块在--max-scroll行之后(默认60) |
| contributing, license | warning | 缺失章节 |
| faq, toc | info | 建议添加 |
| alt-text | warning | 图片没有alt文本 |
| broken-link | error | 相对链接指向缺失的文件,或空链接 |
| broken-anchor | error | #anchor链接(目录)不匹配任何标题或HTML id/name,使用GitHub的slug规则 |
| placeholder | warning | 留有TODO、TBD或lorem ipsum |
错误时退出码为1(带有--strict时警告也视为错误)。