Noções Básicas de Habilidades de Agente

.cursor/skills/
├── explain-review/
│   └── SKILL.md
├── migration-safety/
│   └── SKILL.md
├── failover-drill/
│   └── SKILL.md
└── incident-triage/
    └── SKILL.md

## Pino da pilha
- PostgreSQL 18.4 (servidor e cliente psql)
- pgBackRest 2.55+ (backup auto-hospedado)
- Patroni 4.x / RDS Multi-AZ (por ADR de cluster)
- Flyway 10+ ou Liquibase 4+ (executador de migração)

# Habilidade de Segurança de Migração
 
## O que esta habilidade faz
Pontua o risco de bloqueio de DDL e propõe uma ordem de rollout mais segura.
 
## Quando invocar
- PR adiciona ALTER TABLE, CREATE INDEX ou FK
- Migração de tabela grande sem expandir-contração
 
## Entradas (obrigatório)
- Caminho do arquivo SQL de migração
- Estimativa da contagem de linhas da tabela
- Ambiente de destino (staging/produção)
- Política de janela de manutenção
 
## Saídas
- Pontuação de risco de bloqueio (baixo/médio/alto)
- Alternativa de DDL mais segura, se aplicável
- Verificação: psql -f migração em staging + consulta de monitoramento de bloqueio
 
## Guardrails
- Nunca sugira índice não-CONCURRENT em tabelas quentes de produção
- Nunca execute DDL em agente sem aprovação humana
- Exija SQL de rollback no PR
 
## Pino da pilha
PostgreSQL 18.4 · Flyway 10+
 
## Exemplos de prompts
Veja §10 abaixo.

## Pino da pilha (obrigatório)
- PostgreSQL 18.4 - NÃO sintaxe depreciada sem justificativa
- CREATE INDEX CONCURRENTLY - NÃO CREATE INDEX simples em OLTP de produção
- Colunas IDENTITY preferidas em relação a SERIAL para novas tabelas (idiomas PG 18)

## Política de invocação da equipe
1. Nomeie a habilidade no prompt: "Use a Habilidade de Segurança de Migração em V20260709__add_index.sql"
2. Anexe a saída da consulta de tamanho da tabela, se disponível
3. O agente deve gerar SQL de verificação antes de declarar concluído
4. O humano executa a migração em staging antes da aprovação de produção
5. Nunca mescle automaticamente PRs de migração gerados por habilidades sem revisão de DBA

## Guardrails
- Nenhum DDL de produção do agente sem ID de ticket
- Nenhum pg_terminate_backend sem evidência de PID bloqueador
- Nenhum DROP DATABASE / TRUNCATE sem ponto de verificação de backup nomeado
- EXPLAIN deve usar (ANALYZE, BUFFERS) em staging, não em produção por padrão
- SQL de rollback exigido para cada migração forward

-- Verificação de Staging
BEGIN;
\i db/migrations/V20260709__add_index.sql
SELECT locktype, mode, granted FROM pg_locks WHERE relation = 'orders'::regclass;
ROLLBACK;

flyway -url=jdbc:postgresql://staging:5432/myapp migrate
psql "$STAGING_URL" -c "SELECT indexname FROM pg_indexes WHERE tablename = 'orders';"

docs/skills/README.md          # índice com gatilhos de invocação
.cursor/skills/                # Caminhos nativos do Cursor

# Índice de Habilidades de SME do Postgres
| Habilidade | Gatilho | Proprietário |
|---|---|---|
| explain-review | PR de consulta | rotação app + DBA |
| migration-safety | PR de DDL | DBA da plataforma |
| failover-drill | trimestral | SRE |
| incident-triage | SEV1/2 banco de dados | on-call |

Prompt: "Use a Habilidade de Segurança de Migração em V12__fk.sql, depois a Habilidade de Revisão de EXPLAIN na consulta ORM vinculada"
 
Ordem:
1. Pontuar risco de bloqueio de DDL
2. Se médio+, propor CONCURRENTLY ou expandir-contração
3. Revisar o plano SELECT da aplicação após o índice existir

Use a Habilidade de Revisão de EXPLAIN:
- PR: #842 consulta de lista de pedidos
- Anexar: EXPLAIN (ANALYZE, BUFFERS) de staging
- Tabela: orders ~45M linhas
- Saída: checklist de aprovação/rejeição + sugestão de índice, se necessário

Use a Habilidade de Perfuração de Failover:
- Topologia: Patroni 4.x, 3 nós, etcd
- Destino: apenas cluster de staging
- Saída: failover passo a passo + SQL de verificação + rollback para o primário antigo