adr-skill

Visão geral da skill adr-skill

O que a adr-skill faz

A adr-skill ajuda você a criar e manter Architecture Decision Records como documentos prontos para implementação, e não apenas como registros históricos. Seu valor real está em transformar uma escolha arquitetural em um ADR que um agente de código consiga executar com o mínimo de idas e vindas: restrições claras, não objetivos explícitos, arquivos a alterar nomeados, etapas de verificação e consequências concretas.

Para quem a adr-skill é mais indicada

Esta skill é mais indicada para leads de engenharia, staff engineers, equipes de plataforma e technical writers que documentam decisões que depois vão orientar trabalho de desenvolvimento. Ela é especialmente útil quando as decisões são difíceis de reverter, afetam vários contribuidores ou precisam ser compreendidas tanto por pessoas quanto por agentes de IA.

O principal trabalho a ser feito

Use a adr-skill quando você precisar:

• propor uma nova decisão arquitetural
• documentar uma decisão antes do início da implementação
• atualizar ou substituir um ADR existente
• iniciar o uso de ADRs em um repositório que ainda não tem nenhum
• impor uma estrutura consistente de ADRs em toda a base de código

Para adr-skill for Technical Writing, o encaixe mais forte é produzir documentos de decisão legíveis o suficiente para stakeholders, mas específicos o bastante para quem vai implementar.

Por que esta skill se destaca

O principal diferencial é a abordagem pensada para agentes. A skill não para em contexto, decisão e consequências. Ela força um plano de implementação com caminhos afetados, dependências, padrões a seguir, padrões a evitar, mudanças de configuração e critérios de verificação. Isso é bem mais acionável do que um prompt comum de “escreva um ADR para mim”.

O que verificar antes de adotar

Antes de instalar ou depender da adr-skill, confirme se sua equipe realmente quer que ADRs orientem a execução. Se o seu processo só precisa de notas leves de racional técnico, a skill pode parecer estruturada demais. Se a ideia é ter ADRs que sobrevivam à passagem de contexto e reduzam ambiguidades, esse rigor extra é justamente o ponto.

Como usar a skill adr-skill

Contexto de instalação da adr-skill

O trecho do repositório não mostra um comando de instalação específico da skill dentro de SKILL.md, mas o padrão mais comum é:

npx skills add vercel/ai --skill adr-skill

Depois de adicionar, use a skill no seu ambiente de coding com IA quando estiver prestes a tomar ou documentar uma decisão arquitetural.

Leia estes arquivos primeiro

Se você quer o caminho mais rápido para um uso eficaz da adr-skill, leia nesta ordem:

1. SKILL.md
2. references/adr-conventions.md
3. references/review-checklist.md
4. references/template-variants.md
5. references/examples.md

Depois, inspecione:

• scripts/bootstrap_adr.js
• scripts/new_adr.js
• scripts/set_adr_status.js

Essa ordem importa: as convenções mostram onde os ADRs devem ficar, o checklist explica os critérios de qualidade, as variantes de template ajudam a escolher a estrutura, e os exemplos mostram o nível de especificidade esperado.

Quais informações a adr-skill precisa de você

A adr-skill funciona melhor quando você fornece:

• a decisão a ser tomada
• o gatilho ou problema que está forçando essa decisão agora
• contexto do repositório e arquitetura existente
• restrições como latência, custo, compliance, modelo de deployment ou limitações da equipe
• não objetivos
• arquivos, módulos, serviços ou fluxos de trabalho que devem ser afetados
• alternativas já consideradas

Sem essas informações, a skill ainda consegue redigir um rascunho, mas ele tende a virar um ADR genérico, e não um documento realmente executável.

Como transformar uma ideia vaga em um prompt forte

Um prompt fraco:

• “Write an ADR for switching databases.”

Um prompt mais forte para adr-skill usage:

• “Create an ADR proposing SQLite for local dev and CI while keeping PostgreSQL in production. Context: shared Postgres makes tests flaky and adds 3+ minutes to CI setup. Constraints: local setup must work offline, CI setup under 10 seconds, production schema remains Postgres-compatible. Non-goals: no production migration, no full ORM rewrite. Affected paths likely include src/db/, test setup, and CI config. Include implementation plan and verification steps.”

O segundo prompt dá material suficiente para a skill escrever uma decisão que outro engenheiro ou agente consiga realmente implementar.

Escolha o template certo de forma intencional

Use o template simples quando a decisão já estiver majoritariamente resolvida e você precisar principalmente registrar o porquê, o que mudou e como implementar.

Use o template no estilo MADR quando houver opções realmente concorrentes, múltiplos direcionadores de decisão ou stakeholders que precisem revisar tradeoffs. A skill entrega os dois padrões por meio de:

• assets/templates/adr-simple.md
• assets/templates/adr-madr.md

Fluxo de trabalho típico da adr-skill na prática

Um fluxo prático costuma ser assim:

1. Pergunte à skill se a mudança realmente merece um ADR.
2. Deixe que ela questione você sobre contexto, restrições e não objetivos.
3. Redija o ADR com o template adequado.
4. Valide o resultado com references/review-checklist.md.
5. Edite com os caminhos, nomes e convenções específicos do repositório.
6. Crie ou atualize o arquivo no diretório de ADR escolhido.
7. Se necessário, altere o status do ciclo de vida mais tarde.

É aqui que o valor do adr-skill guide aparece: ele cobre o ciclo de vida inteiro, e não só a escrita do primeiro rascunho.

Como iniciar ADRs em um repositório que ainda não tem nenhum

Se o seu repositório ainda não tem estrutura de ADR, o script incluído é útil:

• scripts/bootstrap_adr.js

Ele pode criar o diretório de ADR, gerar um índice/README e adicionar um documento inicial de “Adopt architecture decision records”. Isso é mais útil do que inventar manualmente a estrutura de pastas, porque o repositório já embute escolhas de convenção, como detecção de diretório e estratégia de nomenclatura.

Como criar um novo ADR mais rápido

Para criação repetível, inspecione scripts/new_adr.js. Ele oferece opções práticas como:

• raiz do repositório
• sobrescrita do diretório de ADR
• título
• status
• escolha de template: simple ou madr
• estratégia de nome de arquivo
• campos de deciders, consulted e informed
• atualização de índice

Isso torna a adr-skill install mais valiosa para equipes que querem repetibilidade em vez de geração pontual de texto.

Como as mudanças de status são tratadas

O scripts/set_adr_status.js incluído atualiza o status do ADR no próprio arquivo. Isso importa se sua equipe trata ADRs como documentos vivos, com estados como proposto, aceito, rejeitado, descontinuado ou substituído, e não como arquivos markdown estáticos.

Convenções do repositório que afetam a qualidade da saída

A skill tem uma opinião clara sobre qualidade de ADR:

• restrições devem ser mensuráveis
• não objetivos devem ser explícitos
• consequências devem gerar tarefas de acompanhamento
• planos de implementação devem nomear caminhos reais
• a verificação deve mostrar como confirmar que a decisão foi implementada corretamente

Se o seu prompt omitir isso, a qualidade da saída cai bastante, mesmo que o texto continue bem escrito.

Convenções de diretório e nomenclatura com as quais alinhar

Segundo references/adr-conventions.md, a skill prioriza primeiro as convenções já existentes no repositório e, só na ausência delas, sugere locais como docs/decisions/ ou adr/. Ela também prefere nomes de arquivo previsíveis, como YYYY-MM-DD-title-with-dashes.md, a menos que o repositório já siga outra convenção.

Isso significa que você não deve impor cegamente os padrões da skill sobre práticas já consolidadas do projeto.

FAQ da skill adr-skill

A adr-skill é melhor do que um prompt normal?

Sim, quando o objetivo é um ADR durável e orientado à implementação. Um prompt genérico pode produzir um documento legível, mas a adr-skill adiciona estrutura em torno de gatilhos, restrições mensuráveis, não objetivos, planejamento de implementação e critérios de revisão. Em geral, isso reduz mais ambiguidade do que um prompt improvisado.

A adr-skill é adequada para iniciantes?

Sim, com uma ressalva: ela ajuda iniciantes a escrever ADRs melhores, mas não consegue inventar contexto arquitetural que está faltando. Se você está começando com ADRs, os exemplos e as variantes de template tornam a curva de aprendizado mais leve. Se você ainda está conhecendo o sistema documentado, espere precisar levantar mais informações antes.

Quando a adr-skill não é uma boa opção?

Evite a adr-skill quando:

• a mudança for trivial e reversível
• você só precisar de uma nota curta de design
• a equipe não mantiver ADRs ao longo do tempo
• ninguém for usar o documento para orientar a implementação

Nesses casos, a estrutura pode parecer mais pesada do que a decisão realmente exige.

A adr-skill consegue lidar com atualizações e ADRs substituídos?

Sim. A skill não se limita à criação de novos ADRs. Ela suporta atualização, aceitação, rejeição, descontinuação e substituição de decisões, o que é importante em repositórios onde a arquitetura evolui em vez de permanecer fixa.

A adr-skill ajuda technical writers ou só engenheiros?

Ajuda ambos. Em casos de uso de Technical Writing, a adr-skill é valiosa porque força os documentos de decisão a responder o que mudou, por que agora, o que está fora de escopo e como a implementação deve ser verificada. Isso torna a documentação mais útil para times de engenharia e futuros mantenedores.

Eu preciso usar os scripts incluídos?

Não. Você pode usar a adr-skill apenas como apoio de redação e revisão. Os scripts importam quando você quer criação padronizada, bootstrap ou atualização de status em todo o repositório.

Como melhorar a skill adr-skill

Dê à adr-skill gatilhos de decisão, não apenas temas

A melhor melhoria que você pode fazer é explicar por que o ADR existe agora. “Need an ADR for caching” é fraco. “Current API p95 is 900ms, traffic doubled, and we need sub-200ms reads for product search” é muito mais forte. O gatilho molda o documento inteiro.

Nomeie restrições e limites concretos

A adr-skill foi feita para decisões mensuráveis. Inclua números e limites sempre que possível:

• metas de latência
• tetos de custo
• requisitos de compatibilidade
• janelas de rollout
• restrições de compliance
• fronteiras de responsabilidade operacional

Isso desloca a saída de uma escrita abstrata sobre arquitetura para documentação de decisão de verdade.

Inclua os não objetivos desde cedo

Muitos ADRs falham porque insinuam escopo demais. Diga à adr-skill o que está explicitamente fora de escopo:

• nenhuma migração de dados de produção
• nenhuma mudança de versão de API
• nenhuma decisão de vendor lock-in neste ADR
• nenhum redesign de UI

Não objetivos claros reduzem scope creep e produzem planos de implementação melhores.

Aponte para caminhos e padrões reais

Se você quer um plano de implementação útil, mencione arquivos, módulos reais ou código semelhante que já exista no repositório. Por exemplo:

• “Follow the pattern in src/payments/stripe.ts.”
• “Avoid adding logic to pages/api/*; use route handlers under app/api/.”
• “Config lives in infra/terraform/ and .github/workflows/.”

Esse é um dos maiores fatores de alavancagem para melhorar a qualidade de saída da adr-skill skill.

Use o checklist de revisão depois do primeiro rascunho

Não pare na primeira saída. Compare o ADR com references/review-checklist.md, especialmente:

• um recém-chegado consegue entender o gatilho?
• as restrições são específicas o suficiente para orientar ação?
• os caminhos afetados estão nomeados?
• tarefas de acompanhamento e etapas de verificação estão explícitas?
• alguma consequência é só uma reformulação vaga da decisão?

É nesse checklist que mora boa parte do valor prático da skill.

Escolha o template que combina com o formato da decisão

Um modo de falha comum é usar a estrutura MADR, mais pesada em opções, para uma escolha simples, ou usar o template simples quando os stakeholders precisam de um registro claro dos tradeoffs. Faça o template acompanhar a complexidade da decisão para que o ADR continue legível.

Evite texto com cara de placeholder

Os exemplos do repositório deixam claro que texto placeholder não deve sobreviver até um ADR real. Se o primeiro rascunho vier com frases vagas como “use best practices” ou “update relevant files”, reescreva isso em detalhes operacionais:

• versões específicas de dependências
• configurações nomeadas
• ordem de migração
• checagens de rollout ou rollback
• classes ou suítes de teste exatas

Itere sobre as consequências, não só sobre a decisão

Muitos usuários refinam a seção Decision e ignoram Consequences. Isso é um erro. Consequências fortes devem dizer aos futuros implementadores o que passa a ficar mais fácil, mais difícil, mais arriscado, mais caro ou obrigatório a partir dali. Se as consequências forem fracas, o ADR não vai orientar bem a execução.

Melhore a adr-skill para adoção em equipe

Se você quer um uso mais amplo na equipe, padronize três coisas em torno da adr-skill:

• uma convenção única de diretório de ADR
• uma escolha padrão de template por tipo de decisão
• um vocabulário único de status

Isso reduz atrito e torna os scripts da skill mais úteis em diferentes repositórios.

Melhor checagem final antes de publicar

Antes de aceitar um ADR redigido com adr-skill, faça uma pergunta difícil: um agente de código conseguiria implementar essa mudança sem depender de conhecimento tribal escondido? Se a resposta for não, adicione contexto, caminhos, padrões, restrições ou etapas de verificação até a resposta virar sim.