Vibe Coding README 冷启动验收：让新环境按文档抵达首个成功

README 最常见的假成功是维护者在自己的电脑上照着读了一遍：依赖早已安装，数据库里已有表，环境变量留在 shell 历史中，于是三行命令看起来完全正确。陌生贡献者或编程 Agent 从全新检出开始时，才发现运行时版本不明、示例配置缺字段、初始化步骤不可重复，或者首页能返回 200 但核心能力根本不可用。

本文所说的 Vibe Coding README 不是 AI 文档站，也不是仓库结构教程。陌生仓库冷启动解决“第一次编辑前怎样只读勘察”，这里解决另一个可验问题：仓库承诺的最短入门路径，能否由没有作者本机状态的人按原文执行并获得同一个业务成功。

先声明读者、范围与首个成功

README 开头先说明它服务谁、覆盖什么、不覆盖什么。一个库的首个成功可能是运行最小示例并得到固定返回；一个 Web 应用可能要求健康检查通过、打开本地地址、使用合成账号完成一次无副作用读取；一个 CLI 则应执行版本命令和一个确定性子命令。只写“项目已启动”无法区分端口监听、依赖就绪和用户任务可完成。

成功判据必须可观察，但不能伪造。可用一个稳定状态码、结构化输出字段或测试夹具 ID 判断，避免要求读者“看到类似页面即可”。若流程需要邮件、对象存储或内部 API，README 应明确真实依赖、受控替身与功能差异；本地开发依赖就绪合同可以进一步防止端口可连却语义未就绪。

同时列出不在快速开始里的事项，例如生产密钥、真实支付、数据迁移和部署。快速开始的目标是建立可信最小闭环，不是用默认管理员或共享云资源模拟生产。

把前提写成能失败的检查

环境前提至少包括操作系统范围、CPU 架构、运行时与包管理器精确支持区间、外部工具、网络要求、所需端口和资源下限。版本只写“Node 已安装”会让读者在不兼容主版本上继续；只写一个下载链接又会让支持矩阵随上游 latest 漂移。仓库实际版本应与 lockfile、引擎声明和 CI 一致，方法可接续官方文档版本锚定。

每项关键前提都应有只读探针，并说明不满足时的退出信息。例如版本检查输出当前值与支持区间，端口检查指出占用者但不自动杀进程，依赖探针区分未配置、无权限和服务不兼容。脚本不能静默下载系统级软件、修改全局配置或覆盖已有文件；需要提升权限的动作单独解释，由人确认。

配置样例只声明名称、类型、用途和安全类别。真实 token、可用的共享密码、个人目录和生产域名不能进入 README。缺少必填值时程序应尽早报出字段名；可选值写明默认语义。环境差异较多时，用仓库配置与环境矩阵保存开发、测试和生产的能力区别，README 只指向当前冷启动所需的一列。

把命令当成面向贡献者的接口

安装、初始化、启动、验证和清理应各有一个仓库拥有的稳定入口。npm 官方脚本文档说明生命周期与参数传递的实际语义；团队应把底层工具组合封装进已有脚本，而不是让 README 复制一串会分别漂移的长命令。命令必须从仓库根目录运行，或明确当前目录；交互提示提供非交互模式，CI 才能复演。

初始化要可重入。第一次运行创建合成资源，第二次运行应报告已满足或安全更新，不能重复插入不可辨认的数据。失败时保留原状态或给出精确恢复步骤。清理命令只删除带当前项目与环境身份的测试资源，先显示范围，不能用宽泛通配符换取“一键重置”。

README 还要区分 shell 平台。仅验证过 Bash 就不要声称 PowerShell 可用；换行、引号、路径和环境变量写法要在各自 runner 里执行。复制块不要混入提示符、行号或自然语言续行。机器入口保持短，解释放在命令前后。

在全新环境生成冷启动收据

验证不能复用维护者的依赖目录、构建缓存、数据库卷和登录状态。CI 或定期任务从全新检出开始，仅注入文档声明的非秘密测试配置，按 README 顺序执行：前提检查、安装、初始化、启动、首个成功、停止、再次初始化与清理。缓存可以另跑加速路径，但至少保留一条冷路径发现隐含输入。

收据绑定提交、README 摘要、运行环境、实际命令、依赖锁摘要、开始结束时间、成功判据和清理结果。可复现构建的核心思想是相同来源在声明环境中得到可验证结果；README 验收同样需要把输入身份固定下来。旧提交的绿色收据不能证明刚修改的说明仍正确。

为了检验门禁，主动制造几类漂移：删除一个必填环境变量说明，提升运行时到不支持版本，预占端口，清空数据库，重复执行初始化，断开一个可选依赖，并从非仓库目录启动。系统应在对应阶段给出可行动错误，而不是卡住或直到端到端测试才失败。

维护入口，而不是堆积历史补丁

每个 README 段落指定 owner 或至少对应代码路径。改变运行时、脚本、配置 schema、默认端口或首个用户流程时，变更清单必须提醒更新冷启动合同。废弃命令从主路径删除，迁移说明进入版本化文档；不能在顶部写新步骤、底部保留相反旧步骤让 Agent 自行选择。

最终门禁要求：一个非作者 runner 能从零抵达首个成功；所有输入都有来源；无秘密和个人状态被读取；初始化可重入；清理范围可证明；失败信息能指向恢复动作。结果再进入编程 Agent 改动验证门，与本次代码而不是作者记忆绑定。

可验证 README 的价值不在于字数，而在于它能独立回答“从哪里开始、怎样知道成功、失败后如何回到可控状态”。当这条路径持续由冷环境复演，Vibe Coding 才拥有可信入口，而不是只有熟悉项目的人才能补全的口头知识。