versão 1

global/skills/documentar-decisao-tecnica/SKILL.md

@@ -0,0 +1,161 @@
+---
+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/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/otimizar-codigos.global.md`