read-the-damn-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Read The Damn Docs

务必查阅官方文档

Do not guess where authoritative docs can answer the question. The most common right move is to web-search for the current official docs, open the relevant pages, and read them before coding. For APIs, versions, provider behavior, config, limits, lifecycle hooks, or security-sensitive flows, ground the answer in what the docs actually say.

不要猜测权威文档的位置，最正确的做法是先通过网络搜索当前的官方文档，打开相关页面并阅读后再进行编码。对于API、版本、供应商行为、配置、限制、生命周期钩子或安全敏感流程，答案必须基于文档的实际内容。

Docs-First Triggers

需优先查阅文档的触发场景

Read docs before proceeding when any of these are true:

The user asks for "latest", "current", "official", "supported", "best practice", "recommended", "today", "now", or "look it up".
The needed docs are not already in the repo or supplied by the user. Search the web for the official docs rather than hoping model memory is current.
The task adds, upgrades, configures, or imports a package, SDK, framework, plugin, CLI, model, cloud resource, or provider integration.
The API is fast-moving or version-sensitive: AI SDKs, OpenAI/Anthropic/Google APIs, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, browser APIs, deployment platforms, auth libraries, and similar.
The implementation depends on auth, OAuth scopes, permissions, secrets, webhooks, billing, payments, PII, encryption, data retention, migrations, retries, rate limits, quotas, caching, deploys, or compliance.
An error mentions deprecation, unknown options, missing exports, invalid config, unsupported fields, changed defaults, or version mismatch.
A repo has local docs, ADRs, generated schemas, OpenAPI specs, route/action registries, design-system docs, or package-level READMEs that could define the contract.
The choice is expensive to reverse: public wire formats, database schema, migration strategy, persistent IDs, event names, customer-visible behavior, or external automation contracts.
You catch yourself about to write "usually", "probably", "I think", "from memory", or code copied from model memory for an external API.

当出现以下任一情况时，必须先查阅文档再继续：

用户询问“最新”“当前”“官方”“支持的”“最佳实践”“推荐的”“如今”“现在”或“查一下”相关内容。
所需文档不在当前仓库中，也未由用户提供。此时应通过网络搜索官方文档，而非依赖模型的记忆内容。
任务涉及添加、升级、配置或导入包、SDK、框架、插件、CLI、模型、云资源或供应商集成。
API迭代速度快或对版本敏感：AI SDK、OpenAI/Anthropic/Google APIs、Next.js、React、Tailwind、Vite、Nitro、Drizzle、Prisma、Stripe、GitHub、Slack、Notion、浏览器API、部署平台、认证库等类似工具。
实现依赖于认证、OAuth权限范围、权限、密钥、Webhook、计费、支付、个人身份信息（PII）、加密、数据保留、迁移、重试、速率限制、配额、缓存、部署或合规相关内容。
错误提示中提及弃用、未知选项、缺失导出、无效配置、不支持字段、默认值变更或版本不匹配。
仓库包含本地文档、架构决策记录（ADR）、生成的Schema、OpenAPI规范、路由/动作注册表、设计系统文档或包级README，这些内容可能定义了契约。
决策的变更成本极高：公共wire格式、数据库Schema、迁移策略、持久化ID、事件名称、客户可见行为或外部自动化契约。
你发现自己即将写下“通常”“可能”“我认为”“凭记忆”，或是复制模型记忆中的外部API代码。

What Counts As Docs

哪些属于权威文档

Use the most authoritative source available:

Local repo docs, specs, ADRs, schemas, generated types, package READMEs, and tests for project-specific behavior.
Official product docs, API references, migration guides, changelogs, release notes, and SDK source/types for third-party behavior. Find these with web search when you do not already have the exact URL.
Package registry metadata for versions. Before adding a dependency, run
```
npm view <pkg> version
```
,
```
pnpm view <pkg> version
```
, or the ecosystem equivalent, then read the docs for that major version.
Source code or type definitions when official docs are incomplete. Treat this as evidence, not folklore.

Avoid Stack Overflow, old blog posts, random snippets, and memory as the primary source when official docs exist. Use community sources only to debug symptoms after the authoritative contract is known.

使用可用的最权威来源：

本地仓库文档、规范、ADR、Schema、生成的类型定义、包README和测试，用于项目特定行为。
第三方产品的官方文档、API参考、迁移指南、变更日志、发布说明和SDK源码/类型定义。当你没有确切URL时，通过网络搜索找到这些内容。
包注册表的版本元数据。添加依赖前，运行
```
npm view <pkg> version
```
、
```
pnpm view <pkg> version
```
或对应生态系统的等效命令，然后查阅该主版本的文档。
当官方文档不完整时，查看源码或类型定义。将其视为证据，而非传闻。

当存在官方文档时，避免将Stack Overflow、旧博客文章、随机代码片段或记忆作为主要来源。仅在了解权威契约后，才使用社区来源调试问题。

Required Workflow

必选工作流程

Identify the exact surface: package name, installed version, target version, provider endpoint, CLI command, config file, local helper, schema, or product feature.
Search the web for the current official docs unless the relevant docs are already local or the user supplied a URL. Use targeted searches such as
```
<product> <feature> official docs
```
,
```
<package> migration guide
```
, or
```
<provider> API reference
```
.
Open and read the docs closest to that surface. Prefer local docs first for internal code, then official upstream docs. For new packages, verify the latest version before writing imports, config, or install commands.
Extract the few facts needed for the task: option names, imports, lifecycle rules, default behavior, breaking changes, limits, permissions, and examples for the current major version.
Implement or answer using those facts. If the docs conflict with existing code, inspect the local code path and call out the discrepancy.
Verify with the smallest useful check: typecheck, tests, build, CLI dry run, API schema validation, or a local reproduction.
In the final answer, name the docs or local files consulted when that evidence affects the recommendation or implementation.

明确具体对象：包名称、已安装版本、目标版本、供应商端点、CLI命令、配置文件、本地辅助工具、Schema或产品功能。
除非相关文档已在本地或用户提供了URL，否则通过网络搜索当前官方文档。使用针对性搜索，例如
```
<product> <feature> official docs
```
、
```
<package> migration guide
```
或
```
<provider> API reference
```
。
打开并阅读与该对象最相关的文档。内部代码优先查阅本地文档，然后是官方上游文档。对于新包，在编写导入、配置或安装命令前，先验证最新版本。
提取任务所需的关键信息：选项名称、导入语句、生命周期规则、默认行为、破坏性变更、限制、权限以及当前主版本的示例。
基于这些信息实现或作答。如果文档与现有代码冲突，检查本地代码路径并指出差异。
通过最小化的有效检查验证：类型检查、测试、构建、CLI试运行、API Schema验证或本地复现。
在最终答案中，注明参考的文档或本地文件（当这些证据影响建议或实现时）。

Examples That Must Trigger Docs

必须触发文档查阅的示例

"Add Tailwind to this app." Check the current Tailwind major and its install docs from the web before creating config files or assuming old PostCSS setup.
"Use the AI SDK to stream responses." Verify the current AI SDK major, imports, provider package names, streaming helpers, and server/runtime examples from official docs.
"Wire up Stripe webhooks." Read Stripe's current signature verification, event retry, endpoint secret, and framework body-parsing docs before coding.
"Fix this Next.js caching bug." Read the docs for the installed Next.js major and router mode before assuming cache invalidation semantics.
"Add Drizzle migrations." Read the current Drizzle kit docs and existing repo migration conventions before generating files.
"Create a GitHub Action." Read official Actions syntax and permissions docs, especially for
```
pull_request
```
,
```
workflow_run
```
, OIDC, tokens, and artifacts.
"Why does this OAuth flow fail?" Read the provider's scopes, redirect URI, PKCE, token refresh, and app verification docs before changing code.
"Use this repo's plan/comment/action system." Read local docs, route/action registries, schemas, and tests before inventing endpoints or props.
"Upgrade Vite/Nitro/React." Read the migration guide for the exact target major before editing config or imports.
"What model should we use?" Read current provider model docs, pricing/limits pages, and SDK examples before recommending.

“为这个应用添加Tailwind。”在创建配置文件或假设旧的PostCSS设置前，先通过网络查阅当前Tailwind主版本的安装文档。
“使用AI SDK流式传输响应。”从官方文档验证当前AI SDK的主版本、导入语句、供应商包名称、流式传输辅助工具以及服务器/运行时示例。
“对接Stripe Webhook。”在编码前，阅读Stripe当前的签名验证、事件重试、端点密钥和框架体解析文档。
“修复这个Next.js缓存bug。”在假设缓存失效语义前，查阅已安装的Next.js主版本和路由模式的文档。
“添加Drizzle迁移。”在生成文件前，阅读当前Drizzle Kit文档和现有仓库的迁移约定。
“创建一个GitHub Action。”阅读官方Actions语法和权限文档，尤其是
```
pull_request
```
、
```
workflow_run
```
、OIDC、令牌和工件相关内容。
“为什么这个OAuth流程失败？”在修改代码前，查阅供应商的权限范围、重定向URI、PKCE、令牌刷新和应用验证文档。
“使用这个仓库的计划/评论/动作系统。”在创建端点或属性前，阅读本地文档、路由/动作注册表、Schema和测试。
“升级Vite/Nitro/React。”在编辑配置或导入语句前，查阅目标主版本的迁移指南。
“我们应该使用哪个模型？”在给出建议前，阅读当前供应商的模型文档、定价/限制页面和SDK示例。

When A Quick Local Read Is Enough

仅需快速查阅本地内容的情况

Do not browse the web for every tiny edit. A docs pass can be local and brief when the answer is already in the repo: existing helper usage, nearby tests, typed interfaces, generated clients, ADRs, or package READMEs. But if the task depends on an external tool, package, provider, or current product behavior, web search is usually the right first step. For trivial language syntax, typo fixes, formatting, or self-contained code with no external contract, proceed normally.

无需为每一处微小修改都浏览网络。当答案已存在于仓库中时，可进行简短的本地文档查阅：现有辅助工具的用法、附近的测试、类型化接口、生成的客户端、ADR或包README。但如果任务依赖外部工具、包、供应商或当前产品行为，网络搜索通常是正确的第一步。对于琐碎的语言语法、拼写修正、格式调整或无外部契约的独立代码，可正常处理。

If Docs Are Unavailable

当文档不可用时

If network access, auth, or missing local files prevents reading the docs, say that plainly before relying on memory. Narrow the uncertainty, inspect source or types if available, and avoid presenting the result as confirmed-current.

如果因网络访问、认证或本地文件缺失无法查阅文档，请明确说明这一点，再依赖记忆作答。缩小不确定性范围，如果可用则检查源码或类型定义，避免将结果表述为已确认的最新内容。