---
name: documentar-decisao-tecnica
scope: global
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/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/` |
| 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: `.agent/workflows/aprimorar-IA.global.md` (seção de classificação de artefatos)
- Workflow: `.agent/workflows/documentar-codigo.global.md`