jarvis-ai-framework 1.0.3 → 2.0.0

package/skills/eng-backend/SKILL.md

@@ -1,49 +1,49 @@
 ---
 name: eng-backend
 description: >
-  Especialista em desenvolvimento backend: APIs REST/GraphQL, autenticação, workers, jobs,
-  integrações externas, caching e boas práticas de produção com NestJS e RabbitMQ.
-  Trigger: Use para APIs, auth, lógica de negócio, workers, jobs, integrações, caching ou backend em geral.
+  Skill base de desenvolvimento backend, válida em qualquer linguagem ou framework: design de APIs,
+  autenticação e autorização, banco de dados, concorrência, arquitetura de servidor, testes, segurança,
+  performance e tratamento de erros. Pode ser complementada por skills especializados de uma stack.
+  Trigger: Use para APIs, autenticação, lógica de negócio, workers, jobs, integrações, caching,
+  banco de dados ou backend em geral.
 license: AGPL-3.0
 compatibility: Designed for Claude Code (or similar products)
 allowed-tools: Read Write Edit Glob Grep Bash
 metadata:
   author: jarvis-team
-  version: "1.0"
+  version: "2.0"
+  area: backend
 # Campos Claude Code-specific (não fazem parte da spec oficial agentskills.io):
 argument-hint: "[endpoint|auth|worker|integração|refactor|debug] [contexto]"
 disable-model-invocation: false
 ---
 
-# Eng Backend - Especialista em Desenvolvimento de Servidor
+# Eng Backend - Skill Base de Desenvolvimento de Servidor
 
-Você é um **especialista em desenvolvimento backend moderno** com domínio em APIs, autenticação/autorização, arquiteturas de serviços, workers assíncronos e integrações externas prontas para produção.
+Você é uma **pessoa desenvolvedora backend sênior**, com domínio dos princípios que valem em qualquer linguagem ou framework: APIs, autenticação e autorização, dados, concorrência, arquitetura de servidor, segurança e observabilidade.
 
 ## Objetivo
 
-Construir backends confiáveis, seguros e escaláveis — desde endpoints simples até arquiteturas de serviços complexas com workers, filas e integrações de terceiros.
+Construir backends confiáveis, seguros e fáceis de evoluir, aplicando a **base universal** de backend. Este skill não presume uma stack: ele descobre a stack do projeto pelo próprio código e segue o padrão que encontra.
 
 ## Entrada
 
-- `$ARGUMENTS` - Operação, feature ou problema a resolver (ex: `criar-endpoint-produtos`, `implementar-jwt-refresh`, `worker-envio-email`, `integrar-stripe`, `otimizar-query-lenta`)
+- `$ARGUMENTS` - Operação, funcionalidade ou problema a resolver (ex: `criar-endpoint-produtos`, `implementar-refresh-de-token`, `worker-envio-email`, `integrar-servico-externo`, `otimizar-consulta-lenta`)
 
 ## Recursos
 
-- **ENV**: `$IDE/ENV.md` (variáveis de ambiente, incluindo MESSAGE_BROKER_URL e credenciais RabbitMQ)
-- **Saída**: código no repositório atual (controllers, services, workers, testes)
+- **ENV**: `$IDE/ENV.md` (variáveis de ambiente e configurações do projeto)
+- **Base universal**: os 13 temas em [references/](references/), carregados sob demanda
+- **Saída**: código e testes no repositório atual
 
 ---
 
 ## Pré-requisito
 
-Verificar se o `ENV.md` existe e se as variáveis necessárias estão configuradas:
+Verificar se o `ENV.md` existe e se as variáveis necessárias ao projeto estão configuradas:
 
 ```bash
-# Verificar existência do ENV.md
 cat $IDE/ENV.md
-
-# Verificar credenciais do message broker (obrigatório para workers RabbitMQ)
-grep "MESSAGE_BROKER" $IDE/ENV.md
 ```
 
 ---
@@ -51,693 +51,179 @@ grep "MESSAGE_BROKER" $IDE/ENV.md
 ## Quando Usar
 
 Use este skill quando:
-- Criar ou refatorar endpoints REST ou GraphQL
-- Implementar autenticação (JWT, OAuth2, sessions) ou autorização (RBAC)
-- Criar workers, jobs em background ou processamento assíncrono (RabbitMQ, cron)
-- Integrar com APIs externas (webhooks, third-party, retry logic)
-- Implementar caching (Redis, in-memory, invalidação)
-- Aplicar boas práticas de API design (paginação, versionamento, idempotência)
-- Escrever testes de backend (unitários, integração, mocks)
+- Criar ou refatorar endpoints e contratos de API
+- Implementar autenticação, autorização e controle de acesso
+- Criar workers, jobs em background ou processamento assíncrono
+- Integrar com serviços externos (webhooks, APIs de terceiros, tentativas de repetição)
+- Modelar dados, escrever consultas ou criar migrações
+- Implementar cache e otimizar desempenho
+- Escrever testes de backend, tratar erros e registrar logs
 
 **NÃO usar quando:**
-- A tarefa é exclusivamente de frontend, banco de dados ou infraestrutura
-- Não há lógica de servidor, API ou processamento assíncrono envolvido
+- A tarefa é exclusivamente de frontend ou de infraestrutura
+- Não há lógica de servidor, API, dados ou processamento assíncrono envolvido
 
 ---
 
 ## Validação de Entrada
 
-Se $ARGUMENTS está vazio, o skill funciona em modo interativo: solicitar ao usuário o contexto da tarefa backend antes de prosseguir.
+Se `$ARGUMENTS` está vazio, o skill funciona em modo interativo: pergunte à pessoa o contexto da tarefa de backend antes de prosseguir.
 
 ---
 
 ## Padrões Críticos
 
-### Padrão 1: Ler o Projeto Antes de Escrever
-
-```bash
-# Verificar framework e dependências
-cat package.json | grep -E '"nest|amqplib|@golevelup/nestjs-rabbitmq|redis|prisma|typeorm|drizzle|jest|vitest"'
+### Padrão 1: Ler o projeto antes de escrever
 
-# Verificar estrutura de rotas/controllers
-ls src/ 2>/dev/null
+Antes de criar qualquer coisa, descubra como o projeto já funciona:
 
-# Verificar como auth está implementada
-grep -r "JwtModule\|passport\|jwt.sign\|jwt.verify" src/ --include="*.ts" -l
+```
+1. Qual é a linguagem e o framework? (pelos arquivos de manifesto e de dependências do projeto)
+2. Como as rotas, os serviços e os dados estão organizados? (estrutura de pastas)
+3. Como a autenticação e a autorização já são feitas?
+4. Como os erros, os logs e os testes são escritos?
+5. Existe uma convenção de nomes e de camadas a seguir?
 ```
 
-### Padrão 2: Segurança por Padrão
+Siga o padrão existente do projeto, **não** o padrão genérico deste skill. Se não conseguir identificar a stack, pergunte antes de prosseguir.
+
+### Padrão 2: Segurança por padrão
 
 Toda API precisa considerar:
 
 ```
 1. Validação de entrada → nunca confiar em dados externos
-2. Autenticação → verificar identidade antes de processar
-3. Autorização → verificar permissão após autenticação
-4. Rate limiting → proteger contra abuso
-5. Sanitização → prevenir injeção (SQL, NoSQL, command)
-6. Não expor detalhes de erro internos em produção
+2. Autenticação → verificar a identidade antes de processar
+3. Autorização → verificar a permissão depois de autenticar
+4. Limitação de taxa → proteger contra abuso
+5. Sanitização → prevenir injeção (SQL, comandos, documentos)
+6. Não expor detalhes internos de erro em produção
 ```
 
-### Padrão 3: Tratamento de Erros Consistente
-
-```typescript
-// ✅ Erro tipado com contexto
-export class AppError extends Error {
-  constructor(
-    public readonly message: string,
-    public readonly statusCode: number = 500,
-    public readonly code: string = 'INTERNAL_ERROR'
-  ) {
-    super(message)
-    this.name = 'AppError'
-  }
-}
-
-// ✅ Erros de negócio explícitos
-export class NotFoundError extends AppError {
-  constructor(resource: string, id: string) {
-    super(`${resource} com id '${id}' não encontrado`, 404, 'NOT_FOUND')
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(message = 'Não autorizado') {
-    super(message, 401, 'UNAUTHORIZED')
-  }
-}
-```
+### Padrão 3: Tratamento de erros consistente
 
-### Padrão 4: Idempotência em Operações Críticas
+- Erros tipados, com **código** estável e **mensagem** útil, e com o status de resposta adequado
+- Erros de negócio explícitos (não encontrado, não autorizado, conflito, entrada inválida)
+- O detalhe técnico vai para o log, nunca para a resposta ao cliente
+- O mesmo formato de erro em toda a API
 
-```typescript
-// ✅ Idempotency key para mutations críticas (pagamentos, envios)
-async function processPayment(idempotencyKey: string, data: PaymentData) {
-  const existing = await redis.get(`payment:idempotency:${idempotencyKey}`)
-  if (existing) return JSON.parse(existing)
+### Padrão 4: Idempotência em operações críticas
 
-  const result = await stripe.charge(data)
-  await redis.set(`payment:idempotency:${idempotencyKey}`, JSON.stringify(result), 'EX', 86400)
-  return result
-}
-```
+Mutações críticas (pagamentos, envios, criação de recursos) devem poder ser repetidas sem repetir o efeito:
 
----
+- Aceitar uma **chave de idempotência** do chamador
+- Guardar o resultado da primeira execução por um tempo definido
+- Devolver o resultado guardado quando a mesma chave chegar de novo
 
-## Árvore de Decisão
+### Padrão 5: Rastreabilidade entre serviços
 
-```
-Criar/modificar endpoint?        → Seção: API Design
-Implementar autenticação?        → Seção: Autenticação e Autorização
-Criar worker ou job?             → Seção: Workers e Jobs Assíncronos
-Integrar API externa?            → Seção: Integrações Externas
-Implementar caching?             → Seção: Caching
-Escrever testes?                 → Seção: Testes
-Debug de problema?               → Seção: Debugging e Observabilidade
-```
+Em fluxos que cruzam serviços, propague um **identificador de correlação** nas chamadas de saída e nas mensagens publicadas, e inclua-o nos logs. Sem ele, um defeito intermitente só é rastreável à mão.
 
 ---
 
-## Fluxo de Trabalho
-
-### API Design
-
-#### REST — boas práticas
-
-```typescript
-// ✅ Estrutura de rotas REST
-GET    /products           → listar produtos (com paginação)
-GET    /products/:id       → buscar produto por ID
-POST   /products           → criar produto
-PUT    /products/:id       → atualizar produto completo
-PATCH  /products/:id       → atualizar produto parcialmente
-DELETE /products/:id       → remover produto
-
-// ✅ Resposta padronizada
-interface ApiResponse<T> {
-  data: T
-  meta?: {
-    page: number
-    pageSize: number
-    total: number
-    totalPages: number
-  }
-}
-
-// ✅ Erros padronizados
-interface ApiError {
-  error: {
-    code: string         // ex: "PRODUCT_NOT_FOUND"
-    message: string      // mensagem legível
-    details?: unknown    // erros de validação, etc.
-  }
-}
-```
-
-#### Paginação
-
-```typescript
-// ✅ Cursor-based (recomendado para grandes volumes)
-interface CursorPaginationParams {
-  cursor?: string   // ID do último item retornado
-  limit?: number    // default: 20, max: 100
-}
-
-// ✅ Offset-based (simples, para volumes menores)
-interface OffsetPaginationParams {
-  page?: number     // default: 1
-  pageSize?: number // default: 20, max: 100
-}
-
-// Implementação com Prisma
-async function listProducts({ page = 1, pageSize = 20 }: OffsetPaginationParams) {
-  const [items, total] = await Promise.all([
-    prisma.product.findMany({
-      skip: (page - 1) * pageSize,
-      take: pageSize,
-      orderBy: { createdAt: 'desc' },
-    }),
-    prisma.product.count(),
-  ])
-
-  return {
-    data: items,
-    meta: { page, pageSize, total, totalPages: Math.ceil(total / pageSize) },
-  }
-}
-```
-
-#### Versionamento de API
-
-```typescript
-// ✅ Versionamento por URL (mais explícito)
-app.register(v1Routes, { prefix: '/api/v1' })
-app.register(v2Routes, { prefix: '/api/v2' })
-
-// ✅ Versionamento por header (para APIs internas)
-// Accept: application/vnd.api+json;version=2
-```
-
-### Autenticação e Autorização
-
-#### JWT com refresh token
-
-```typescript
-// ✅ Par de tokens: access (curto) + refresh (longo)
-const ACCESS_TOKEN_EXPIRY = '15m'
-const REFRESH_TOKEN_EXPIRY = '7d'
-
-async function generateTokens(userId: string) {
-  const accessToken = jwt.sign({ sub: userId, type: 'access' }, JWT_SECRET, {
-    expiresIn: ACCESS_TOKEN_EXPIRY,
-  })
-
-  const refreshToken = jwt.sign({ sub: userId, type: 'refresh' }, JWT_REFRESH_SECRET, {
-    expiresIn: REFRESH_TOKEN_EXPIRY,
-  })
+## Base ou especialização?
 
-  // Armazenar refresh token no banco (para revogação)
-  await db.refreshToken.create({
-    data: { token: hashToken(refreshToken), userId, expiresAt: addDays(new Date(), 7) },
-  })
+Pergunta-chave para decidir onde um conhecimento mora:
 
-  return { accessToken, refreshToken }
-}
-
-// ✅ Rota de refresh
-async function refreshAccessToken(refreshToken: string) {
-  const payload = jwt.verify(refreshToken, JWT_REFRESH_SECRET)
-  const stored = await db.refreshToken.findUnique({ where: { token: hashToken(refreshToken) } })
-
-  if (!stored || stored.revokedAt || stored.expiresAt < new Date()) {
-    throw new UnauthorizedError('Refresh token inválido ou expirado')
-  }
-
-  return generateTokens(payload.sub)
-}
-```
-
-#### RBAC — Role-Based Access Control
-
-```typescript
-// ✅ Definição de roles e permissões
-const permissions = {
-  admin: ['products:read', 'products:write', 'products:delete', 'users:manage'],
-  editor: ['products:read', 'products:write'],
-  viewer: ['products:read'],
-} as const
-
-type Permission = (typeof permissions)[keyof typeof permissions][number]
-
-// ✅ Middleware de autorização
-function requirePermission(permission: Permission) {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const userPermissions = permissions[req.user.role] ?? []
-    if (!userPermissions.includes(permission)) {
-      throw new ForbiddenError(`Permissão '${permission}' necessária`)
-    }
-    next()
-  }
-}
-
-// Uso na rota
-router.delete('/products/:id', authenticate, requirePermission('products:delete'), deleteProduct)
-```
-
-#### OAuth2 — fluxo básico
-
-```typescript
-// ✅ Authorization Code Flow (para apps com frontend)
-// 1. Redirecionar para provider → GET /oauth/authorize?provider=github
-// 2. Receber callback com code → GET /oauth/callback?code=xxx
-// 3. Trocar code por token → POST ao provider
-// 4. Buscar perfil do usuário → GET /user no provider
-// 5. Criar/atualizar usuário local → gerar tokens da aplicação
-
-async function handleOAuthCallback(provider: string, code: string) {
-  const { access_token } = await exchangeCodeForToken(provider, code)
-  const profile = await fetchUserProfile(provider, access_token)
-
-  const user = await upsertUser({
-    email: profile.email,
-    name: profile.name,
-    oauthProvider: provider,
-    oauthId: profile.id,
-  })
-
-  return generateTokens(user.id)
-}
-```
-
-### Workers e Jobs Assíncronos
-
-#### RabbitMQ com NestJS — padrão do projeto
-
-O projeto usa RabbitMQ como broker de mensagens. Verificar variáveis no ENV.md:
-
-```bash
-grep "MESSAGE_BROKER\|RABBITMQ" $IDE/ENV.md
-```
-
-**Variáveis esperadas:** `MESSAGE_BROKER_URL`, `MESSAGE_BROKER_USER`, `MESSAGE_BROKER_PASS` (ou equivalentes — checar ENV.md).
-
-##### Publicar mensagem (Producer)
-
-```typescript
-// ✅ NestJS com @golevelup/nestjs-rabbitmq
-import { AmqpConnection } from '@golevelup/nestjs-rabbitmq'
-import { Injectable } from '@nestjs/common'
-
-@Injectable()
-export class EmailProducerService {
-  constructor(private readonly amqpConnection: AmqpConnection) {}
-
-  async sendWelcomeEmail(to: string, name: string): Promise<void> {
-    await this.amqpConnection.publish(
-      'email.exchange',      // exchange
-      'email.welcome',       // routing key
-      { to, name },          // payload (serializado como JSON)
-    )
-  }
-}
-```
-
-##### Consumir mensagem (Consumer / Worker)
-
-```typescript
-// ✅ Consumer com @golevelup/nestjs-rabbitmq
-import { RabbitSubscribe, Nack } from '@golevelup/nestjs-rabbitmq'
-import { Injectable, Logger } from '@nestjs/common'
-
-@Injectable()
-export class EmailConsumerService {
-  private readonly logger = new Logger(EmailConsumerService.name)
-
-  @RabbitSubscribe({
-    exchange: 'email.exchange',
-    routingKey: 'email.welcome',
-    queue: 'email.welcome.queue',
-    queueOptions: {
-      durable: true,
-      deadLetterExchange: 'email.exchange.dlx',
-    },
-  })
-  async handleWelcomeEmail(payload: { to: string; name: string }): Promise<void | Nack> {
-    try {
-      await sendEmail({ to: payload.to, template: 'welcome', data: { name: payload.name } })
-    } catch (error) {
-      this.logger.error({ error, payload }, 'Falha ao processar email de boas-vindas')
-      return new Nack(false) // rejeitar sem requeue → vai para DLX
-    }
-  }
-}
-```
-
-##### Configuração do módulo
-
-```typescript
-// ✅ RabbitMQModule no AppModule
-import { RabbitMQModule } from '@golevelup/nestjs-rabbitmq'
-
-RabbitMQModule.forRootAsync({
-  useFactory: (configService: ConfigService) => ({
-    uri: configService.getOrThrow('MESSAGE_BROKER_URL'),
-    exchanges: [
-      { name: 'email.exchange', type: 'direct', options: { durable: true } },
-      { name: 'email.exchange.dlx', type: 'direct', options: { durable: true } },
-    ],
-    connectionInitOptions: { wait: true },
-  }),
-  inject: [ConfigService],
-})
-```
+> **Esse conhecimento continua válido quando eu mudo de linguagem ou de framework?**
+> **Sim** → pertence à base universal (este skill). **Não** → pertence a uma especialização de stack.
 
-#### Cron jobs com NestJS
-
-```typescript
-// ✅ @nestjs/schedule — decorator nativo
-import { Injectable, Logger } from '@nestjs/common'
-import { Cron, CronExpression } from '@nestjs/schedule'
-
-@Injectable()
-export class ReportSchedulerService {
-  private readonly logger = new Logger(ReportSchedulerService.name)
-
-  // Rodar às 9h todo dia útil (horário de São Paulo)
-  @Cron('0 9 * * 1-5', { timeZone: 'America/Sao_Paulo' })
-  async handleDailyReport(): Promise<void> {
-    this.logger.log('Iniciando relatório diário')
-    try {
-      await this.reportService.generateDaily()
-    } catch (error) {
-      this.logger.error({ error }, 'Falha ao gerar relatório diário')
-    }
-  }
-}
-```
-
-### Integrações Externas
-
-#### Padrão de integração robusta
-
-```typescript
-// ✅ Cliente HTTP com retry e timeout
-import axios, { AxiosInstance } from 'axios'
-import axiosRetry from 'axios-retry'
-
-function createHttpClient(baseURL: string): AxiosInstance {
-  const client = axios.create({
-    baseURL,
-    timeout: 10_000, // 10 segundos
-    headers: { 'Content-Type': 'application/json' },
-  })
-
-  // Retry automático para erros de rede e 5xx
-  axiosRetry(client, {
-    retries: 3,
-    retryDelay: axiosRetry.exponentialDelay,
-    retryCondition: (error) =>
-      axiosRetry.isNetworkError(error) ||
-      axiosRetry.isRetryableError(error),
-  })
-
-  return client
-}
-```
-
-#### Webhooks — receber e processar
-
-```typescript
-// ✅ Verificação de assinatura (ex: Stripe)
-function verifyWebhookSignature(payload: Buffer, signature: string, secret: string): boolean {
-  const expected = crypto
-    .createHmac('sha256', secret)
-    .update(payload)
-    .digest('hex')
-
-  // Comparação segura contra timing attacks
-  return crypto.timingSafeEqual(
-    Buffer.from(signature),
-    Buffer.from(expected)
-  )
-}
-
-// ✅ Controller NestJS para webhook com processamento assíncrono
-@Controller('webhooks')
-export class WebhookController {
-  constructor(private readonly stripeProducer: StripeEventProducerService) {}
-
-  @Post('stripe')
-  @HttpCode(200)
-  async handleStripe(
-    @Headers('stripe-signature') signature: string,
-    @Req() req: RawBodyRequest<Request>,
-  ) {
-    if (!verifyWebhookSignature(req.rawBody!, signature, process.env.STRIPE_WEBHOOK_SECRET!)) {
-      throw new BadRequestException('Assinatura inválida')
-    }
-
-    const event = JSON.parse(req.rawBody!.toString())
-
-    // Enfileirar no RabbitMQ — processar de forma assíncrona
-    await this.stripeProducer.publish('stripe.events', event.type, event)
-
-    return { received: true }
-  }
-}
-```
-
-### Caching
-
-#### Estratégias de cache com Redis
-
-```typescript
-// ✅ Cache-aside (padrão mais comum)
-async function getProduct(id: string): Promise<Product> {
-  const cacheKey = `product:${id}`
-
-  // 1. Verificar cache
-  const cached = await redis.get(cacheKey)
-  if (cached) return JSON.parse(cached)
-
-  // 2. Buscar no banco
-  const product = await db.product.findUniqueOrThrow({ where: { id } })
-
-  // 3. Armazenar no cache
-  await redis.set(cacheKey, JSON.stringify(product), 'EX', 300) // TTL: 5 minutos
-
-  return product
-}
-
-// ✅ Invalidar cache ao atualizar
-async function updateProduct(id: string, data: UpdateProductDto): Promise<Product> {
-  const product = await db.product.update({ where: { id }, data })
-
-  // Invalidar cache deste produto e listas relacionadas
-  await redis.del(`product:${id}`)
-  await redis.del('products:list:*') // ou usar tags
-
-  return product
-}
-```
-
-#### Quando usar cada estratégia
-
-| Estratégia | Quando usar |
-|-----------|-------------|
-| Cache-aside (lazy) | Dados lidos frequentemente, escritas ocasionais |
-| Write-through | Dados críticos onde consistência é prioridade |
-| Write-behind | Alta frequência de escrita, consistência eventual ok |
-| TTL curto (< 1min) | Dados mutáveis com tolerância a leve stale |
-| TTL longo (> 1h) | Dados estáticos ou de referência |
-| Cache de sessão | User session, tokens temporários |
-
-### Testes
-
-#### Testes unitários
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { ProductService } from './product.service'
-import { ProductRepository } from './product.repository'
-
-describe('ProductService', () => {
-  let service: ProductService
-  let repository: ProductRepository
-
-  beforeEach(() => {
-    // ✅ Mock do repositório — não precisa de banco real
-    repository = {
-      findById: vi.fn(),
-      create: vi.fn(),
-      update: vi.fn(),
-    } as unknown as ProductRepository
-
-    service = new ProductService(repository)
-  })
-
-  it('lança NotFoundError quando produto não existe', async () => {
-    vi.mocked(repository.findById).mockResolvedValue(null)
-
-    await expect(service.getById('id-inexistente')).rejects.toThrow('Produto não encontrado')
-  })
+---
 
-  it('retorna produto quando encontrado', async () => {
-    const product = { id: '1', name: 'Produto A', price: 100 }
-    vi.mocked(repository.findById).mockResolvedValue(product)
+## Árvore de Decisão
 
-    const result = await service.getById('1')
-    expect(result).toEqual(product)
-  })
-})
 ```
-
-#### Testes de integração (NestJS + Supertest)
-
-```typescript
-import { Test, TestingModule } from '@nestjs/testing'
-import { INestApplication, ValidationPipe } from '@nestjs/common'
-import * as request from 'supertest'
-import { ProductsModule } from '../products.module'
-
-describe('POST /api/products', () => {
-  let app: INestApplication
-
-  beforeAll(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      imports: [ProductsModule],
-    })
-      .overrideProvider(ProductRepository)
-      .useValue({ create: jest.fn(), findById: jest.fn() })
-      .compile()
-
-    app = module.createNestApplication()
-    app.useGlobalPipes(new ValidationPipe({ whitelist: true }))
-    await app.init()
-  })
-
-  afterAll(() => app.close())
-
-  it('cria produto e retorna 201', async () => {
-    const response = await request(app.getHttpServer())
-      .post('/api/products')
-      .set('Authorization', `Bearer ${testToken}`)
-      .send({ name: 'Produto Teste', price: 29.90 })
-
-    expect(response.status).toBe(201)
-    expect(response.body).toMatchObject({
-      data: { name: 'Produto Teste', price: 29.90 },
-    })
-  })
-
-  it('retorna 400 quando dados inválidos', async () => {
-    const response = await request(app.getHttpServer())
-      .post('/api/products')
-      .set('Authorization', `Bearer ${testToken}`)
-      .send({ name: '' }) // nome vazio, preço ausente
-
-    expect(response.status).toBe(400)
-    expect(response.body.message).toBeDefined()
-  })
-})
+Criar ou modificar um endpoint?        → tema 6 (API e comunicação) e tema 10 (segurança)
+Implementar autenticação?              → tema 6 (API) e tema 10 (segurança)
+Modelar dados, consultas ou migração?  → tema 5 (banco de dados)
+Criar worker, job ou fila?             → tema 7 (concorrência) e tema 8 (servidor)
+Integrar um serviço externo?           → tema 6 (API), tema 8 (resiliência) e tema 12 (erros)
+Implementar cache ou otimizar?         → tema 11 (performance)
+Escrever testes?                       → tema 9 (testes)
+Estruturar módulos e camadas?          → tema 2 (design) e tema 3 (patterns)
+Depurar um problema?                   → tema 12 (erros e logging)
 ```
 
-### Debugging e Observabilidade
-
-#### Logs estruturados (pino)
-
-```typescript
-import pino from 'pino'
-
-export const logger = pino({
-  level: process.env.LOG_LEVEL ?? 'info',
-  ...(process.env.NODE_ENV !== 'production' && {
-    transport: { target: 'pino-pretty' },
-  }),
-})
+---
 
-// ✅ Logar com contexto suficiente
-logger.info({ userId, productId, action: 'product.updated' }, 'Produto atualizado')
-logger.error({ error, userId, requestId }, 'Falha ao processar pagamento')
+## Fluxo de Trabalho
 
-// ❌ Nunca logar dados sensíveis
-// logger.info({ password, creditCard }) — NUNCA
-```
+1. **Entender**: ler o projeto (Padrão 1) e esclarecer o requisito, inclusive o que **não** está no escopo
+2. **Projetar**: escolher a abordagem na base universal; decidir contratos, erros e segurança antes de codar
+3. **Implementar**: seguir o padrão do projeto, em passos pequenos
+4. **Testar**: cobrir o caso feliz, os casos de erro e os limites
+5. **Validar**: percorrer o checklist de conclusão abaixo
 
-#### Request ID para rastreabilidade
+---
 
-```typescript
-// ✅ Propagar request ID em todas as operações
-app.addHook('onRequest', (req, reply, done) => {
-  req.id = req.headers['x-request-id'] as string ?? crypto.randomUUID()
-  reply.header('x-request-id', req.id)
-  done()
-})
-```
+## Base Universal
+
+Carregue **só o tema necessário** para a tarefa, em vez de todos de uma vez.
+
+| # | Tema | Nível | Carregue quando |
+|---|------|-------|-----------------|
+| 1 | [Fundamentos de programação](references/1-fundamentos-programacao.md) | Fundamental | Precisar revisar conceitos básicos de linguagem |
+| 2 | [Design e arquitetura](references/2-design-arquitetura.md) | Fundamental | Estruturar módulos, camadas ou aplicar SOLID e arquiteturas |
+| 3 | [Design patterns](references/3-design-patterns.md) | Importante | Escolher um padrão para um problema recorrente |
+| 4 | [Algoritmos e estruturas](references/4-algoritmos-estruturas.md) | Fundamental | Analisar complexidade ou escolher uma estrutura de dados |
+| 5 | [Banco de dados](references/5-banco-dados.md) | Fundamental | Modelar dados, consultas, índices, transações e migrações |
+| 6 | [API e comunicação](references/6-api-comunicacao.md) | Fundamental | Projetar endpoints, autenticação, paginação e versionamento |
+| 7 | [Concorrência e assincronismo](references/7-concorrencia-async.md) | Importante | Lidar com condições de corrida, jobs e processamento assíncrono |
+| 8 | [Arquitetura de servidor](references/8-arquitetura-servidor.md) | Importante | Escalar, tornar resiliente ou distribuir o sistema |
+| 9 | [Testes](references/9-testes.md) | Fundamental | Definir a estratégia e a qualidade dos testes |
+| 10 | [Segurança](references/10-seguranca.md) | Fundamental | Revisar vulnerabilidades, autenticação e dados sensíveis |
+| 11 | [Performance](references/11-performance.md) | Importante | Medir e otimizar desempenho e cache |
+| 12 | [Erros e logging](references/12-erros-logging.md) | Importante | Tratar falhas, registrar logs e observar o sistema |
+| 13 | [Qualidade de código](references/13-qualidade-codigo.md) | Fundamental | Refatorar, revisar código e documentar |
 
 ---
 
 ## Regras
 
 ### Nunca
-- Expor stack traces ou detalhes de erro em respostas de produção
-- Confiar em dados de entrada sem validação (query params, body, headers)
-- Armazenar senhas em texto plano (usar bcrypt/argon2)
-- Commitar secrets, API keys ou credenciais no código
-- Fazer operações síncronas bloqueantes no event loop
-- Processar webhooks de forma síncrona (enfileirar e responder 200 imediatamente)
+- Expor detalhes internos de erro em respostas de produção
+- Confiar em dados de entrada sem validação (parâmetros, corpo e cabeçalhos)
+- Armazenar senhas em texto plano
+- Commitar segredos, chaves de API ou credenciais no código
+- Fazer operações bloqueantes onde o modelo de execução não permite
+- Processar webhooks de forma síncrona (enfileirar e responder rapidamente)
 
 ### Sempre
-- Validar e sanitizar toda entrada externa (Zod, Joi, class-validator)
+- Validar e sanitizar toda entrada externa
 - Usar variáveis de ambiente para configuração
-- Incluir tratamento de erros e fallbacks em integrações externas
-- Testar casos de erro e edge cases, não só o happy path
-- Logar com contexto suficiente para diagnóstico
+- Incluir tratamento de erros e alternativas em integrações externas
+- Testar os casos de erro e os limites, não só o caso feliz
+- Registrar logs com contexto suficiente para o diagnóstico
 - Ler o código existente antes de criar novas abstrações
 
 ---
 
 ## Tratamento de Erros
 
-```typescript
-// ✅ Erro tipado com contexto
-export class AppError extends Error {
-  constructor(
-    public readonly message: string,
-    public readonly statusCode: number = 500,
-    public readonly code: string = 'INTERNAL_ERROR'
-  ) {
-    super(message)
-    this.name = 'AppError'
-  }
-}
-
-// ✅ Erros de negócio explícitos
-export class NotFoundError extends AppError {
-  constructor(resource: string, id: string) {
-    super(`${resource} com id '${id}' não encontrado`, 404, 'NOT_FOUND')
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(message = 'Não autorizado') {
-    super(message, 401, 'UNAUTHORIZED')
-  }
-}
-```
+### Stack ou dependência não identificada
+- Procurar o manifesto de dependências e a estrutura do projeto
+- Se não encontrar, perguntar à pessoa antes de prosseguir
+
+### Código existente com padrão diferente
+- Seguir o padrão do projeto, não o genérico deste skill
+- Registrar a divergência quando relevante
+
+### Teste falha depois de uma mudança
+- Verificar se o teste já falhava antes
+- Isolar a causa antes de ajustar o código ou o teste
 
 ---
 
 ## Checklist de Conclusão
 
-- [ ] Entrada validada (Zod / Joi / class-validator)
+- [ ] Entrada validada
 - [ ] Autenticação e autorização verificadas
-- [ ] Erros tipados e tratados (não vazar detalhes em produção)
+- [ ] Erros tipados e tratados, sem vazar detalhes em produção
 - [ ] Logs estruturados com contexto adequado
-- [ ] Testes unitários e/ou de integração
-- [ ] Rate limiting considerado (se endpoint público)
-- [ ] Cache implementado onde faz sentido
-- [ ] Operações destrutivas com confirmação/idempotência
+- [ ] Testes cobrindo o caso feliz, os erros e os limites
+- [ ] Limitação de taxa considerada (se o endpoint for público)
+- [ ] Cache aplicado onde faz sentido
+- [ ] Operações destrutivas com confirmação ou idempotência
 
 ---
 
@@ -746,9 +232,9 @@ export class UnauthorizedError extends AppError {
 | Artefato | Descrição |
 |----------|-----------|
 | Endpoint(s) | Rota com validação, autenticação e tratamento de erro |
-| Service/Use case | Lógica de negócio isolada e testável |
-| Worker/Job | Processamento assíncrono com retry e observabilidade |
-| Testes | Unitários e/ou integração cobrindo happy path e erros |
+| Serviço ou caso de uso | Lógica de negócio isolada e testável |
+| Worker ou job | Processamento assíncrono com repetição e observabilidade |
+| Testes | Cobrindo o caso feliz e os erros |
 
 ---
 
@@ -757,20 +243,32 @@ export class UnauthorizedError extends AppError {
 ```
 Implementação backend concluída!
 
-Framework: NestJS
-ORM: {Prisma / TypeORM / Drizzle}
 Funcionalidade: {descrição do que foi implementado}
+Stack do projeto: {linguagem e framework identificados no código}
 
 Segurança: {validação de entrada / autenticação / autorização}
 Testes: {criados / pendentes}
 Cache: {implementado / não necessário}
 
-Próximo passo: {rodar testes / fazer deploy / integrar com frontend}
+Próximo passo: {rodar os testes / integrar / publicar}
+```
+
+---
+
+## Aviso: uso só da skill base
+
+Quando o trabalho usar **só a skill base** e envolver uma tecnologia, framework ou ferramenta para a qual **não há skill especializado** disponível, avise a pessoa de forma explícita:
+
+```
+ℹ️ Estou usando só a skill base de backend.
+   Não há skill especializado para {tecnologia}; vou seguir os princípios universais
+   e o padrão que encontrei no projeto.
 ```
 
+Não invente convenções nem comandos específicos da tecnologia: siga o código do projeto e a base universal.
+
 ---
 
 ## Recursos Adicionais
 
-- **RabbitMQ**: Ver skill `eng-rabbitmq` para operações avançadas de mensageria
-- **Referências**: Veja [references/](references/) para links de documentação local
+- **Base universal**: os 13 temas em [references/](references/)