161 lines
4.4 KiB
Markdown
161 lines
4.4 KiB
Markdown
---
|
|
name: documentar-decisao-tecnica
|
|
scope: global
|
|
updatedAt: "2026-06-01"
|
|
description: >
|
|
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)
|
|
|
|
```bash
|
|
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`
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```markdown
|
|
# 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.md` (seção de classificação de artefatos)
|
|
- Workflow: `global/workflows/otimizar-codigos.md`
|