当需要编写或审计开发者快速上手文档（quickstart）时…

编写或审计一份让开发者快速获得首次成功体验的 quickstart 页面，而非教学教程或 README。

适用场景

解决思路

1. 先做范围检查：确认任务是 quickstart；若读者需要概念讲解则转 getting-started 或教学教程，若是仓库落地页则转 README，若是文档站点信息架构问题则转对应技能，若是 API 逐端点完整性则转 API reference，若消费者是编码代理则转 agent 文档技能。
2. 通过访谈确定关键信息（一次问一个，尽量给选项，一旦能定义成功时刻和时间预算就停止）：产品类别、读者最终应看到什么在运行、读者是否熟悉问题领域、读者类型（自助个人/内部入职/企业评估）、凭证获取方式、happy path 使用的单一环境、是审计还是新建、能否在干净机器上自行运行、是否有分析数据、上线日期、一次性还是长期资产、作者工时上限与维护负责人。
3. 设定模式：新建则进入后续步骤；审计则先按冷运行协议运行现有页面并收集真实缺陷，绝不只靠阅读就重写。
4. 选定成功时刻：它是产品为读者可见地做了什么，而不是读者执行的步骤；限定到产品主功能和最短端到端路径（例如“响应中包含你刚创建的记录”，而非“发了一次 API 调用”）。
5. 设定时间预算并作为后续所有决策的硬约束：Hosted API 5 分钟、SDK/库 10 分钟、CLI 5 分钟、数据库/数据平台 10 分钟、托管/部署平台 10 分钟、Auth 10 分钟、自托管基础设施 30-60 分钟。
6. 在记录前置条件之前先删除它们：优先通过沙箱账号减少设置负担；最强形式是删除账号本身，用临时开发密钥或匿名开发部署让首次运行无需注册；按每周产品工程删除的分钟数排序访问机制：无账号 > 临时开发密钥 > 即时自助密钥 > 注册后免费层 > 销售门控沙箱。
7. 把幸存的前置条件全部列在步骤 1 之前：每项附一行检查命令（如 node --version）和安装指引；运行中途发现的任何东西都是缺陷；环境设置庞大且持久时单独成页并从步骤 1 链接。
8. 选择一条路径和一个容器：一种语言、一个包管理器、一个平台、一种认证方式；替代方案放在链接或同步语言切换器后，绝不作为读者需推理的内联选择；容器按每小时构建和维护消除的摩擦排序：纯文档页 > CLI 脚手架 > try-it 控制台 > 语言标签页 > notebook > 嵌入式沙箱；默认纯文档页，仅当容器能消除文字无法解决的摩擦时才升级。
9. 每个步骤写四部分：动词开头的标题陈述完整结果（如“Connect to the VM instance”，不用“Connect”，也不用 -ing 形式）、恰好一个可复制块、预期输出、一行失败分支；每步一个动作；步骤需要特定文件或屏幕时先给读者定位。
10. 落地成功：明确陈述成功时刻（“你现在应该看到你创建的记录”），然后最多给三个后续步骤：最常见的第二个任务、参考文档、获取帮助的地方。
11. 对散文（绝不对代码块）做 humanizer 处理，让页面读起来像工程师写的而非模型写的。
12. 按通过阈值做冷运行验证：在干净环境、全新账号、无缓存凭证、无预装依赖下运行；修复并重跑直到通过。
13. 埋点并记录：定义成功事件和漏斗；若有持久记忆，存储选定的成功时刻、时间预算、支持路径和被拒绝的范围，以便后续文档工作保持一致。
14. 遵守复制粘贴规则：命令和输出分块显示；去掉 shell 提示符（$）、行号和穿插注释；占位符要醒目（<YOUR_API_KEY>），绝不用看似真实的假值；创建文件时给完整内容而非片段，包含所有必需的 import/using；代码示例注释放在代码前后而非命令块内；安装命令固定版本。
15. 冷运行时维护摩擦日志：记录每次犹豫、困惑和意外，用红绿灯标记（绿=愉悦、黄=摩擦、红=阻塞）；同一一步出现三次犹豫意味着该步在做两件事，应拆分。
16. 按价值/接线工时顺序埋点 KPI：步骤级流失（每步一个事件）、引用 quickstart 步骤的支持工单或 issue、从页面加载到成功事件的中位时间、完成率、完成者第 7 天回访；完成健康但激活平淡时把第 7 天回访提升到最高优先级。
17. 用页面自身基线设定目标：默认测量四周，然后承诺相对改进，绝不从厂商博客导入数字。
18. 在 CI 中逐字运行 quickstart 命令并断言文档化输出，防止回归。
19. 把 quickstart 放在与产品相同的仓库和 PR 工作流中：让发布工程师写初稿，由写作者审阅，设置合并门禁阻止无文档的 PR。
20. 按读者类型调整访问方式：个人/自助读者优化零账号或即时密钥、免费层覆盖全路径、成功前无账单提示；企业/门控读者 upfront 说明必须存在什么（租户、沙箱、角色、白名单网络）及由谁提供，为每条假设联网的命令提供离线/本地变体，绝不写“联系管理员”而不说明要申请什么。
21. 按失败模式表修复：页面以背景或架构散文开头→删到第一个动作；前置条件出现在步骤 3→移到前置条件块并加检查命令；读者需在三个包管理器间选择→选一个并链接其他；步骤无预期输出→加可观察输出或合并到下一步；步骤标题是裸动词或 -ing 形式→改写为完整结果；错误输出无修复路径→为每个文档化错误加一行失败分支；环境设置膨胀页面→拆成独立页从步骤 1 链接；quickstart 只在作者机器上工作→按通过阈值冷运行并在 CI 自动化；页面随时间超出预算→重新裁剪到一个成功时刻，其余拆成 how-to 指南；把具名厂商工具列为必需→描述能力而非厂商；加了语言标签页但只验证一个→冷运行每个标签页。
22. 通过阈值五项全部满足才发布：每条命令按原样成功、每步真实输出与文档输出匹配、步骤 1 后零前置条件被发现、实测耗时在承诺预算内、不熟悉产品的读者不离开页面即可到达成功时刻；时间预算失败时缩小成功时刻，绝不延长预算。

适用边界 · 注意事项

• 读者是问题领域新手、需要解释概念时（应使用 getting-started 指南或教学教程）
• 读者需要通过渐进练习来学习时（应使用教学教程技能）
• 产物是仓库落地页（徽章、定位、项目结构）时（应使用 README 技能）
• 问题是文档站点中内容该放在哪里时（应使用文档信息架构技能）
• 问题是 API 文档逐端点完整性时（应使用 API reference 技能）
• 消费者是编码代理而非人类时（应使用 agent 文档技能）