4.9 KiB
4.9 KiB
| name | scope | updatedAt | description |
|---|---|---|---|
| documentar-decisao-tecnica | global | 2026-09-01 | Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/adrs/). |
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, uso de BullMQ, schemas Zod)
- Escolha de ferramenta ou biblioteca entre alternativas
- Decisão de breaking change de contrato
- Migração de tecnologia ou banco de dados
- Mudança de estratégia de deploy ou CI/CD
- Qualquer decisão técnica relevante para o time ou para a IA
PASSO 1 — Obter Identidade do Módulo e Localizar o Diretório de ADRs
- Ler
modulo-idemodulo-wikiem<base_projeto>/memorias-ia/modulo.yml(fallback de wiki:../wiki/). - Convenção de diretório:
<modulo-wiki>/dev/<modulo-id>/adrs/(na Wiki de Desenvolvimento).
mkdir -p <modulo-wiki>/dev/<modulo-id>/adrs
PASSO 2 — Criar o Arquivo ADR
Nomenclatura: NNN-titulo-em-kebab-case.md
# Encontrar o próximo número
NEXT=$(ls <modulo-wiki>/dev/<modulo-id>/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/rules/ |
| Define um processo repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um Workflow em .agent/workflows/ |
| Refina um padrão operacional (ex: "queries agora usam pool separado") | Atualizar a Skill correspondente em .agent/skills/ |
| Registra histórico de ação da IA | Gravar na memória em <base_projeto>/memorias-ia/ |
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)?
- O ADR foi salvo em
<modulo-wiki>/dev/<modulo-id>/adrs/? - A decisão foi registrada na memória em
<base_projeto>/memorias-ia/? - Alguém de fora do contexto entenderia este ADR?
Referências
- Rule:
rules/ddd-documentacao-primeiro.md - Workflow:
global/workflows/aprimora-ia.md - Wiki de Desenvolvimento:
<modulo-wiki>/dev/<modulo-id>/adrs/