clanker25/ai

Skill ADR

Filosofia

ADRs criados com este skill são especificações executáveis para agentes de codificação. Um humano aprova a decisão; um agente a implementa. O ADR deve conter tudo o que o agente precisa para escrever código correto sem fazer perguntas de acompanhamento.

Isso significa:

• Restrições devem ser explícitas e mensuráveis, não apenas sentimentos
• Decisões devem ser específicas o suficiente para agir ("usar PostgreSQL 16 com pgvector", não "usar um banco de dados")
• Consequências devem mapear tarefas concretas de acompanhamento
• Não-objetivos devem ser declarados para evitar aumento de escopo
• O ADR deve ser autocontido — sem suposições de conhecimento tribal
• O ADR deve incluir um plano de implementação — quais arquivos modificar, quais padrões seguir, quais testes escrever e como verificar se a decisão foi implementada corretamente

Quando Escrever um ADR

Escreva um ADR quando uma decisão:

• Muda como o sistema é construído ou operado (nova dependência, padrão de arquitetura, escolha de infraestrutura, design de API)
• É difícil de reverter depois que o código é escrito com base nela
• Afeta outras pessoas ou agentes que trabalharão neste repositório posteriormente
• Tem alternativas reais que foram consideradas e rejeitadas

NÃO escreva um ADR para:

• Escolhas rotineiras de implementação dentro de um padrão estabelecido
• Correções de bugs ou correções de digitação
• Decisões já capturadas em um ADR existente (atualize-o)
• Preferências de estilo já cobertas por linters ou formatadores

Em caso de dúvida: se um agente futuro trabalhando neste repositório se beneficiaria em saber por que essa escolha foi feita, escreva o ADR.

Gatilhos Proativos de ADR (Para Agentes)

Se você é um agente codificando em um repositório e encontrar qualquer uma dessas situações, pare e proponha um ADR antes de continuar:

• Você está prestes a introduzir uma nova dependência que ainda não existe no projeto
• Você está prestes a criar um novo padrão arquitetural (nova forma de lidar com erros, nova camada de acesso a dados, nova convenção de API) que outros códigos precisarão seguir
• Você está prestes a fazer uma escolha entre duas ou mais alternativas reais e os trade-offs não são óbvios
• Você está prestes a mudar algo que contradiz um ADR existente aceito
• Você percebe que está escrevendo um comentário longo explicando "por que" — essa justificativa pertence a um ADR

Como propor: Diga ao humano qual decisão você encontrou, por que é importante e pergunte se eles querem capturá-la como um ADR. Se sim, execute o fluxo de trabalho completo de quatro fases. Se não, anote a decisão em um comentário de código e prossiga.

Criando um ADR: Fluxo de Trabalho de Quatro Fases

Cada ADR passa por quatro fases. Não pule fases.

Fase 0: Escaneie o Repositório

Antes de fazer qualquer pergunta, colete contexto do repositório:

1. Encontre ADRs existentes. Verifique contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/ por registros existentes. Leia-os. Anote:

   • Convenções existentes (diretório, nomenclatura, estilo de template)
   • Decisões que se relacionam ou restringem a atual
   • Quaisquer ADRs que esta nova decisão pode substituir

2. Verifique a pilha de tecnologia. Leia package.json, go.mod, requirements.txt, Cargo.toml ou equivalente. Anote dependências e versões relevantes.

3. Encontre padrões de código relacionados. Se a decisão envolve uma área específica (por exemplo, "como lidamos com autenticação"), escaneie implementações existentes. Identifique os arquivos, diretórios e padrões específicos que serão afetados pela decisão.

4. Verifique referências de ADR no código. Procure por referências de ADR em comentários e documentação (veja "Vinculação Código ↔ ADR" abaixo). Isso revela quais decisões existentes governam quais partes do repositório.

5. Anote o que encontrou. Leve este contexto para a Fase 1 — isso afiará suas perguntas e evitará que o ADR contradiga decisões existentes.

Fase 1: Capture a Intenção (Socrático)

Entreviste o humano para entender o espaço da decisão. Faça perguntas uma de cada vez, construindo sobre respostas anteriores. Não solte uma lista de perguntas.

Perguntas principais (faça aproximadamente nesta ordem, pule o que já está claro pelo contexto ou Fase 0):

1. O que você está decidindo? — Obtenha um título curto e específico. Force uma frase verbal ("Escolher X", "Adotar Y", "Substituir Z por W").
2. Por que agora? — O que quebrou, o que está mudando ou o que quebrará se você não fizer nada? Este é o gatilho.
3. Quais restrições existem? — Pilha de tecnologia, prazo, orçamento, tamanho da equipe, código existente, conformidade. Seja concreto. Faça referência ao que encontrou na Fase 0 ("Vejo que você já está usando X — isso restringe isso?").
4. Como é o sucesso? — Resultados mensuráveis. Vá além de "funciona" para especificidades (latência, throughput, DX, custo de manutenção).
5. Quais opções você considerou? — Pelo menos duas. Para cada: qual é o trade-off principal? Se eles têm apenas uma opção, ajude-os a articular por que as alternativas foram rejeitadas.
6. Qual é sua inclinação atual? — Capture a intuição inicial cedo. Frequentemente revela prioridades não declaradas.
7. Quem precisa saber ou aprovar? — Tomadores de decisão, especialistas consultados, partes interessadas informadas.
8. O que um agente precisaria para implementar isso? — Quais arquivos/diretórios são afetados? Que padrões existentes deve seguir? O que deve evitar? Que testes provariam que está funcionando? Isso alimenta diretamente o Plano de Implementação.

Acompanhamentos adaptativos: Com base nas respostas, aprofunde onde a decisão é confusa. Acompanhamentos comuns:

• "Qual é o pior resultado possível se esta decisão estiver errada?"
• "O que faria você revisitar isso em 6 meses?"
• "Há algo que você está explicitamente escolhendo NÃO fazer?"
• "A que artefato anterior ou padrões existentes no repositório isso se relaciona?"
• "Encontrei [ADR/pattern existente] — esta nova decisão interage com ele?"

Quando parar: Você tem o suficiente quando pode preencher cada seção do ADR — incluindo o Plano de Implementação — sem inventar coisas. Se estiver adivinhando em qualquer seção, faça outra pergunta.

Portão do Resumo de Intenção: Antes de passar para a Fase 2, apresente um resumo estruturado do que capturou e peça ao humano para confirmar ou corrigir:

Aqui está o que estou capturando para o ADR:

• Título: {título}
• Gatilho: {por que agora}
• Restrições: {lista}
• Opções: {opção 1} vs {opção 2} [vs ...]
• Inclinação: {qual opção e por que}
• Não-objetivos: {o que está explicitamente fora de escopo}
• ADRs/código relacionados: {o que existe com que isso interage}
• Arquivos/áreas afetados: {onde no repositório isso reside}
• Verificação: {como saberemos que foi implementado corretamente}

Isso captura sua intenção? Algo a adicionar ou corrigir?

Não prossiga para a Fase 2 até que o humano confirme o resumo.

Fase 2: Rascunhe o ADR

1. Escolha o diretório do ADR.

   • Se um existir (encontrado na Fase 0), use-o.
   • Se nenhum existir, crie contributing/decisions/ (se contributing/ existir), docs/decisions/ (padrão MADR), ou adr/ (repositórios mais simples).

2. Escolha uma estratégia de nome de arquivo.

   • Se ADRs existentes usarem prefixos de data (AAAA-MM-DD-...), continue isso.
   • Caso contrário, use apenas slugs (escolher-banco-de-dados.md).

3. Escolha um template.

   • Use assets/templates/adr-simple.md para decisões diretas (um vencedor claro, trade-offs mínimos).
   • Use assets/templates/adr-madr.md quando precisar documentar múltiplas opções com prós/contras/drivers estruturados.
   • Veja references/template-variants.md para orientação.

4. Preencha cada seção a partir do resumo de intenção confirmado. Não deixe texto de espaço reservado. Cada seção deve conter conteúdo real ou ser removida (apenas seções opcionais).

5. Escreva o Plano de Implementação. Esta é a seção mais importante para ADRs orientados a agentes. Diz ao próximo agente exatamente o que fazer. Veja o template para estrutura.

6. Escreva critérios de Verificação como caixas de seleção. Eles devem ser específicos o suficiente para que um agente possa verificar cada um programaticamente ou manualmente.

7. Gere o arquivo.

   • Preferido: execute scripts/new_adr.js (lida com diretório, nomenclatura e atualizações opcionais de índice).
   • Se não puder executar scripts, copie um template de assets/templates/ e preencha manualmente.

Fase 3: Revise Contra a Checklist

Após rascunhar, revise o ADR contra a checklist de prontidão para agente em references/review-checklist.md.

Apresente a revisão como um resumo, não um despejo de checklist bruto. Formate:

Revisão do ADR

✅ Passa: {lista o que está sólido — por exemplo, "contexto é autocontido, plano de implementação cobre arquivos afetados, critérios de verificação são verificáveis"}

⚠️ Lacunas encontradas:

• {lacuna específica 1 — por exemplo, "Plano de Implementação não menciona arquivos de teste — qual suíte de teste deve cobrir isso?"}
• {lacuna específica 2}

Recomendação: {Pode enviar / Corrigir as lacunas primeiro / Precisa de mais trabalho na Fase 1}

Apenas destaque falhas e pontos fortes notáveis — não recite cada item da checklist.

Se houver lacunas, proponha correções específicas. Não apenas aponte problemas — ofereça soluções e peça ao humano para aprovar.

Não finalize até que o ADR passe na checklist ou o humano aceite explicitamente as lacunas.

Consultando ADRs (Fluxo de Leitura)

Agentes devem ler ADRs existentes antes de implementar mudanças em um repositório que os tenha. Isso não faz parte do fluxo de criação de um ADR — é uma operação independente que qualquer agente deve fazer.

Quando Consultar ADRs

• Antes de começar o trabalho em uma funcionalidade que toca arquitetura (auth, camada de dados, design de API, infraestrutura)
• Quando você encontrar um padrão no código e se perguntar "por que é feito assim?"
• Antes de propor uma mudança que possa contradizer uma decisão existente
• Quando um humano disser "verifique os ADRs" ou "há uma decisão sobre isso"
• Quando você encontrar uma referência de ADR em um comentário de código

Como Consultar ADRs

1. Encontre o diretório de ADR. Verifique contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/. Também verifique se há um arquivo de índice (README.md ou index.md).

2. Escaneie títulos e status. Leia o índice ou liste nomes de arquivos. Concentre-se em ADRs accepted — estas são decisões ativas.

3. Leia ADRs relevantes completamente. Não leia apenas o título — leia contexto, decisão, consequências, não-objetivos E o Plano de Implementação. O Plano de Implementação informa quais padrões seguir e quais arquivos são governados por esta decisão.

4. Respeite as decisões. Se um ADR aceito disser "use PostgreSQL", não proponha mudar para MongoDB sem criar um novo ADR que o substitua. Se você encontrar um conflito entre o que o código faz e o que o ADR diz, sinalize ao humano.

5. Siga o Plano de Implementação. Ao implementar código em uma área governada por um ADR, siga os padrões especificados em seu Plano de Implementação. Se o plano disser "todas as novas consultas passam pela camada de acesso a dados em src/db/", faça isso.

6. Referencie ADRs em seu trabalho. Adicione referências de ADR em comentários de código e descrições de PR (veja "Vinculação Código ↔ ADR" abaixo).

Vinculação Código ↔ ADR

ADRs devem ser vinculados bidirecionalmente ao código que governam.

ADR → Código (no Plano de Implementação)

A seção Plano de Implementação nomeia arquivos, diretórios e padrões específicos:

## Implementation Plan

- **Affected paths**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Pattern**: all database queries go through `src/db/client.ts`

Código → ADR (em comentários)

Ao implementar código guiado por um ADR, adicione um comentário referenciando-o:

// ADR: Using better-sqlite3 for test database
// See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

Mantenha-os leves — um comentário no ponto de entrada, não em cada linha. O objetivo é a descoberta: quando um agente futuro ler este código, ele pode encontrar a justificativa.

Por Que Isso Importa

• Um agente trabalhando em src/db/ pode encontrar quais ADRs governam essa área
• Um agente lendo um ADR pode encontrar o código que o implementa
• Quando um ADR é substituído, as referências de código facilitam encontrar todo o código que precisa ser atualizado

Outras Operações

Atualizar um ADR Existente

1. Identifique a intenção:

   • Aceitar / rejeitar: mude o status, adicione qualquer contexto final.
   • Depreciar: status → deprecated, explique o caminho de substituição.
   • Substituir: crie um novo ADR, vincule ambos os lados (antigo → novo, novo → antigo).
   • Adicionar aprendizados: anexe a ## Mais Informações com um carimbo de data. Não reescreva o histórico.

2. Use scripts/set_adr_status.js para mudanças de status (suporta front matter YAML, status de marcador e status de seção).

Ciclo de Vida Pós-Aceitação

Após um ADR ser aceito:

1. Crie tarefas de implementação. Cada item no Plano de Implementação e cada acompanhamento em Consequências deve se tornar uma tarefa rastreável (issue, ticket ou TODO).
2. Referencie o ADR em PRs. Vincule o ADR nas descrições de PR, por exemplo "Implementa contributing/decisions/2025-06-15-use-sqlite-for-test-database.md."
3. Adicione referências de código. Adicione comentários com o caminho do ADR nos pontos-chave de implementação.
4. Verifique os critérios de verificação. Uma vez que a implementação esteja completa, percorra as caixas de seleção de Verificação. Atualize o ADR com resultados em ## Mais Informações.
5. Revisite quando os gatilhos dispararem. Se o ADR especificou condições de revisita ("se X acontecer, reconsidere"), monitore essas condições.

Índice

Se o repositório tem um arquivo de índice/log de ADR (frequentemente README.md ou index.md no diretório de ADR), mantenha-o atualizado.

Preferido: deixe scripts/new_adr.js --update-index fazer isso. Caso contrário:

• Adicione uma entrada de marcador para o novo ADR.
• Mantenha a ordenação consistente (numérica se numerada; data ou alfabética se slugs).

Inicialização

Ao introduzir ADRs em um repositório que não tem nenhum:

node /path/to/adr-skill/scripts/bootstrap_adr.js

Isso cria o diretório, um arquivo de índice e um primeiro ADR preenchido ("Adotar registros de decisão de arquitetura") com conteúdo real explicando por que a equipe está usando ADRs. Use --json para saída legível por máquina. Use --dir para sobrescrever o nome do diretório.

Categorias (Projetos Grandes)

Para repositórios com muitos ADRs, organize por subdiretório:

docs/decisions/
  backend/
    2025-06-15-use-postgresql.md
  frontend/
    2025-06-20-use-react-query-for-data-fetching.md
  cross-cutting/
    2025-07-01-logging-standard.md

Crie um README.md ou index.md em cada subdiretório listando ADRs contidos, ou mantenha um índice por categoria no índice raiz.

Scripts e Templates

Scripts em scripts/ (se existirem):

• new_adr.js — Cria um novo ADR com geração de nome, preenchimento de template e atualização de índice
• set_adr_status.js — Atualiza o status de um ADR existente (aceitar, rejeitar, depreciar, substituir)
• bootstrap_adr.js — Inicializa um novo diretório de ADR com configuração de índice e primeiro ADR
• link_adr.js — Adiciona ou gerencia referências de ADR em código existente

Templates em assets/templates/:

• adr-simple.md — Template leve para decisões diretas
• adr-madr.md — Template estruturado baseado em MADR com prós/contras múltiplos e drivers
• adr-yaml-frontmatter.md — Template usando front matter YAML para status

Referências

Consulte os seguintes arquivos para detalhes adicionais:

• references/template-variants.md — Qual template usar e quando
• references/review-checklist.md — Checklist detalhada de prontidão para agente