README 先行：动笔写代码之前，先把文档写了
亚马逊用六页纸开会，vibe coder 可以用 README 开工。这篇指南讲“README 先行”工作流：先写好给用户看的文档，再让 AI 照着实现——需求在动笔前就被逼着想清楚，返工少一半。
为什么先写文档：文档是需求的试金石
大多数 vibe 项目的返工不是代码写得慢，而是写到一半才发现需求没想清楚。“这个按钮到底该干嘛”“用户流程到底是几步”——这些问题在写代码时才暴露，改起来最贵。README 先行的逻辑很简单：如果你写不出一段清晰的文档来描述这个功能，说明你还没想清楚，不配开始写代码。
这招是从亚马逊的“六页纸”文化化用来的：开会之前先写叙述文档，写不清楚就别开会。对 vibe coder 来说，README 就是你的六页纸——而且 AI 特别吃这一套：给它一份写好的 README，它生成的代码一次成型的概率高得多。
README 先行工作流：四步
第一步：写“这是什么”。用三句话说清：这个项目/功能是干嘛的、给谁用的、解决什么问题。写不出来就别往下走——这是需求的生死线。
第二步：写“怎么用”。像最终用户一样写使用流程：第一步点哪、第二步看到什么、异常情况长什么样。这一步会逼你把用户流程的每一步都想清楚，很多“到时候再说”的坑在这里现形。
第三步：写“长什么样”。用文字或 ASCII 草图描述关键界面：页面上有哪些区域、核心操作在哪。不需要精美，需要具体——“右上角有个导出按钮”比“界面简洁美观”有用一百倍。
第四步：把 README 喂给 AI。直接告诉 agent：“按这份 README 实现，文档里写的就是验收标准，实现完对照着自查。”这时候 README 从文档变成了可执行的规格说明书。
三个实战建议
第一，README 要写给“不懂的人”看。想象读者是一个完全没参与讨论的朋友——凡是需要口头补充说明的地方，都是需求没写清楚的信号。
第二，先写英文版也行，但别跳过中文思考。很多 vibe coder 习惯直接让 AI 写英文 README，结果是文档很漂亮、需求很模糊。先用中文把逻辑捋顺，再让 AI 翻译润色。
第三，代码变了，README 跟着变。README 先行最怕的是“写完就扔”——实现过程中需求必然调整，每次调整先改 README 再改代码。这样你的文档永远是最新状态，而不是三个月后没人敢看的古董。
一句话总结
README 先行不是形式主义，是把最贵的思考前置：用一小时写文档，省下十小时返工。对 AI 来说，一份好 README 是最好的 prompt；对你来说，它是需求想清楚的证明。
相关文章
10 月 3 日，工程师 Kevin Liao 发表檄文冲上 HN 前页：记忆插件是一场 RAG 片段抽奖，Agent 需要的是文档工作区。本文拆解他的诊断、开源的 Operator Memory 插件、两个最强的反方质疑，以及今晚就能开始的最小实践。
2026 年 10 月 7 日，Google Developers 发布 Developer Knowledge API 生态：Google Cloud、Firebase、Android 等官方文档变成程序化事实来源，配 gcloud CLI 入口、官方 Agent Skill（一行安装）、MCP server 和多语言客户端库。为什么「文档 API 化」能连根拔掉 vibe coding「模型记错 API」的经典翻车。
每个 vibe 项目迟早需要定时任务：每日数据同步、过期订单清理、账单对账、定时报告。AI 给你的第一个版本通常是 setInterval——开发够用，生产必死。这篇实战给出四种跑法的选型地图（应用内/Vercel Cron/GitHub Actions/Cloudflare），cron 表达式速查与时区坑，幂等性、防重叠分布式锁、失败重试与告警、可观测性 run log，以及 cron 接口的鉴权，最后附上线清单。