version: "1.0.0" name: fontes-oficiais description: Fundamenta cada decisão de implementação em documentação oficial. Use quando o usuário quiser código com fontes citadas, livre de padrões desatualizados, ou ao construir com qualquer framework ou biblioteca em que a correção importa. metadata: fase: construir origem: addyosmani/agent-skills (MIT)

Desenvolvimento Guiado por Fontes Oficiais

Visão geral

Toda decisão de código específica de framework deve estar respaldada por documentação oficial. Não implemente de memória — verifique, cite e deixe o usuário ver suas fontes. Dados de treinamento envelhecem, APIs são descontinuadas, boas práticas evoluem. Esta skill garante código confiável porque cada padrão remete a uma fonte autoritativa verificável.

Quando usar

• O usuário quer código que siga as boas práticas atuais de um framework
• Construir boilerplate, código inicial ou padrões que serão copiados pelo projeto
• O usuário pede explicitamente implementação documentada, verificada ou "correta"
• Implementar funcionalidades em que a abordagem recomendada do framework importa (formulários, roteamento, busca de dados, gerenciamento de estado, auth)
• Revisar ou melhorar código que usa padrões específicos de framework
• Sempre que estiver prestes a escrever código de framework de memória

Quando NÃO usar: quando a correção não depende de versão específica (renomear variáveis, corrigir typos, mover arquivos); lógica pura que funciona igual em todas as versões; ou quando o usuário quer explicitamente velocidade em vez de verificação.

O fluxo

DETECTAR ──→ BUSCAR ──→ IMPLEMENTAR ──→ CITAR
   │            │            │            │
   ▼            ▼            ▼            ▼
 Qual        Obter a      Seguir os    Mostrar
 stack?      doc          padrões      suas
             relevante    documentados fontes

Etapa 1: Detectar stack e versões

Leia o arquivo de dependências do projeto para identificar versões exatas:

package.json    → Node/React/Vue/Angular/Svelte
composer.json   → PHP/Symfony/Laravel
requirements.txt / pyproject.toml → Python/Django/Flask
go.mod          → Go
Cargo.toml      → Rust
Gemfile         → Ruby/Rails

Declare explicitamente o que encontrou:

STACK DETECTADA:
- React 19.1.0 (do package.json)
- Vite 6.2.0
- Tailwind CSS 4.0.3
→ Buscando a documentação oficial dos padrões relevantes.

Se as versões estiverem ausentes ou ambíguas, pergunte ao usuário. Não adivinhe — a versão determina quais padrões estão corretos.

Etapa 2: Buscar a documentação oficial

Busque a página específica da documentação para a funcionalidade que vai implementar. Não a home, não a doc inteira — a página relevante.

Hierarquia de fontes (em ordem de autoridade):

Não autoritativas — nunca cite como fonte primária: respostas do Stack Overflow, posts de blog ou tutoriais (mesmo populares), documentação gerada por IA, seus próprios dados de treinamento (esse é justamente o ponto — verifique-os).

Seja preciso no que busca:

RUIM: Buscar a home do React
BOM:  Buscar react.dev/reference/react/useActionState
 
RUIM: Pesquisar "django authentication best practices"
BOM:  Buscar docs.djangoproject.com/en/6.0/topics/auth/

Após buscar, extraia os padrões-chave e anote avisos de descontinuação ou guias de migração. Quando fontes oficiais conflitarem entre si (ex.: um guia de migração contradiz a referência da API), exponha a discrepância ao usuário e verifique qual padrão realmente funciona na versão detectada.

Etapa 3: Implementar seguindo os padrões documentados

Escreva código que corresponda ao que a documentação mostra:

• Use as assinaturas de API da doc, não da memória
• Se a doc mostra um jeito novo de fazer algo, use o jeito novo
• Se a doc descontinua um padrão, não use a versão descontinuada
• Se a doc não cobre algo, sinalize como não verificado

Quando a doc conflita com o código existente do projeto:

CONFLITO DETECTADO:
A base existente usa useState para o estado de carregamento do formulário,
mas a doc do React 19 recomenda useActionState para esse padrão.
(Fonte: react.dev/reference/react/useActionState)
 
Opções:
A) Usar o padrão moderno (useActionState) — consistente com a doc atual
B) Seguir o código existente (useState) — consistente com a base
→ Qual abordagem você prefere?

Exponha o conflito. Não escolha silenciosamente.

Etapa 4: Citar as fontes

Todo padrão específico de framework recebe citação. O usuário precisa poder verificar cada decisão.

Em comentários de código:

// Tratamento de formulário no React 19 com useActionState
// Fonte: https://react.dev/reference/react/useActionState#usage
const [state, formAction, isPending] = useActionState(submitOrder, initialState);

Na conversa: explique a decisão, cite a URL completa e, quando a decisão não for óbvia, cite o trecho relevante da doc.

Regras de citação:

• URLs completas, não encurtadas
• Prefira deep links com âncoras (ex.: /useActionState#usage em vez de /useActionState) — âncoras sobrevivem melhor a reestruturações da doc
• Cite o trecho relevante quando ele sustenta uma decisão não óbvia
• Inclua dados de suporte de navegador/runtime ao recomendar recursos de plataforma
• Se não encontrar documentação para um padrão, diga explicitamente:

NÃO VERIFICADO: não encontrei documentação oficial para este
padrão. Ele vem de dados de treinamento e pode estar desatualizado.
Verifique antes de usar em produção.

Honestidade sobre o que não pôde ser verificado vale mais que falsa confiança.

Racionalizações comuns

Sinais de alerta

• Escrever código específico de framework sem consultar a doc daquela versão
• Usar "acredito" ou "acho" sobre uma API em vez de citar a fonte
• Implementar um padrão sem saber a qual versão ele se aplica
• Citar Stack Overflow ou posts de blog em vez de documentação oficial
• Usar APIs descontinuadas porque aparecem nos dados de treinamento
• Não ler package.json / arquivos de dependência antes de implementar
• Entregar código sem citação de fonte para decisões específicas de framework
• Buscar um site de docs inteiro quando só uma página é relevante

Portão de aprovação

Apresente: a stack detectada com versões, a lista de fontes oficiais consultadas (URLs completas), os conflitos encontrados (doc × código existente) e tudo que ficou marcado como não verificado. O humano aprova: as escolhas de padrão nos pontos de conflito e a aceitação (ou não) dos trechos não verificados. Só avance após aprovação explícita.

Verificação

Após implementar com desenvolvimento guiado por fontes:

• [ ] Versões de framework e bibliotecas identificadas a partir do arquivo de dependências
• [ ] Documentação oficial buscada para os padrões específicos de framework
• [ ] Todas as fontes são documentação oficial, não posts de blog ou dados de treinamento
• [ ] O código segue os padrões mostrados na doc da versão atual
• [ ] Decisões não triviais incluem citações com URLs completas
• [ ] Nenhuma API descontinuada em uso (verificado contra guias de migração)
• [ ] Conflitos entre doc e código existente foram expostos ao usuário
• [ ] Tudo que não pôde ser verificado está sinalizado explicitamente como não verificado