| name | create-adr |
| description | Gerencia o ciclo de vida dos ADRs (Architecture Decision Records) no repositório. Executa arqueologia de software, análise de gaps, proposta de decisões e escrita de ADRs em docs/architecture-decision-records. Use quando o usuário pedir para criar ADRs, documentar decisões de arquitetura, analisar decisões implícitas do projeto ou gerenciar a pasta de architecture-decision-records. |
ADR — Architecture Decision Records
Configuração
Pasta de ADRs (fixa): docs/architecture-decision-records na raiz do repositório. Todas as ADRs devem ser criadas neste caminho.
| Parâmetro | Padrão | Descrição |
|---|
| Pasta de ADRs | docs/architecture-decision-records | Pasta na raiz do repo onde ficam os ADRs. Sempre usar este caminho para ler e criar ADRs. |
| Template | Template da skill | Se na pasta de ADRs existir TEMPLATE.md, use-o; caso contrário use o da skill: TEMPLATE.md. |
| Escopo da análise | Projeto inteiro | Analisar só a pasta de ADRs ou o repositório todo (recomendado para proposta de novos ADRs). |
| Idioma | Português (PT-BR) | Idioma de saída dos ADRs. |
Verificação e criação da pasta
Antes de ler ou escrever ADRs:
- Verificar se existe a pasta
docs/architecture-decision-records na raiz do repositório.
- Se não existir, criar a pasta (e
docs/, se necessário).
- Só então prosseguir com leitura dos ADRs existentes ou criação de novos arquivos.
Assim garante-se que as ADRs são sempre criadas em docs/architecture-decision-records.
Fluxo de trabalho (4 passos)
Siga os passos na ordem. Detalhes completos e prompts estão em reference.md.
Passo 1: Arqueologia e análise de gaps
- Pasta de ADRs: Verificar se
docs/architecture-decision-records existe na raiz do repo; se não, criar a pasta. Usar sempre este caminho.
- Leitura inicial: Ler todos os
.md em docs/architecture-decision-records para saber o que já está decidido.
- Análise macro (C4 – Containers): Antes de ler código, analisar a estrutura de diretórios (raiz e um nível abaixo).
- Topologia: monorepo, monólito modular, microserviços, front/back separados?
- Containers: pastas que são aplicações/serviços (
client/, server/, apps/).
- Contextos: domínio (ex.:
modules/sales) ou camadas (ex.: layers/).
- Migração: pastas como
v1/, v2/, legacy/, modern/.
- Stack e padrões: Configurações (
package.json, *.csproj, go.mod, docker-compose.yml) e código para identificar stack, padrões (Clean Arch, Hexagonal, MVC) e libs principais.
- Testes: Projetos de teste (unitários e integração) — padrões, stack, mocks, assertivas, nomenclatura e organização dos arquivos.
- Gaps: Comparar estrutura + stack com o que está documentado nos ADRs; listar decisões implícitas.
Passo 2: Proposta de decisões (pausa obrigatória)
- Listar ADRs sugeridos, numerados e agrupados por categoria.
- Grupo A — Estrutura e organização (containers): ex.: estratégia de monorepo, separação front/back. Evidência: pastas X e Y.
- Grupo B — Engenharia e padrões: ex.: uso da lib X, padrão Y. Evidência: código/config.
- Usar o próximo número sequencial disponível na pasta de ADRs.
- Parar e aguardar confirmação do usuário antes de escrever arquivos.
Passo 3: Criação e escrita (após aprovação)
Para cada ADR aprovado:
- Ler o template do projeto (se existir
TEMPLATE.md na pasta de ADRs) ou o da skill: TEMPLATE.md.
- Escrever o conteúdo seguindo a estrutura do template (Contexto, Decisão, seções opcionais quando fizerem sentido).
- Em Contexto, indicar onde no repositório a decisão aparece (caminhos de pasta).
- Em Implementação Técnica, usar a subseção Estrutura de Arquivos com árvore (
tree ou equivalente) para ilustrar.
- Garantir a pasta: Se
docs/architecture-decision-records não existir na raiz, criá-la. Criar o arquivo em docs/architecture-decision-records/ADR-XXX-slug.md (slug em minúsculas, hífens) com a data atual.
Passo 4: Verificação final
- Conferir se ADRs de estrutura (Grupo A) sustentam as de engenharia (Grupo B).
- Ex.: a estrutura de pastas está alinhada à arquitetura hexagonal documentada?
Nomenclatura e arquivos
- Nome do arquivo:
ADR-XXX-slug-do-titulo.md (XXX = número com zeros à esquerda, ex.: 001, 012).
- Slug: minúsculas, palavras separadas por hífen, sem acentos.
Comando inicial sugerido
Se o usuário não especificar como começar, inicie pelo Passo 1 (com foco em 1.2 – análise macro) e, ao final, apresente as propostas do Passo 2 e pause para aprovação.
Para fluxo completo, consulte reference.md. O template de base está em TEMPLATE.md.
