Readme Craft

---
name: readme-craft
description: |
  为开源项目撰写、重写或审查仓库 README：让读者迅速判断项目是否解决自己的问题，尽快完成第一次真实使用，并逐步理解原理与边界。用于“写 README”“优化开源项目首页”“README 审查”“3 秒抓眼球、30 秒开始、1 分钟懂原理”等请求；不用于 GitHub 个人主页 README 或纯 Markdown 排版美化。
trigger: /readme-craft
compatibility: Claude Code, Codex
license: MIT
---

# readme-craft

把 README 当成陌生人第一次使用项目的入口。目标是让对的人愿意试、试得成、知道何时不该用；Star 只能是结果，不是文案的真实性标准。

同系列：`launch-video` 用同一套证据制作 30 秒发布视频；README 定稿后再做视频，二者的定位句、证据与安装命令保持一致。

“3 秒 / 30 秒 / 1 分钟”是**信息可见性目标**，不是阅读速度或增长承诺：首屏看出用途与价值；紧接着找到可执行的第一步；继续读能理解输入、关键机制与输出。按项目类型调整篇幅和媒介，不用固定标题凑齐三段。

## 适用与交付

- 新写：交付仓库根目录的 `README.md`，使用项目已有语言约定；用户只要草稿时交付草稿，不擅自改仓库。
- 重写：保留经过核实的安装、许可、兼容性、限制和贡献信息；删除已失效或重复内容。
- 审查：指出最影响首次使用的少数问题，给出可直接替换的文字或修改后的文件；不要只给打分。
- 项目已有生成器、国际化来源文件或 README 自动同步机制时，修改源头并重新生成；不要手改生成产物。

## 先取证，再写承诺

1. 读项目说明、入口代码、包元数据、示例、发布产物、测试与现有文档，确定**目标读者、具体问题、可观察结果、差异及适用边界**。用户有明确定位时沿用，并核对实现。源码仅能证明实现意图；运行结果、发布状态和外部采用分别需要各自证据。
2. 从现有公开安装或运行方式中选一条门槛最低、能看到价值的路径。核对前置条件、版本、平台、凭据、费用、数据外发、样例输入和预期输出。无法运行时只写已核实部分，并标明未验证，不能把示意命令写成“复制即用”。
3. 明确项目形态：CLI 展示输入命令与输出；库展示最小代码与返回值；应用展示入口和关键界面；Agent skill 展示安装、调用及可检查的产物；数据/研究项目展示数据来源与复现条件。项目没有可用的最短路径时，先修阻断或如实说明，不靠文案掩盖。
4. 吸收同类优秀 README 的表达方式，只借信息组织和展示手法；功能、数据、评价、截图与基准必须来自本项目的可核实证据。不要由 Star 数反推文案有效，也不要复制他人承诺。

## 按读者的决策顺序组织

**首屏：判断值不值得看。** 用项目名与一句具体描述说清“谁，用什么，得到什么”。紧接一张真实结果图、短输出或极短示例，选择最能证明价值的媒介。给一个清楚的下一步链接。差异只写可验证的事实；避免“强大、革命性、最简单”等空词、徽章墙、长目录和架构图抢占首屏。

**第一次使用：读者独自走通。** 在深度背景之前给最短可复制路径：前置条件 → 安装/打开 → 输入 → 预期输出或成功判据。选择官方发布途径；不要默认 `git clone` 等于安装。需要密钥、账号或费用时在命令之前说明。失败时给最常见且有证据的排查入口。高级配置和开发环境另放后文或 `docs/`。

**原理：解释实际因果链。** 用“输入 → 关键处理 → 输出”解释为什么会得到刚才的结果。复杂项目可加一张准确的 Mermaid 图或小表；简单项目用三句话即可。讲清独特机制、约束与取舍，不把组件清单或宣传词冒充原理。术语首次出现时用读者熟悉的概念解释。

**按需深入：逐层展开。** 常见后续顺序是使用场景与示例、能力与限制、配置、常见问题、开发/贡献、许可与安全/隐私。内容多时把完整 API、故障手册、设计细节移到独立文档并在 README 给出明确入口。每个章节回答一个读者问题；没有内容就删掉章节，不保留模板占位符。

## 写作与验证闭环

1. 先写一句定位和一条真实“输入 → 结果”链，再排章节。用户强调的卖点要让例子证明。对不同受众，仅在确有不同任务时设独立入口，避免首屏并列过多选择。
2. 写完逐条核对功能、命令、版本、链接、截图、性能数字、平台、许可证、外部依赖与安全声明。未知写未知，不编造用户反馈、采用量、支持范围或即将发布的能力。
3. 在干净环境或隔离目录按 README **原文顺序**完成最短路径，记录命令、退出状态和实际输出；如果真实运行受外部条件阻断，标记 `NOT_RUN` 及原因。修正文档或产品阻断，再复跑受影响路径。仅检查代码块格式不能证明可用。
4. 在 GitHub 渲染视图或等效 Markdown 预览中检查首屏、移动端可读性、图片替代文本、标题层级、链接与代码块。无图项目不必强制补图；截图必须来自真实运行且与当前版本一致。
5. 做一次冷读：只看首屏能否说出用途和目标人群？继续找到的第一段命令能否独立起步？读到原理后能否解释刚才的输出？找不到的内容前移或补链接，冗余的内容下沉。真实新用户试用优于自我计时；没有读者实测就不要声称“3 秒/30 秒/1 分钟达标”。

## 输出

交付修改后的 README（或用户要求的草稿），并简述：定位句、最短使用路径、原理说明、执行验证结果与仍未核实的声明。审查任务给阻断项和可执行修法。若项目本身无法完成核心任务，明确指出阻断，不把“README 已写完”当成可发布证据。

## 来源与取舍

- [README checklist](https://github.com/ddbeck/readme-checklist)：按读者建立信心的顺序检查内容，而不是照章节填空。
- [Art of README](https://github.com/hackergrrl/art-of-readme)：重视示例、链接和长期可读性。
- [Standard Readme](https://github.com/RichardLitt/standard-readme)：借鉴安装、使用、贡献等信息的可查找结构；不强制所有项目符合其库类规范。
- [How to write a good README](https://github.com/banesullivan/README)：借鉴开头的亮点、实际使用示例及简洁表达。
- [Awesome README](https://github.com/matiassingers/awesome-readme)：寻找相同项目形态的真实案例，不把视觉装饰当成质量指标。