readme-craftlisted

# readme-craft 把 README 当成陌生人第一次使用项目的入口。目标是让对的人愿意试、试得成、知道何时不该用；Star 只能是结果，不是文案的真实性标准。 “3 秒 / 30 秒 / 1 分钟”是**信息可见性目标**，不是阅读速度或增长承诺：首屏看出用途与价值；紧接着找到可执行的第一步；继续读能理解输入、关键机制与输出。按项目类型调整篇幅和媒介，不用固定标题凑齐三段。 ## 适用与交付 - 新写：交付仓库根目录的 `README.md`，使用项目已有语言约定；用户只要草稿时交付草稿，不擅自改仓库。 - 重写：保留经过核实的安装、许可、兼容性、限制和贡献信息；删除已失效或重复内容。 - 审查：指出最影响首次使用的少数问题，给出可直接替换的文字或修改后的文件；不要只给打分。 - 项目已有生成器、国际化来源文件或 README 自动同步机制时，修改源头并重新生成；不要手改生成产物。 ## 先取证，再写承诺 1. 读项目说明、入口代码、包元数据、示例、发布产物、测试与现有文档，确定**目标读者、具体问题、可观察结果、差异及适用边界**。用户有明确定位时沿用，并核对实现。源码仅能证明实现意图；运行结果、发布状态和外部采用分别需要各自证据。 2. 从现有公开安装或运行方式中选一条门槛最低、能看到价值的路径。核对前置条件、版本、平台、凭据、费用、数据外发、样例输入和预期输出。无法运行时只写已核实部分，并标明未验证，不能把示意命令写成“复制即用”。 3. 明确项目形态：CLI 展示输入命令与输出；库展示最小代码与返回值；应用展示入口和关键界面；Agent skill 展示安装、调用及可检查的产物；数据/研究项目展示数据来源与复现条件。项目没有可用的最短路径时，先修阻断或如实说明，不靠文案掩盖。 4. 吸收同类优秀 README 的表达方式，只借信息组织和展示手法；功能、数据、评价、截图与基准必须来自本项目的可核实证据。不要由 Star 数反推文案有效，也不要复制他人承诺。 ## 按读者的决策顺序组织 **首屏：判断值不值得看。** 用项目名与一句具体描述说清“谁，用什么，得到什么”。紧接一张真实结果图、短输出或极短示例，选择最能证明价值的媒介。给一个清楚的下一步链接。差异只写可验证的事实；避免“强大、革命性、最简单”等空词、徽章墙、长目录和架构图抢占首屏。 **第一次使用：读者独自走通。** 在深度背景之前给最短可复制路径：前置条件 → 安装/打开 → 输入 → 预期输出或成功判据。选择官方发布途径；不要默认 `git clone` 等于安装。需要密钥、账号或费用时在命令之前说明。失败时给最常见且有证据的排查入口。高级配置和开发环境另放后文或 `docs/`。 **原理：解释实际因果链。** 用“输入 → 关键处理 → 输出”解释为什么会得到刚才的结果。复杂项目可加一张准确的 Mermaid 图或小表；简单项目用三句话即可。讲清独特机制、约束与取舍，不把组件清单或宣传词冒充原理。术语首次出现时用读者熟悉的概念解释。 **按需深入：逐层展开。** 常见后续顺序是使用场景与示例、能力与限制、配置、常见问题、开发/贡献、许可与安全/隐私。内容多时把完整 API、故障手册、设计细节移到独立文档并在 README 给出明确入口。每个章节回答一个读者问题；没有内容就删掉章节，不保留模板占位符。 ## 写作与验证闭环 1. 先写一句定位和一条真实“输入 → 结果”链，再排章节。用户强调的卖点要让例子证明。对不同受众，仅在确有不同任务