---
name: documentar-decisao-tecnica
scope: global
updatedAt: "2026-09-01"
description: >
  Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<base_projeto>/../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

1. Ler `modulo-id` em `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
2. Convenção de diretório: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/` (na Wiki de Desenvolvimento).

```bash
mkdir -p <base_projeto>/../wiki/dev/<modulo-id>/adrs
```

---

## 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/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 `<base_projeto>/../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: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`