@luanpdd/kit-mcp 1.9.0 → 1.11.0

package/kit/skills/legacy-api-only-applications/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: legacy-api-only-applications
+description: Use ao escrever ou refatorar código que é maioritariamente wrapper de API externa (cap 15 Feathers + Supabase Edge Functions). Adapter / anti-corruption layer canônico — interface mínima testável + adapter para API real.
+---
+
+# Legacy — API-Only Applications
+
+## Quando usar
+
+LLM carrega esta skill quando user trabalha em código que é primariamente wrapper de API externa. Trigger phrases:
+
+- "essa edge function só chama Stripe/OpenAI/Twilio"
+- "como testar integração com [vendor]?"
+- "anti-corruption layer", "adapter pattern"
+- "API-only application", "cap 15 Feathers"
+- "wrapper de API"
+- arquivo em `supabase/functions/<name>/index.ts` com 60%+ de chamadas a SDKs/APIs externos
+
+## Regras absolutas
+
+- **Adapter pattern é a resposta canônica.** Code de produção depende de **interface mínima**, não da API completa do vendor. Adapter concreto envolve a API real.
+- **Interface mínima = só o que VOCÊ usa.** SDKs do Stripe/OpenAI/etc têm 100+ métodos; você usa 5. Sua interface tem 5.
+- **Anti-corruption layer (DDD) = adapter + tradução de tipos.** Tipos do vendor (e.g., `Stripe.Charge`, `OpenAI.ChatCompletion`) NÃO atravessam camadas internas. Adapter traduz vendor type → domain type.
+- **Modernização Supabase Edge Functions:** Edge Function que wrappar Stripe/OpenAI é o caso paradigmático moderno do cap 15. Pattern canônico: handler depende de interface, adapter implementa, adapter testado isolado, fake adapter em testes.
+- **Modernização LLM providers:** OpenAI/Anthropic clients são API externa. Aplicar exatamente o mesmo pattern — `LLMProvider` interface + `OpenAIAdapter` + `AnthropicAdapter` + `FakeLLMProvider`. Nunca acoplar handler ao SDK específico.
+- **Versionar a interface, não a API do vendor.** Quando vendor muda assinatura, adapter absorve a mudança; consumidor (handler interno) não vê.
+- **Idempotência via adapter.** Adapter pode adicionar idempotency key, retry com jitter, deadline propagation, sem que handler precise saber.
+
+## Patterns canônicos
+
+### Pattern 1: Adapter para vendor API (Stripe canônico)
+
+```ts
+// ANTES — handler acoplado ao SDK Stripe (intestável sem mock global)
+import Stripe from 'stripe'
+
+const stripe = new Stripe(Deno.env.get('STRIPE_KEY')!)
+
+Deno.serve(async (req) => {
+  const order = await req.json()
+  const charge = await stripe.charges.create({  // ← acoplamento direto
+    amount: order.totalCents,
+    currency: order.currency,
+    source: order.cardToken,
+  })
+  return new Response(JSON.stringify({ id: charge.id, status: charge.status }))
+})
+
+// DEPOIS — handler depende de interface mínima
+interface PaymentGateway {
+  charge(input: ChargeInput): Promise<ChargeResult>
+}
+type ChargeInput = { amountCents: number; currency: string; cardToken: string }
+type ChargeResult = { id: string; status: 'succeeded' | 'failed' | 'pending' }
+
+class StripeAdapter implements PaymentGateway {
+  constructor(private stripe: Stripe) {}
+  async charge(input: ChargeInput): Promise<ChargeResult> {
+    const c = await this.stripe.charges.create({
+      amount: input.amountCents,
+      currency: input.currency,
+      source: input.cardToken,
+    })
+    // anti-corruption: traduz Stripe.Charge.status para nosso domain enum
+    const status = this.translateStatus(c.status)
+    return { id: c.id, status }
+  }
+  private translateStatus(s: Stripe.Charge.Status): ChargeResult['status'] {
+    if (s === 'succeeded') return 'succeeded'
+    if (s === 'failed' || s === 'canceled') return 'failed'
+    return 'pending'
+  }
+}
+
+// Em produção
+const gateway: PaymentGateway = new StripeAdapter(new Stripe(Deno.env.get('STRIPE_KEY')!))
+
+// Handler — agora testável
+async function handleCharge(req: Request, gateway: PaymentGateway) {
+  const order = await req.json()
+  const result = await gateway.charge({
+    amountCents: order.totalCents,
+    currency: order.currency,
+    cardToken: order.cardToken,
+  })
+  return new Response(JSON.stringify(result))
+}
+
+Deno.serve(req => handleCharge(req, gateway))
+
+// Em teste
+class FakePaymentGateway implements PaymentGateway {
+  charged: ChargeInput[] = []
+  result: ChargeResult = { id: 'ch_fake', status: 'succeeded' }
+  async charge(input: ChargeInput): Promise<ChargeResult> {
+    this.charged.push(input)
+    return this.result
+  }
+}
+
+test('handleCharge — typical input', async () => {
+  const gw = new FakePaymentGateway()
+  const req = new Request('http://x', {
+    method: 'POST',
+    body: JSON.stringify({ totalCents: 5000, currency: 'BRL', cardToken: 'tok_x' }),
+  })
+  await handleCharge(req, gw)
+  expect(gw.charged).toHaveLength(1)
+  expect(gw.charged[0].amountCents).toBe(5000)
+})
+```
+
+### Pattern 2: Adapter para LLM provider (modernização total — sem precedente em 2004)
+
+```ts
+// LLM provider como dependência testável (canônico em 2026)
+interface LLMProvider {
+  generate(input: GenerateInput): Promise<GenerateResult>
+}
+type GenerateInput = {
+  prompt: string
+  maxTokens: number
+  temperature?: number
+  seed?: number  // determinismo em testes
+}
+type GenerateResult = {
+  text: string
+  finishReason: 'stop' | 'length' | 'content_filter'
+  inputTokens: number
+  outputTokens: number
+}
+
+class OpenAIAdapter implements LLMProvider {
+  constructor(private client: OpenAI) {}
+  async generate(input: GenerateInput): Promise<GenerateResult> {
+    const r = await this.client.chat.completions.create({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: input.prompt }],
+      max_tokens: input.maxTokens,
+      temperature: input.temperature ?? 0,
+      seed: input.seed,
+    })
+    return {
+      text: r.choices[0].message.content ?? '',
+      finishReason: this.translateFinish(r.choices[0].finish_reason),
+      inputTokens: r.usage?.prompt_tokens ?? 0,
+      outputTokens: r.usage?.completion_tokens ?? 0,
+    }
+  }
+  private translateFinish(f: string): GenerateResult['finishReason'] {
+    if (f === 'stop') return 'stop'
+    if (f === 'length') return 'length'
+    return 'content_filter'
+  }
+}
+
+class AnthropicAdapter implements LLMProvider {
+  constructor(private client: Anthropic) {}
+  async generate(input: GenerateInput): Promise<GenerateResult> {
+    const r = await this.client.messages.create({
+      model: 'claude-opus-4-7',
+      messages: [{ role: 'user', content: input.prompt }],
+      max_tokens: input.maxTokens,
+      temperature: input.temperature ?? 0,
+    })
+    return {
+      text: r.content[0].type === 'text' ? r.content[0].text : '',
+      finishReason: this.translateStop(r.stop_reason),
+      inputTokens: r.usage.input_tokens,
+      outputTokens: r.usage.output_tokens,
+    }
+  }
+  private translateStop(s: string | null): GenerateResult['finishReason'] {
+    if (s === 'end_turn') return 'stop'
+    if (s === 'max_tokens') return 'length'
+    return 'content_filter'
+  }
+}
+
+class FakeLLMProvider implements LLMProvider {
+  responses: GenerateResult[] = []
+  callIndex = 0
+  async generate(_: GenerateInput): Promise<GenerateResult> {
+    if (this.callIndex < this.responses.length) return this.responses[this.callIndex++]
+    return { text: 'fake response', finishReason: 'stop', inputTokens: 10, outputTokens: 5 }
+  }
+}
+```
+
+**Insight:** sem essa abstração, edge function fica acoplada a 1 vendor. Trocar OpenAI → Anthropic = rewrite. Com adapter = trocar 1 linha (`new AnthropicAdapter(...)` em vez de `new OpenAIAdapter(...)`).
+
+### Pattern 3: Anti-corruption layer (DDD)
+
+```ts
+// VENDOR types — bagunça típica (Stripe, OpenAI, Twilio têm shapes próprios)
+type StripeChargeRaw = {
+  id: string
+  amount: number  // cents
+  currency: string  // lowercase ISO
+  status: 'succeeded' | 'pending' | 'failed' | 'canceled'
+  receipt_url?: string  // snake_case do vendor
+  metadata?: Record<string, string>
+}
+
+// DOMAIN types — sua linguagem
+type Charge = {
+  chargeId: string
+  amountCents: number
+  currencyIso4217: string  // uppercase
+  status: ChargeStatus  // domain enum, NÃO o do vendor
+  receiptUrl?: string
+}
+type ChargeStatus = 'succeeded' | 'failed' | 'pending'  // simplificou; canceled vira failed
+
+// Adapter ABSORVE diferenças — domain interno NÃO vê StripeChargeRaw
+class StripeAdapter implements PaymentGateway {
+  async charge(input: ChargeInput): Promise<ChargeResult> {
+    const raw = await this.stripe.charges.create(...)
+    return this.toDomain(raw)
+  }
+  private toDomain(raw: StripeChargeRaw): Charge {
+    return {
+      chargeId: raw.id,
+      amountCents: raw.amount,
+      currencyIso4217: raw.currency.toUpperCase(),
+      status: raw.status === 'canceled' || raw.status === 'failed' ? 'failed' : raw.status,
+      receiptUrl: raw.receipt_url,
+    }
+  }
+}
+```
+
+### Pattern 4: Adapter aplicando cross-cutting concerns
+
+Adapter é lugar canônico para retry, timeout, idempotency, instrumentation:
+
+```ts
+class StripeAdapterResilient implements PaymentGateway {
+  constructor(private stripe: Stripe, private logger: Logger) {}
+
+  async charge(input: ChargeInput): Promise<ChargeResult> {
+    const idempotencyKey = await crypto.randomUUID()
+    const startMs = performance.now()
+
+    try {
+      const c = await retryWithJitter(
+        () => this.stripe.charges.create(
+          { amount: input.amountCents, currency: input.currency, source: input.cardToken },
+          { idempotencyKey, timeout: 5000 }
+        ),
+        { maxRetries: 3, baseMs: 250 }
+      )
+
+      const latency = performance.now() - startMs
+      this.logger.info('stripe.charge', { latency_ms: latency, status: c.status })
+      return this.toDomain(c)
+    } catch (e) {
+      this.logger.warn('stripe.charge.failed', { error: e.message })
+      throw e
+    }
+  }
+}
+```
+
+**Cross-suite:**
+- Retry pattern de v1.11 (`retry-strategies`) aplicável aqui
+- Logging segue v1.9 (`structured-events`)
+- Latency histogram segue v1.10 (`four-golden-signals`)
+- Adapter é exatamente onde "instrumentation shift-left" (v1.9 ODD) faz mais sentido
+
+### Pattern 5: Quando NÃO criar adapter
+
+```text
+- Vendor SDK já tem interface mínima e estável (raríssimo)
+- Edge function é one-shot script (não tem testes nem manutenção continuada)
+- Spike/POC para validar viabilidade (descartável após decisão)
+- Adapter custaria > 4h e prazo é < 1 dia (faça inline com warning de débito)
+```
+
+## Anti-patterns
+
+### ANTI: handler depende direto do SDK do vendor
+
+```text
+ANTI: handler.ts: import Stripe from 'stripe'; ... stripe.charges.create(...)
+
+PROBLEMA: handler intestável sem mocking SDK inteiro. Trocar vendor
+          = rewrite. Vendor SDK breaking change = bugs em handler.
+
+CERTO: handler depende de interface mínima `PaymentGateway`. Adapter
+       absorve SDK. Testes do handler usam fake. Trocar vendor =
+       trocar 1 linha (constructor injection).
+```
+
+### ANTI: adapter expondo tipos do vendor
+
+```text
+ANTI: interface PaymentGateway { charge(input): Promise<Stripe.Charge> }
+
+PROBLEMA: Stripe.Charge atravessa camadas internas. Quando Stripe
+          renomeia field, refactor cascateia. Sem anti-corruption.
+
+CERTO: interface tem TIPO próprio (ChargeResult). Adapter traduz.
+       Stripe.Charge fica encapsulado dentro do adapter.
+```
+
+### ANTI: 1 adapter por método do vendor
+
+```text
+ANTI: StripeChargeAdapter, StripeRefundAdapter, StripePayoutAdapter,
+      StripeCustomerAdapter — 1 classe por endpoint.
+
+PROBLEMA: explosão. 30 adapters para 1 vendor. Cross-cutting (retry,
+          logging) duplicado em cada um.
+
+CERTO: 1 adapter por VENDOR + capability cluster. StripePaymentAdapter
+       (charge + refund), StripeCustomerAdapter (create + update).
+       Cross-cutting concerns aplicados consistente.
+```
+
+### ANTI: fake adapter testando o vendor real
+
+```text
+ANTI: FakeStripeAdapter faz HTTP real para Stripe sandbox em testes.
+
+PROBLEMA: testes lentos, flaky, dependentes de rede, custam $.
+          Sandbox vendor pode ter rate limits.
+
+CERTO: FakeStripeAdapter implementa interface NÃO depende de Stripe.
+       Coleta inputs em array; retorna outputs canned. Test puramente
+       local. Fast, deterministic, free.
+```
+
+## Verificação
+
+1. Handler depende de interface, não de SDK do vendor diretamente
+2. Adapter implementa interface, encapsula SDK do vendor
+3. Tipos do vendor não atravessam adapter (anti-corruption)
+4. Fake adapter existe; tests do handler usam fake
+5. Adapter centraliza retry/timeout/idempotency/logging (cross-cutting)
+6. Tipos de DOMAIN são uppercase ISO/etc (não passam por convenção do vendor)
+7. Trocar vendor = trocar 1 linha (constructor)
+
+---
+
+## Ver também
+
+- [`_shared-legacy/glossary.md`](../_shared-legacy/glossary.md) — vocabulário (adapter, anti-corruption layer)
+- [`legacy-seams-and-test-harness`](../legacy-seams-and-test-harness/SKILL.md) — extract-interface é técnica do cap 25 que produz adapter
+- [`legacy-characterization-tests`](../legacy-characterization-tests/SKILL.md) — characterize handler usando fake adapter (sem rede)
+- [`supabase-edge-functions`](../supabase-edge-functions/SKILL.md) (v1.8) — Edge Functions são API-only paradigmáticas; adapter pattern aplicável
+- [`supabase-edge-fn-writer`](../../agents/supabase-edge-fn-writer.md) (v1.8) — patch v1.12: adapter pattern como template default
+- [`four-golden-signals`](../four-golden-signals/SKILL.md) (v1.10) — adapter é lugar canônico de instrumentation
+- [`retry-strategies`](../retry-strategies/SKILL.md) (v1.11 — quando entregar) — retry pattern aplicado dentro do adapter
+- [`llm-as-dependency`](../llm-as-dependency/SKILL.md) — caso especial de API-only para LLM providers
+
+*Material-fonte: Working Effectively with Legacy Code — Feathers, 2004 — Cap 15: "My Application Is All API Calls".*
+*Modernização (2026):* Supabase Edge Functions + LLM providers (OpenAI/Anthropic) como aplicação canônica do pattern.

package/kit/skills/legacy-characterization-tests/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: legacy-characterization-tests
+description: Use ao refatorar código legado SEM testes prévios — characterization tests (cap 13 Feathers) capturam comportamento atual como golden snapshot, viram oracle imutável durante o refactor. Bloqueador para legacy refactor.
+---
+
+# Legacy — Characterization Tests
+
+## Quando usar
+
+LLM carrega esta skill quando o user vai modificar código sem suite de testes adequada e o objetivo é refactor (não bug fix). Trigger phrases:
+
+- "refatorar [arquivo grande]", "extract method de", "quebrar essa classe"
+- "esse arquivo não tem testes", "como começo testando isso?"
+- "preservar comportamento", "snapshot test", "golden master"
+- "cap 13 Feathers", "characterization test"
+- "código legado", "legacy code", "edit and pray"
+- arquivo > 500 linhas que será modificado
+- arquivo com contrato externo (webhook, API, integração) sendo modificado
+
+Carrega antes de planejar/executar refactor. **Bloqueia execução** até characterization existir.
+
+## Regras absolutas
+
+- **Legacy code = código sem testes** (definição Feathers, não emocional). Idade não importa. Estética não importa. **Cobertura comportamental** importa.
+- **Characterize first, refactor second.** Sempre. Sem exceção. Pular esse passo é "edit and pray" — o modo default que o livro existe para combater.
+- **Capture o que o código FAZ, não o que DEVERIA fazer.** Se há bug, o teste preserva o bug. Bug fix é commit separado, depois do refactor, com seu próprio teste.
+- **Mínimo de 5-10 inputs cobrindo grupos de equivalência** — null/vazio, válido típico, válido extremo, inválido recoverable, inválido fatal. Menos que isso = baseline frágil.
+- **Behavioral coverage ≥ 70-80% antes de qualquer extract/move/rename**. Coverage % de linha NÃO É proxy de safety — verifique branches via mutation testing.
+- **Golden master/snapshot é decisão, não copy-paste.** Leia output capturado linha por linha antes de salvar. Bugs conhecidos viram comentários inline (`// BUG #X: deveria Y, é Z`). PII/secrets/UUIDs locais → redact deterministic (hash, mask).
+- **Vermelho em characterization test = regressão até prova ao contrário.** Nunca "atualize o expected" sem investigar e documentar a mudança comportamental no commit.
+- **Bug fix dentro de refactor PR = veto.** Misturar invalida o oracle e torna PR não-revisável. Single-goal editing (cap 22) — uma intenção por commit.
+
+## Patterns canônicos
+
+### Pattern 1: Workflow de characterization (cap 13)
+
+```text
+1. Identificar o método/classe/arquivo a refatorar
+2. Inventariar entradas e saídas:
+   - Inputs: parâmetros + globals lidos + I/O (DB read, API call)
+   - Outputs: return + parâmetros mutados + I/O (DB write, log, API call)
+3. Para cada grupo de equivalência (5+ inputs):
+   a. Construir input ("arrange")
+   b. Executar código real ("act") — sem mocks ainda; isole I/O com seam mínimo se necessário
+   c. Capturar output completo ("snapshot")
+   d. REVISAR output linha por linha — marcar bugs conhecidos como comments
+   e. Salvar como `expected.txt` ou `__snapshots__/foo.test.ts.snap`
+4. Escrever teste:
+   - Arrange = mesmo input
+   - Act = mesmo código
+   - Assert = output igual ao salvo (deep equal OR snapshot match)
+5. Rodar suite — TODOS verdes → BASELINE estabelecido
+6. Refactor pode começar
+```
+
+### Pattern 2: Grupos de equivalência canônicos
+
+Cobertura mínima — pelo menos 1 caso por grupo:
+
+| Grupo | Definição | Exemplo (função `parseOrder(input)`) |
+|---|---|---|
+| **Empty** | Input ausente/zero/vazio | `parseOrder(null)`, `parseOrder({})` |
+| **Typical valid** | Caso comum esperado | `parseOrder({ id: 'O123', items: [...] })` |
+| **Boundary valid** | Limites superiores/inferiores válidos | `parseOrder({ ..., items: [singleItem] })`, `parseOrder({ ..., items: [maxItems_x_50] })` |
+| **Recoverable invalid** | Erro que código trata graceful | `parseOrder({ id: 'O123', items: 'malformed' })` — espera-se exceção tipada |
+| **Fatal invalid** | Erro que código não trata (vai propagar/crashar) | `parseOrder(undefined)` — espera-se NPE/crash |
+| **Side-effect heavy** | Input que dispara muitos side effects (logs, DB writes) | Ordem grande que escreve em audit log + cache + queue |
+| **Edge case histórico** | Cases conhecidos que já causaram bugs (consultar git log/issues) | Input com encoding UTF-16, timestamp negativo |
+
+### Pattern 3: Snapshot tooling por linguagem
+
+| Linguagem | Framework | Snapshot syntax |
+|---|---|---|
+| **JavaScript/TypeScript** | Jest, Vitest | `expect(output).toMatchSnapshot()` ou `toMatchInlineSnapshot()` |
+| **Python** | pytest + pytest-snapshot OR syrupy | `snapshot.assert_match(output)` ou `assert output == snapshot` |
+| **Java** | JUnit + ApprovalTests | `Approvals.verify(output)` |
+| **Ruby** | RSpec + rspec-snapshot | `expect(output).to match_snapshot('foo_bar')` |
+| **Go** | go-cmp + cupaloy/snaps | `cupaloy.SnapshotT(t, output)` |
+| **C#** | Verify, Snapshooter | `await Verifier.Verify(output)` |
+| **Rust** | insta | `insta::assert_yaml_snapshot!(output)` |
+
+**Anti-tooling:** evitar diff visual cru (eyeballed) — snapshot framework gera diff legível e atualiza expected via flag (`--updateSnapshot` no Jest, `--snapshot-update` em pytest). Sem framework, refactor de "atualizar oracle" vira manual e propenso a erro.
+
+### Pattern 4: Captura de outputs com side effects
+
+Quando código tem side effects (DB writes, HTTP calls, logs), o snapshot deve incluir **todos** os efeitos observáveis, não só return. Estratégia:
+
+```ts
+// PT-BR: capturar return + lista canônica de efeitos
+async function characterize_placeOrder() {
+  const sideEffects = {
+    dbWrites: [] as Array<{ table: string, op: string, row: any }>,
+    httpCalls: [] as Array<{ url: string, method: string, body: any }>,
+    logs: [] as Array<{ level: string, msg: string, fields: any }>,
+    queueMsgs: [] as Array<{ queue: string, payload: any }>,
+  }
+
+  // Wire fakes que populam sideEffects ao invés de fazer real I/O
+  const db = makeFakeDb(sideEffects.dbWrites)
+  const http = makeFakeHttp(sideEffects.httpCalls)
+  const log = makeFakeLogger(sideEffects.logs)
+  const queue = makeFakeQueue(sideEffects.queueMsgs)
+
+  const input = { customerId: 'C-42', items: [{ sku: 'SKU-1', qty: 2 }] }
+  const result = await placeOrder(input, { db, http, log, queue })
+
+  return {
+    return: result,
+    sideEffects,
+  }
+  // ↑ ESSE objeto é o que vira snapshot
+}
+
+// Test
+test('placeOrder — typical valid input', async () => {
+  const captured = await characterize_placeOrder()
+  expect(captured).toMatchSnapshot()
+})
+```
+
+Snapshot resultante captura return E efeitos, ambos congelados.
+
+### Pattern 5: Determinismo — eliminar non-determinism antes de capturar
+
+Datas, UUIDs, random, nanos — todos não-determinísticos por default. Capture-os como dependência injetada:
+
+```ts
+// PT-BR: dependências injetadas tornam snapshot reproduzível
+const fakeClock = () => new Date('2024-01-15T10:00:00Z')  // congelado
+const fakeUuid = (() => { let n = 0; return () => `uuid-${++n}` })()  // determinístico
+const fakeRandom = (() => { let n = 0; return () => (n++ % 1000) / 1000 })()  // ciclico
+
+const result = await placeOrder(input, {
+  ...realDeps,
+  clock: fakeClock,
+  uuidGen: fakeUuid,
+  random: fakeRandom,
+})
+```
+
+Sem isso, cada run produz snapshot diferente → "flaky tests" → ninguém confia → suite ignorada.
+
+### Pattern 6: Sanitização para snapshot
+
+Output cru pode incluir dados sensíveis ou voláteis. Sanitize ANTES de salvar:
+
+```ts
+function sanitizeForSnapshot(o: any): any {
+  return JSON.parse(
+    JSON.stringify(o, (key, value) => {
+      if (key === 'apiKey' || key === 'password' || key === 'token') return '***REDACTED***'
+      if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) return '<TIMESTAMP>'
+      if (typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}/.test(value)) return '<UUID>'
+      return value
+    })
+  )
+}
+```
+
+Aplicar **antes** de `expect(...).toMatchSnapshot()`. Documentar quais campos foram sanitized para que reviewer entenda.
+
+### Pattern 7: Behavioral coverage check (mutation testing)
+
+Coverage de linha NÃO É proxy de safety. Para confirmar que characterization realmente cobre comportamento:
+
+```bash
+# JavaScript/TypeScript
+npx stryker run
+
+# Python
+mutmut run
+mutmut results
+
+# Java
+mvn pitest:mutationCoverage
+
+# Métrica desejada: ≥ 70% de mutants killed
+# Survived mutants = comportamento NÃO observado pelos tests = ponto cego
+```
+
+Survived mutant tipicamente indica que falta um observation point. Adicione um test que exercita o branch correspondente.
+
+### Pattern 8: Effort budget para characterization
+
+Dados empíricos baseados em arquivos típicos:
+
+| Tamanho do alvo | Inputs a gerar | Esforço típico | Cobertura esperada |
+|---|---|---|---|
+| Método 20-50 linhas, 1-3 branches | 5-7 inputs | 1-2h | 80-90% behavioral |
+| Método 50-150 linhas, 3-7 branches | 8-12 inputs | 3-6h | 70-85% behavioral |
+| Método 150+ linhas (monster) | 15-25 inputs | 1-3 dias | 60-75% behavioral (exigir cap 22 antes) |
+| Classe inteira 300-500 linhas | 20-40 inputs | 2-5 dias | 65-80% behavioral |
+| Arquivo > 500 linhas | proibido refatorar sem split first | depende | exigir extract class antes |
+
+**Não negocie cobertura para baixo "para ganhar tempo".** Cobertura insuficiente = false sense of safety, pior que ausência total.
+
+## Anti-patterns
+
+### ANTI: testar o "comportamento esperado"
+
+```text
+ANTI: "Vou escrever um teste do que o método deveria fazer e refatorar
+       até passar".
+
+PROBLEMA: o método tem bugs. Teste-do-esperado falha imediato porque o
+          estado atual É buggy. Você não consegue rodar nem 1 verde.
+          Frustrado, "ajusta" expected para o atual — perdeu o ponto
+          inteiro do exercício.
+
+CERTO: characterize first. Capture o que o código faz HOJE, com bugs.
+       Refactor preserva isso. Bug fix vem depois, em commit separado.
+```
+
+### ANTI: 1 teste cobrindo "happy path"
+
+```text
+ANTI: "Adicionei 1 test do caso comum, vai dar".
+
+PROBLEMA: branches raras (null, vazio, edge case) são exatamente onde
+          regressão se esconde. Refactor "verde" no test de happy path
+          mas quebra null handling silencioso → bug em prod no primeiro
+          input null real (1% do tráfego, mas existe).
+
+CERTO: 5+ inputs cobrindo grupos canônicos de equivalência. 1h a mais
+       de teste = N horas a menos de incident.
+```
+
+### ANTI: snapshot sem revisão
+
+```text
+ANTI: rodar code → toMatchSnapshot() → CI verde → commit. "Funcionou".
+
+PROBLEMA: snapshot pode incluir bug, PII, secret, UUID local. CI
+          "verde" só significa "snapshot está consistente com captura
+          anterior" — não que o conteúdo está certo.
+
+CERTO: ler snapshot inteiro antes de commit. Marcar bugs com comments,
+       redact PII com sanitize fn, verificar que não há secrets. Commit
+       de snapshot é decisão de produto, não automation.
+```
+
+### ANTI: mocks excessivos = teste de mock, não de código
+
+```text
+ANTI: tudo mockado — DB, HTTP, log, queue, clock, random. Test passa.
+
+PROBLEMA: você testou que o método chama os mocks na ordem certa, não
+          que o método produz output correto para entrada real. Refactor
+          que muda ORDEM de chamadas (igualmente correto) quebra mock
+          assertion mas é regressão zero.
+
+CERTO: minimize mocks. Use fakes que coletam side effects observáveis
+       (lista, counter), assert sobre o STATE final dos fakes, não
+       sobre sequência de invocações. Snapshot do state pós-execução
+       é mais resiliente que assertion de invocation order.
+```
+
+### ANTI: pular characterization "porque o método é simples"
+
+```text
+ANTI: "esse método tem 30 linhas, é óbvio o que faz, vou refatorar
+       direto".
+
+PROBLEMA: 30 linhas têm ~5-10 branches implícitas (early return, &&
+          short-circuit, exceções, type coercion). Cada branch é uma
+          assumption não-verificada. "Óbvio" é ilusão de quem escreveu
+          o código original — você está lendo, é diferente.
+
+CERTO: SEMPRE characterize, mesmo métodos curtos. 30 linhas → 5 inputs
+       → 30 minutos. Custo trivial. Benefício: zero "wait, eu não sabia
+       que isso retornava undefined em X". Descobre-se durante captura,
+       não em prod.
+```
+
+### ANTI: characterization em fase de bug fix
+
+```text
+ANTI: "Estou consertando bug X, vou aproveitar e characterize tudo
+       enquanto estou aqui".
+
+PROBLEMA: scope creep. PR vira inrevisável (bug fix + 50 testes novos
+          + redesenho mental). Linha entre "preservei comportamento" e
+          "modifiquei comportamento" desaparece.
+
+CERTO: bug fix é bug fix. Escreva 1 teste do COMPORTAMENTO CORRETO
+       (TDD agora, porque você está mudando intenção). Characterize é
+       fase prévia ao refactor — separa em PR/sprint próprio.
+```
+
+## Verificação
+
+Antes de iniciar refactor de código legado:
+
+1. **Inventário completo de inputs/outputs** — todos os parâmetros, globals lidos, I/O capturados
+2. **5+ inputs cobrindo grupos de equivalência** — empty, typical, boundary, invalid recoverable, invalid fatal
+3. **Snapshots revisados linha por linha** — bugs marcados, PII/secrets redacted
+4. **Determinismo garantido** — clock/uuid/random injetáveis, fakes substituem em teste
+5. **Side effects capturados** — DB writes, HTTP calls, logs, queue msgs incluídos no snapshot
+6. **Suite verde** — todos characterization tests rodam OK no main branch
+7. **Behavioral coverage medida** — mutation testing rodado, ≥ 70% mutants killed
+8. **Documentação no PR** — link para snapshots, lista de bugs preservados, fonte do oracle
+
+## Limiar de "pronto para refactor"
+
+```text
+Total inputs cobertos:               ≥ 5  (mínimo); 10+ recomendado
+Behavioral coverage (mutation kill): ≥ 70%
+Branches conhecidas testadas:        100% (todas as branches do código que será tocado)
+Side effects capturados:             100% (zero side effect "esquecido")
+Snapshots revisados:                 100% (cada arquivo lido por humano)
+Bugs documentados como TODO:         lista no PR
+Determinismo:                        OK em 10 runs consecutivos sem flaky
+```
+
+Se algum item < limiar → não inicie refactor. Volte para characterization.
+
+---
+
+## Ver também
+
+- [`_shared-legacy/glossary.md`](../_shared-legacy/glossary.md) — vocabulário canônico
+- [`legacy-seams-and-test-harness`](../legacy-seams-and-test-harness/SKILL.md) — quando characterization requer quebrar dependência primeiro
+- [`legacy-effect-analysis`](../legacy-effect-analysis/SKILL.md) — quais inputs escolher? effect sketch identifica
+- [`legacy-monster-methods`](../legacy-monster-methods/SKILL.md) — método > 100 linhas? characterization tem trato especial
+- [`legacy-sprout-wrap-techniques`](../legacy-sprout-wrap-techniques/SKILL.md) — alternativa quando characterization é caro demais (sprout side-steps)
+- [`pre-refactor-characterization`](../pre-refactor-characterization/SKILL.md) — gate auto-trigger que bloqueia refactor sem characterization
+- [`event-based-slos`](../event-based-slos/SKILL.md) (v1.9) — refactor pode regredir SLO; characterization protege
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) (v1.10) — PRR Axe 5 (Change Management) verifica characterization antes de aceitar mudança em prod
+
+*Material-fonte: Working Effectively with Legacy Code — Feathers, 2004 — Cap 13: "I Need to Make a Change, But I Don't Know What Tests to Write" + Cap 23: "How Do I Know That I'm Not Breaking Anything?".*