documentation-and-adrs

Visão geral da skill documentation-and-adrs

O que a skill documentation-and-adrs faz

A skill documentation-and-adrs ajuda um agente a escrever documentação técnica orientada a decisões, especialmente Architecture Decision Records (ADRs). O trabalho real dela não é “escrever mais documentação”, e sim “registrar por que a equipe escolheu essa abordagem, quais restrições importavam e quais alternativas foram descartadas”. Isso a torna útil quando o código, sozinho, não explica decisões de manutenção no futuro.

Para quem ela funciona melhor e qual problema resolve

Essa skill é mais indicada para engenheiros, tech leads, arquitetos e equipes fazendo Technical Writing sobre arquitetura, APIs, infraestrutura, autenticação, modelos de dados ou mudanças em funcionalidades visíveis ao usuário. Use documentation-and-adrs quando você precisar de contexto durável para engenheiros ou agentes futuros, e não apenas de uma explicação bem escrita para a tarefa de hoje.

O que a diferencia de um prompt genérico

Um prompt comum pode gerar um bom resumo, mas a documentation-and-adrs skill é voltada a registros de decisão: contexto, restrições, opções, trade-offs e consequências. Esse enquadramento importa porque a maioria da documentação fraca falha ao descrever a implementação e omitir o raciocínio que os mantenedores futuros realmente precisam.

Quando não instalar

Evite esta skill se você só quer comentários inline no código, uma limpeza leve de README ou documentação para protótipos descartáveis. Ela também é uma escolha ruim para caminhos de código óbvios, em que a implementação já comunica a intenção e não existe histórico de decisão relevante para preservar.

Como usar a skill documentation-and-adrs

Contexto de instalação e por onde começar a leitura

Para documentation-and-adrs install, adicione a skill do repositório addyosmani/agent-skills e leia primeiro skills/documentation-and-adrs/SKILL.md. Esta skill vem como um único arquivo de orientação, então não há scripts auxiliares nem arquivos de referência para apoiar. Isso significa que a qualidade da sua entrada importa mais do que em uma skill apoiada por ferramentas.

Se o seu ambiente suportar instalação de skills, use:
npx skills add addyosmani/agent-skills --skill documentation-and-adrs

Depois, revise:

• skills/documentation-and-adrs/SKILL.md

Que tipo de entrada a skill documentation-and-adrs precisa

A skill funciona melhor quando você fornece a superfície da decisão, e não só o formato de saída desejado. Entradas fortes normalmente incluem:

• a mudança proposta
• sistemas ou APIs afetados
• restrições como desempenho, compliance, custo, prazos ou compatibilidade
• alternativas consideradas
• consequências esperadas e riscos
• público-alvo e local de saída, como docs/adr/ ou docs/architecture/

Entrada fraca: “Escreva um ADR para migrar para GraphQL.”

Entrada mais forte:

• Estado atual: API REST com dificuldades de versionamento entre clientes mobile
• Decisão necessária: adotar ou não GraphQL para novas superfícies do produto
• Restrições: manter endpoints REST existentes por 12 meses, equipe de plataforma pequena, necessidade de flexibilidade de campos no cliente
• Alternativas: convenções REST melhores, tRPC, GraphQL gateway
• Dono da decisão: líder de plataforma
• Saída: ADR com status, contexto, decisão, consequências e alternativas rejeitadas

Como pedir melhores resultados com documentation-and-adrs

Um bom prompt para documentation-and-adrs usage deve pedir estrutura e qualidade do raciocínio ao mesmo tempo. Um padrão confiável é:

1. Declare a decisão ou o tipo de documento.
2. Forneça contexto do projeto e restrições.
3. Nomeie as opções consideradas.
4. Peça ao agente para explicitar trade-offs, premissas e ações de acompanhamento.
5. Especifique o formato final.

Exemplo de prompt:
“Use a skill documentation-and-adrs para redigir um ADR sobre a escolha de uma estratégia de autenticação para nosso B2B SaaS. Compare auth gerenciado, OAuth autogerenciado e uma abordagem first com passkeys. Inclua contexto, restrições, critérios que pesaram na decisão, opções rejeitadas, consequências, notas de migração e perguntas em aberto. O público é formado por futuros engenheiros de backend e segurança.”

Fluxo de trabalho recomendado para equipes reais

Use esta ordem para um fluxo prático com documentation-and-adrs guide:

1. Reúna fatos de issues, PRs, notas de arquitetura e conversas da equipe.
2. Peça ao agente para extrair os fatores da decisão antes de redigir.
3. Revise a primeira versão em busca de alternativas ausentes e restrições não explicitadas.
4. Transforme a saída em um documento do repositório ou ADR com nomeação e local estáveis.
5. Atualize o registro quando a decisão for validada em produção.

Essa skill é especialmente boa para Technical Writing quando combinada com material-fonte concreto. Ela fica muito mais fraca se você pedir que ela infira raciocínio de negócio ou de arquitetura que não foi fornecido em nenhum lugar.

Perguntas frequentes sobre a skill documentation-and-adrs

A skill documentation-and-adrs serve para iniciantes em Technical Writing?

Sim, desde que a pessoa iniciante já tenha acesso aos fatos por trás da decisão. A skill oferece uma estrutura útil para ADRs e documentos de decisão, mas não substitui julgamento técnico. Iniciantes costumam ter os melhores resultados quando fornecem atas de reunião, links de issues ou uma lista inicial de prós e contras, em vez de pedir um documento do zero.

Em que ela é diferente de pedir “write docs”?

Prompts genéricos de documentação normalmente otimizam a legibilidade. documentation-and-adrs otimiza a manutenção das decisões: por que esse caminho foi escolhido, quais restrições existiam e o que leitores futuros precisam saber antes de mudar isso. Essa diferença pesa especialmente em arquitetura, APIs públicas e escolhas de infraestrutura.

Quais são os limites desta skill?

A skill não é um sistema de documentação para o repositório inteiro, nem um linter de estilo, nem um gerador de documentação com automação. Ela oferece orientação de processo e estrutura, não scripts ou templates impostos por ferramenta. Se você precisa de sincronização automática de docs, imposição de padrões ou fluxos de publicação, vai precisar de outras ferramentas ao redor dela.

Quando eu não devo usar a skill documentation-and-adrs?

Não a use para detalhes triviais de implementação, refatorações óbvias, comentários duplicados no código ou protótipos especulativos sem valor duradouro. Se a equipe ainda não tomou uma decisão de verdade, use a skill para comparar opções, mas não finja que um ADR final já existe antes de a decisão ter sido realmente tomada.

Como melhorar a skill documentation-and-adrs

Dê entradas no nível de decisão, não apenas no nível de resumo

A forma mais rápida de melhorar a saída da documentation-and-adrs skill é fornecer evidências que sustentem uma decisão. Inclua alternativas rejeitadas, restrições e consequências esperadas. Sem isso, a saída pode soar polida, mas genérica. Se possível, traga trechos de design docs, descrições de PR, RFCs ou análises de incidentes.

Fique atento aos modos de falha mais comuns

Os problemas mais frequentes são:

• repetir detalhes de implementação em vez de documentar o raciocínio
• listar alternativas sem explicar por que perderam
• omitir riscos, custos de migração ou consequências operacionais
• escrever para quem revisa hoje, e não para quem vai manter o sistema no futuro

Se perceber qualquer um desses problemas, peça uma revisão focada em “fatores da decisão, alternativas rejeitadas e consequências posteriores”.

Itere na estrutura depois do primeiro rascunho

Depois da primeira versão, peça ao agente para fortalecer trechos fracos em vez de reescrever tudo. Bons pedidos de acompanhamento incluem:

• “Torne os trade-offs mais explícitos.”
• “Adicione premissas e o que mudaria essa decisão.”
• “Separe as consequências imediatas do impacto de manutenção no longo prazo.”
• “Reescreva para engenheiros futuros que não conhecem este subsistema.”

Adapte a skill às convenções do seu repositório

Para tornar documentation-and-adrs for Technical Writing mais útil, diga ao agente quais são suas convenções de nomeação de arquivos, formato de ADR e locais de documentação. Por exemplo, especifique se você usa ADRs sequenciais como docs/adrs/0007-auth-strategy.md ou docs temáticos em docs/architecture/. Quanto mais o seu prompt se aproximar das convenções de documentação do repositório, menos ajustes você precisará fazer depois da geração.