Noções Básicas de Habilidades de Agente

.cursor/skills/
├── api-scaffold/
│   └── SKILL.md
├── queue-worker/
│   └── SKILL.md
├── node-upgrade/
│   └── SKILL.md
└── incident-triage/
    └── SKILL.md

## Pino da pilha
- Node.js 24.18.0 (Active LTS)
- TypeScript 5.6+
- Fastify 5 / NestJS 11 / Express 5 (por ADR do serviço)
- npm 10+

# Habilidade de Scaffold de API
 
## O que esta habilidade faz
Inicializa Fastify 5 + TypeScript + testes + Dockerfile.
 
## Quando invocar
- Novo microsserviço em monorepo
- Substituindo stub legado do Express
 
## Entradas (obrigatório)
- ADR do Framework (Fastify vs Nest)
- Nome do serviço, porta, caminho da rota de health
- Se Postgres/Redis é necessário desde o primeiro dia
 
## Saídas
- Checklist da árvore de arquivos
- Scripts do package.json correspondentes ao CI
- Verificação: npm run typecheck && npm test
 
## Guardrails
- Nunca comitar .env com segredos reais
- Padrão ESM: "type": "module"
- Rota de health antes das rotas de negócios
 
## Pino da pilha
Node.js 24.18.0 · TypeScript 5.6+ · Fastify 5
 
## Exemplos de prompts
Veja §10 abaixo.

## Pino da pilha (obrigatório)
- Node.js 24.18.0 - NÃO exemplos do Node 18 com `require()`
- "type": "module" - NÃO padrões CommonJS `__dirname`
- Fastify 5 `await app.listen()` - NÃO Fastify 3 listen com callback

## Política de invocação da equipe
1. Nomeie a habilidade no prompt: "Use a Habilidade de Scaffold de API para billing-api"
2. Anexe o ADR ou service.yaml se existir
3. O agente deve gerar comandos de verificação antes de declarar concluído
4. O humano executa npm ci && npm test localmente antes do merge
5. Nunca faça merge automático de PRs gerados por habilidades sem revisão

## Guardrails
- Nenhum segredo em arquivos gerados - use placeholders .env.example
- Nenhum `any` em TypeScript gerado sem TODO explícito
- Workers não devem compartilhar o mesmo processo do servidor HTTP
- Handlers de desligamento gracioso em APIs e workers
- npm audit --audit-level=high deve passar antes de "concluído"

cd services/orders-api
npm ci
npm run typecheck
npm test
npm run build
docker build -t orders-api:local .
curl -sf http://localhost:3000/health

docs/skills/README.md          # índice com gatilhos de invocação
.cursor/skills/                # caminhos nativos do Cursor
.github/skills/                # opcional: compartilhado via submodule

# Índice de Habilidades Node SME
| Habilidade | Gatilho | Proprietário |
|---|---|---|
| api-scaffold | novo serviço | equipe de plataforma |
| queue-worker | trabalho assíncrono | equipe de plataforma |
| node-upgrade | bump LTS | infra |
| incident-triage | SEV1/2 API | on-call |

Prompt: "Use a Habilidade de Scaffold de API para notifications-api, depois a Habilidade de Worker de Fila para a fila de e-mail"
 
Ordem:
1. Scaffold HTTP + health + logger
2. Adicionar URL do Redis ao .env.example
3. Adicionar entrada do worker em package.json "worker:email"
4. Verificar API e worker separadamente

Use a Habilidade de Scaffold de API:
- Serviço: inventory-api
- Framework: Fastify 5 por ADR-012
- Necessidades: Postgres, sem Redis no primeiro dia
- Saída: árvore completa + Dockerfile + stub de job do GitHub Actions

Use a Habilidade de Upgrade do Node:
- Atual: Node 20.18.0 em Docker e .nvmrc
- Alvo: Node 24.18.0 Active LTS
- Monorepo: 6 serviços, workspaces npm
- Saída: matriz de breaking-changes + PRs de migração ordenados

Use a Habilidade de Triagem de Incidentes:
- Sintoma: 502 do ingress, p95 latência 12s, conexões Postgres no máximo
- Serviço: orders-api v2.4.1 implantado há 40m
- Saída: checklist T+0 a T+60 com decisão de rollback