4.4 KiB
| name | scope | updatedAt | description |
|---|---|---|---|
| documentar-decisao-tecnica | global | 2026-06-01 | Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records). |
Skill: Documentar Decisão Técnica (ADR)
Use esta skill sempre que uma decisão técnica significativa for tomada — escolha de biblioteca, mudança de arquitetura, padrão de código, migração, ou qualquer decisão que afete múltiplos pacotes ou desenvolvedores.
O objetivo é garantir que nenhuma decisão fique apenas na cabeça ou perdida em conversas.
Quando usar
- Nova dependência adicionada ao monorepo
- Mudança de padrão arquitetural (ex: de REST para GraphQL)
- Escolha de ferramenta ou lib entre alternativas
- Decisão de breaking change
- Migração de tecnologia
- Mudança de estratégia de deploy ou CI/CD
- Qualquer decisão que alguém pode questionar daqui 3 meses
PASSO 1 — Criar o Diretório de ADRs (se não existir)
mkdir -p .docs/adrs
Convenção de diretório: .docs/adrs/ na raiz do monorepo.
PASSO 2 — Criar o Arquivo ADR
Nomenclatura: NNN-titulo-em-kebab-case.md
# Encontrar o próximo número
NEXT=$(ls .docs/adrs/*.md 2>/dev/null | wc -l | xargs -I{} expr {} + 1)
NEXT=$(printf "%03d" $NEXT)
echo "Próximo ADR: $NEXT"
PASSO 3 — Preencher o Template
# ADR-NNN: Título Descritivo da Decisão
**Data:** YYYY-MM-DD
**Status:** proposto | aceito | substituído por ADR-XXX | descontinuado
**Autores:** Nome(s)
## Contexto
Descreva a situação que levou à necessidade de uma decisão.
Inclua:
- O problema enfrentado
- Restrições técnicas ou de negócio
- O que motivou a discussão
## Decisão
Descreva a decisão tomada de forma clara e direta.
Use voz ativa: "Decidimos usar X para Y porque Z."
## Alternativas Consideradas
### Alternativa A: [Nome]
- **Prós:** ...
- **Contras:** ...
- **Motivo da rejeição:** ...
### Alternativa B: [Nome]
- **Prós:** ...
- **Contras:** ...
- **Motivo da rejeição:** ...
## Consequências
### Positivas
- O que melhora com essa decisão
### Negativas
- O que fica mais complexo ou limitado
- Débitos técnicos introduzidos
### Neutras
- Mudanças que não são boas nem ruins, mas afetam o workflow
## Impacto no Monorepo
Listar quais pacotes/módulos são afetados:
- `@org/pacote-a` — precisa migrar de X para Y
- `@org/pacote-b` — sem impacto
PASSO 4 — Conectar com o Sistema de Conhecimento
Após criar o ADR, avaliar se a decisão deve gerar:
| A decisão... | Ação |
|---|---|
| Cria uma restrição permanente (ex: "nunca usar lib X") | Criar/atualizar uma Rule em .agent/local/rules/ |
| Define um processo repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um Workflow em .agent/local/workflows/ |
| Refina um padrão operacional (ex: "queries agora usam pool separado") | Atualizar a Skill correspondente em .agent/local/skills/ |
| Não gera artefato adicional | Apenas o ADR é suficiente |
PASSO 5 — Validar o ADR
Antes de considerar completo:
- Teste do "daqui a 6 meses": alguém que não participou da conversa consegue entender a decisão?
- Teste da reversibilidade: está claro o que seria necessário para reverter essa decisão?
- Teste do impacto: todos os pacotes afetados estão listados?
Exemplos de ADRs Reais
Bom ✅
ADR-003: Usar Zod para validação de schemas em vez de Joi
Contexto: O projeto usava Joi para validação no backend, mas ao compartilhar schemas entre back e front em um monorepo, Joi se mostrou pesado para o bundle do frontend (280KB gzipped).
Decisão: Migrar para Zod em todos os pacotes. Zod oferece inferência nativa de tipos TypeScript, é 10x menor, e elimina a necessidade de manter tipos e schemas separados.
Ruim ❌
ADR-003: Usar Zod
Decidimos usar Zod porque é melhor.
Checklist Final
- O contexto explica o "porquê" da decisão?
- As alternativas consideradas estão documentadas?
- As consequências (positivas e negativas) estão claras?
- Os pacotes impactados estão listados?
- O status está definido (proposto/aceito)?
- A decisão gerou rules/workflows/skills quando aplicável?
- Alguém de fora do contexto entenderia este ADR?
Referências
- Workflow:
global/workflows/aprimorar-IA(seção de classificação de artefatos) - Workflow:
global/workflows/otimizar-codigos