BuilderIO/leia-a-droga-da-documentação

Leia a Droga da Documentação

Não adivinhe quando a documentação autoritativa pode responder à pergunta. O movimento correto mais comum é pesquisar na web pela documentação oficial atual, abrir as páginas relevantes e lê-las antes de programar. Para APIs, versões, comportamento de provedores, configuração, limites, hooks de ciclo de vida ou fluxos sensíveis à segurança, baseie a resposta no que a documentação realmente diz.

Gatilhos de Leitura Antes de Codificar

Leia a documentação antes de prosseguir quando qualquer um destes for verdadeiro:

• O usuário pede "último", "atual", "oficial", "suportado", "melhor prática", "recomendado", "hoje", "agora" ou "pesquise".
• A documentação necessária já não está no repositório ou fornecida pelo usuário. Pesquise na web pela documentação oficial em vez de esperar que a memória do modelo esteja atualizada.
• A tarefa adiciona, atualiza, configura ou importa um pacote, SDK, framework, plugin, CLI, modelo, recurso em nuvem ou integração de provedor.
• A API é de rápida evolução ou sensível a versões: SDKs de IA, APIs 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 OAuth, permissões, segredos, webhooks, faturamento, pagamentos, PII, criptografia, retenção de dados, migrações, tentativas, limites de taxa, cotas, cache, implantações ou conformidade.
• Um erro menciona depreciação, opções desconhecidas, exports ausentes, configuração inválida, campos não suportados, valores padrão alterados ou incompatibilidade de versão.
• Um repositório tem documentação local, ADRs, esquemas gerados, especificações OpenAPI, registros de rotas/ações, documentação de design-system ou READMEs de pacotes que podem definir o contrato.
• A escolha é cara para reverter: formatos de fio público, 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 externa.
• 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 autoritativa disponível:

• Documentação local do repositório, especificações, ADRs, esquemas, tipos gerados, READMEs de pacotes e testes para comportamento específico do projeto.
• Documentação oficial do produto, referências de API, guias de migração, changelogs, notas de versão e código fonte/tipos de SDK para comportamento de terceiros. Encontre-os com pesquisa na web quando você já não tiver a URL exata.
• Metadados do registro de pacotes para versões. Antes de adicionar uma dependência, execute npm view <pkg> version, pnpm view <pkg> version ou o equivalente do ecossistema e, em seguida, leia a documentação para aquela versão principal.
• Código fonte ou definições de tipo quando a documentação oficial estiver incompleta. Trate isso como evidência, não como folclore.

Evite Stack Overflow, postagens antigas de blog, snippets aleatórios e memória como fonte primária quando existir documentação oficial. Use fontes comunitárias apenas para depurar sintomas depois que o contrato autoritativo for conhecido.

Fluxo de Trabalho Obrigatório

1. Identifique a superfície exata: nome do pacote, versão instalada, versão alvo, endpoint do provedor, comando CLI, arquivo de configuração, helper local, esquema ou funcionalidade do produto.
2. Pesquise na web pela documentação oficial atual, a menos que a documentação relevante já esteja local ou o usuário tenha fornecido uma URL. Use pesquisas direcionadas como <produto> <funcionalidade> documentação oficial, <pacote> guia de migração ou <provedor> referência de API.
3. Abra e leia a documentação mais próxima dessa superfície. Prefira documentação local primeiro para código interno, depois documentação oficial upstream. Para novos pacotes, verifique a versão mais recente antes de escrever imports, configuração ou comandos de instalação.
4. Extraia os poucos fatos necessários para a tarefa: nomes de opções, imports, regras de ciclo de vida, comportamento padrão, mudanças que quebram compatibilidade, limites, permissões e exemplos para a versão principal atual.
5. Implemente ou responda usando esses fatos. Se a documentação conflitar com o código existente, inspecione o caminho do código local e aponte a discrepância.
6. Verifique com a verificação menor e mais útil: typecheck, testes, build, simulação de CLI, validação de esquema de API ou uma reprodução local.
7. Na resposta final, nomeie a documentação ou os arquivos locais consultados quando essa evidência afetar a recomendação ou implementação.

Exemplos Que Devem Acionar a Leitura de Documentação

• "Adicione 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 assumir o antigo setup PostCSS.
• "Use o AI SDK para transmitir respostas." Verifique a versão principal atual do AI SDK, imports, nomes de pacotes de provedores, helpers de streaming e exemplos de servidor/execução da documentação oficial.
• "Configure webhooks do Stripe." Leia a documentação atual do Stripe sobre verificação de assinatura, repetição de eventos, segredo de endpoint e parsing de corpo de framework antes de programar.
• "Corrija este bug de cache do Next.js." Leia a documentação para a versão principal do Next.js instalada e o modo de roteador antes de assumir semânticas de invalidação de cache.
• "Adicione migrações com Drizzle." Leia a documentação atual do Drizzle Kit e as convenções de migração existentes do repositório antes de gerar arquivos.
• "Crie uma GitHub Action." Leia a documentação oficial de sintaxe e permissões de Actions, especialmente para pull_request, workflow_run, OIDC, tokens e artefatos.
• "Por que este fluxo OAuth falha?" Leia a documentação do provedor sobre escopos, URI de redirecionamento, PKCE, renovação de token e verificação de aplicativo antes de alterar código.
• "Use o sistema de plano/comentário/ação deste repositório." Leia a documentação local, registros de rotas/ações, esquemas e testes antes de inventar endpoints ou props.
• "Atualize Vite/Nitro/React." Leia o guia de migração para a versão principal exata alvo antes de editar configuração ou imports.
• "Qual modelo devemos usar?" Leia a documentação atual do modelo do provedor, páginas de preços/limites e exemplos de SDK antes de recomendar.

Quando Uma Leitura Local Rápida É Suficiente

Não navegue na web para cada pequena edição. Uma passada pela 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 READMEs de pacotes. Mas se a tarefa depende de uma ferramenta externa, pacote, provedor ou comportamento atual do produto, a pesquisa na web geralmente é o primeiro passo correto. Para sintaxe de linguagem trivial, correções de digitação, formatação ou código autocontido sem contrato externo, prossiga normalmente.

Se a Documentação Não Estiver Disponível

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