Lar

Skill

Produtividade e fluxo de trabalho

read-the-damn-docs

BuilderIO/skills

Exige que se realizem pesquisas na internet e se leiam documentos oficiais antes de implementar, integrar ou depurar APIs, bibliotecas e serviços de terceiros, a fim de garantir a precisão e evitar suposições.

...Expandir tudo

Tempo atualizado 6 de Setembro de 2026

# documentation # debugging # web search # api reference # best practices # third party apis

Leia os malditos documentos

Não tente adivinhar quando a documentação oficial pode responder à sua dúvida. A atitude correta mais comum é pesquisar na web os documentos oficiais atualizados, abrir as páginas relevantes e lê-las antes de programar. Para APIs, versões, comportamento de provedores, configuração, limites, ganchos de ciclo de vida ou fluxos sensíveis à segurança, baseie a resposta no que os documentos realmente dizem.

Motivos para priorizar a documentação

Leia a documentação antes de prosseguir quando qualquer uma dessas situações se aplicar:

O usuário pede “mais recente”, “atual”, “oficial”, “compatível”, “melhores práticas”, “recomendado”, “hoje”, “agora” ou “procure”.
A documentação necessária ainda não está no repositório nem foi fornecida pelo usuário. Pesquise na web pela documentação oficial, em vez de confiar que a memória do modelo esteja atualizada.
A tarefa adiciona, atualiza, configura ou importa um pacote, SDK, framework, plug-in, CLI, modelo, recurso em nuvem ou integração com provedor.
A API está em constante evolução ou é sensível a versões: SDKs de IA, APIs da OpenAI/Anthropic/Google, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, APIs de navegador, plataformas de implantação, bibliotecas de autenticação e similares.
A implementação depende de autenticação, escopos de OAuth, permissões, segredos, webhooks, faturamento, pagamentos, informações de identificação pessoal (PII), criptografia, retenção de dados, migrações, repetições de tentativa, limites de taxa, cotas, armazenamento em cache, implantações ou conformidade.
Um erro pode indicar descontinuação, opções desconhecidas, exportações ausentes, configuração inválida, campos não suportados, padrões alterados ou incompatibilidade de versão.
Um repositório possui documentação local, ADRs, esquemas gerados, especificações OpenAPI, registros de rotas/ações, documentação do sistema de design ou arquivos README no nível do pacote que poderiam definir o contrato.
É caro reverter essa escolha: formatos de comunicação públicos, esquema de banco de dados, estratégia de migração, IDs persistentes, nomes de eventos, comportamento visível ao cliente ou contratos de automação externos.
Você se pega prestes a escrever “geralmente”, “provavelmente”, “acho que”, “de memória” ou código copiado da memória do modelo para uma API externa.

O que conta como documentação

Use a fonte mais confiável disponível:

documentação do repositório local, especificações, ADRs, esquemas, tipos gerados, arquivos README dos pacotes e testes para comportamentos específicos do projeto.
Documentação oficial do produto, referências de API, guias de migração, registros de alterações, notas de lançamento e código-fonte/tipos do SDK para comportamentos de terceiros. Encontre-os por meio de pesquisas na web quando ainda não tiver a URL exata.
Metadados do registro de pacotes para versões. Antes de adicionar uma dependência, execute npm view version, pnpm view versionou o equivalente no ecossistema e, em seguida, leia a documentação dessa versão principal.
Código-fonte ou definições de tipos quando a documentação oficial estiver incompleta. Trate isso como evidência, não como lenda.

Evite o Stack Overflow, posts antigos de blogs, trechos aleatórios e a memória como fonte primária quando houver documentação oficial. Use fontes da comunidade apenas para depurar sintomas após conhecer o contrato oficial.

Fluxo de trabalho necessário

Identifique a superfície exata: nome do pacote, versão instalada, versão de destino, ponto de extremidade do provedor, comando da CLI, arquivo de configuração, auxiliar local, esquema ou recurso do produto.
Pesquise na web pela documentação oficial atual, a menos que a documentação relevante já esteja disponível localmente ou o usuário tenha fornecido uma URL. Use pesquisas direcionadas, como official docs, migration guide, ou API reference.
Abra e leia a documentação mais próxima dessa área. Dê preferência primeiro à documentação local para código interno e, em seguida, à documentação oficial do upstream. Para novos pacotes, verifique a versão mais recente antes de escrever comandos de importação, configuração ou instalação.
Extraia os poucos fatos necessários para a tarefa: nomes de opções, importações, regras de ciclo de vida, comportamento padrão, alterações compatíveis, limites, permissões e exemplos para a versão principal atual.
Implemente ou responda usando esses fatos. Se a documentação entrar em conflito com o código existente, inspecione o caminho do código local e identifique a discrepância.
Verifique com a menor verificação útil: verificação de tipos, testes, compilação, execução de teste da CLI, validação do esquema da API ou uma reprodução local.
Na resposta final, mencione os documentos ou arquivos locais consultados quando essa evidência afetar a recomendação ou a implementação.

Exemplos que devem acionar a consulta à documentação

“Adicione o Tailwind a este aplicativo.” Verifique a versão principal atual do Tailwind e sua documentação de instalação na web antes de criar arquivos de configuração ou presumir uma configuração antiga do PostCSS.
“Use o SDK de IA para transmitir respostas.” Verifique a versão principal atual do SDK de IA, as importações, os nomes dos pacotes de provedores, os auxiliares de streaming e os exemplos de servidor/tempo de execução na documentação oficial.
“Configure os webhooks do Stripe.” Leia a documentação atual do Stripe sobre verificação de assinatura, retentativas de eventos, segredo de endpoint e análise de corpo de solicitação antes de programar.
“Corrija este bug de cache do Next.js.” Leia a documentação da versão principal do Next.js instalada e do modo de roteador antes de presumir a semântica de invalidação do cache.
“Adicione migrações do Drizzle.” Leia a documentação atual do kit do Drizzle e as convenções de migração existentes no repositório antes de gerar arquivos.
“Crie uma GitHub Action.” Leia a documentação oficial sobre sintaxe e permissões das Actions, especialmente sobre pull_request, workflow_runOIDC, tokens e artefatos.
“Por que esse fluxo de OAuth falha?” Leia a documentação do provedor sobre escopos, URI de redirecionamento, PKCE, atualização de token e verificação de aplicativos antes de alterar o código.
“Use o sistema de planos/comentários/ações deste repositório.” Leia a documentação local, os registros de rotas/ações, esquemas e testes antes de criar endpoints ou propriedades.
“Atualize o Vite/Nitro/React.” Leia o guia de migração para saber a versão principal exata de destino antes de editar a configuração ou as importações.
“Que modelo devemos usar?” Leia a documentação atual do modelo do provedor, as páginas de preços/limites e os exemplos do SDK antes de fazer recomendações.

Quando uma rápida leitura local é suficiente

Não navegue pela web para cada pequena edição. Uma verificação da documentação pode ser local e breve quando a resposta já está no repositório: uso de helpers existentes, testes próximos, interfaces tipadas, clientes gerados, ADRs ou arquivos README dos pacotes. Mas se a tarefa depender de uma ferramenta externa, pacote, provedor ou comportamento atual do produto, a busca na web geralmente é o primeiro passo certo. Para sintaxe trivial da linguagem, correções de erros de digitação, formatação ou código autônomo sem contrato externo, proceda normalmente.

Se a documentação não estiver disponível

Se o acesso à rede, a autenticação ou a falta de arquivos locais impedirem a leitura da documentação, deixe isso bem claro antes de confiar na memória. Reduza a incerteza, inspecione o código-fonte ou os tipos, se disponíveis, e evite apresentar o resultado como confirmado e atual.

Ver no GitHub

---
name: read-the-damn-docs
description: Forces web searches and reading of official docs before implementing, integrating, or debugging third-party APIs, libraries, and services to ensure accuracy and avoid guesswork.
---

# 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.

## 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.

## 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.

## Required Workflow

1. Identify the exact surface: package name, installed version, target version,
   provider endpoint, CLI command, config file, local helper, schema, or product
   feature.
2. 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`.
3. 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.
4. 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.
5. Implement or answer using those facts. If the docs conflict with existing
   code, inspect the local code path and call out the discrepancy.
6. Verify with the smallest useful check: typecheck, tests, build, CLI dry run,
   API schema validation, or a local reproduction.
7. In the final answer, name the docs or local files consulted when that
   evidence affects the recommendation or implementation.

## 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.

## 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.

## 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.