read-the-damn-docs

先去读该死的文档

权威文档能回答问题时，不要猜。最常见的正确做法是：在网上搜索最新的官方文档，打开相关页面，并在编写代码前阅读。对于 API、版本、提供商行为、配置、限制、生命周期钩子或涉及安全的流程，答案应以文档的实际说明为依据。

先读文档的触发条件

出现以下任一情况时，先阅读文档再继续：

• 用户询问“最新”“当前”“官方”“支持”“最佳实践”“推荐”“今天”“现在”或“查一下”。
• 所需文档不在仓库中，也未由用户提供。应在网上搜索官方文档，而不是寄希望于模型记忆是最新的。
• 任务需要添加、升级、配置或导入包、SDK、框架、插件、CLI、模型、云资源或提供商集成。
• API 变化快或对版本敏感：AI SDK、OpenAI/Anthropic/Google API、Next.js、React、Tailwind、Vite、Nitro、Drizzle、Prisma、Stripe、GitHub、Slack、Notion、浏览器 API、部署平台、身份验证库等。
• 实现依赖身份验证、OAuth 作用域、权限、机密、Webhook、计费、支付、个人身份信息（PII）、加密、数据保留、迁移、重试、速率限制、配额、缓存、部署或合规。
• 错误提到弃用、未知选项、缺少导出、配置无效、不支持的字段、默认值变更或版本不匹配。
• 仓库中有本地文档、ADR、生成的架构、OpenAPI 规范、路由/操作注册表、设计系统文档或包级 README，可能定义了契约。
• 选择一旦作出便难以撤回：公开的线格式、数据库架构、迁移策略、持久化 ID、事件名称、用户可见行为或外部自动化契约。
• 你发现自己正准备写“通常”“大概”“我觉得”“凭记忆”，或使用从模型记忆中复制的外部 API 代码。

什么算文档

使用现有的最权威来源：

• 项目特定行为：本地仓库文档、规范、ADR、架构、生成的类型、包 README 和测试。
• 第三方行为：官方产品文档、API 参考、迁移指南、变更日志、发行说明和 SDK 源码/类型。如果尚未掌握确切 URL，通过网络搜索查找。
• 版本信息：包注册表元数据。添加依赖前，运行 npm view <pkg> version、pnpm view <pkg> version 或对应生态系统中的等效命令，然后阅读该主版本的文档。
• 当官方文档不完整时，查阅源代码或类型定义。将其视为证据，而非传闻。

当存在官方文档时，不要将 Stack Overflow、旧博客、随手可得的代码片段和记忆作为主要依据。只有在明确权威契约后，才使用社区来源排查症状。

必需的工作流

1. 确定准确的对象：软件包名称、已安装版本、目标版本、提供方端点、CLI 命令、配置文件、本地辅助工具、架构或产品功能。
2. 搜索网络以查找当前官方文档，除非相关文档已在本地，或用户提供了 URL。使用有针对性的搜索，例如 <product> <feature> official docs、<package> migration guide 或 <provider> API reference。
3. 打开并阅读与该对象最相关的文档。处理内部代码时优先查看本地文档，其次查看上游官方文档。对于新软件包，编写导入语句、配置或安装命令前，先核实最新版本。
4. 提取完成任务所需的少量事实：选项名称、导入方式、生命周期规则、默认行为、重大变更、限制、权限，以及当前主版本的示例。
5. 根据这些事实实现或回答。如果文档与现有代码冲突，请检查本地代码路径，并指出差异。
6. 使用最精简且有用的方式进行验证：类型检查、测试、构建、CLI 空运行、API 架构验证或本地复现。
7. 在最终答复中，列出查阅过的文档或本地文件（如果这些依据会影响建议或实现）。

必须查阅文档的示例

• “在这个应用中添加 Tailwind。”在创建配置文件或假设使用旧版 PostCSS 设置之前，先从网络查阅当前 Tailwind 主版本及其安装文档。
• “使用 AI SDK 流式传输响应。”从官方文档核实当前 AI SDK 主版本、导入方式、提供方软件包名称、流式传输辅助函数，以及服务器／运行时示例。
• “接入 Stripe Webhook。”编写代码前，阅读 Stripe 当前的签名验证、事件重试、端点密钥和框架请求体解析文档。
• “修复这个 Next.js 缓存错误。”先阅读与已安装 Next.js 主版本及路由模式对应的文档，再判断缓存失效语义。
• “添加 Drizzle 迁移。”生成文件前，阅读当前 Drizzle kit 文档和现有仓库的迁移规范。
• “创建 GitHub Action。”阅读官方 Actions 语法和权限文档，尤其是 pull_request、workflow_run、OIDC、令牌和构件相关内容。
• “为什么这个 OAuth 流程会失败？”更改代码前，阅读提供方关于作用域、重定向 URI、PKCE、令牌刷新和应用验证的文档。
• “使用此仓库的计划／评论／操作系统。”在自行设计端点或属性前，阅读本地文档、路由／操作注册表、架构和测试。
• “升级 Vite/Nitro/React。”编辑配置或导入语句前，阅读与确切目标主版本对应的迁移指南。
• “应该使用哪个模型？”提出建议前，阅读提供方最新的模型文档、定价／限制页面和 SDK 示例。

何时快速阅读本地资料即可

不要为每个小改动都浏览网络。如果答案已在仓库中，例如现有辅助工具的用法、邻近测试、类型化接口、生成的客户端、ADR 或软件包 README，那么查阅文档可以仅限本地且从简。但如果任务依赖外部工具、软件包、提供方或当前产品行为，通常应先搜索网络。对于简单的语言语法、拼写修正、格式调整或不涉及外部约定的独立代码，可直接处理。

文档无法获取时

如果网络访问、身份验证或本地文件缺失导致无法阅读文档，请在依赖记忆作答前明确说明。缩小不确定范围；如果有可用的源代码或类型定义，请检查它们；避免声称结果已根据当前资料确认。