ai-prompt-characterization

AI Prompt Characterization (Modernização)

Quando usar

LLM carrega esta skill quando user vai modificar prompt ou tool definition de LLM em produção. Trigger phrases:

• "vou mudar esse prompt", "modificar prompt em prod"
• "atualizar tool definition", "function calling schema"
• "como testar mudança de prompt?"
• "characterization de prompt", "snapshot de generation"
• "esse prompt tem 300 linhas e ninguém testou ainda"
• prompt em arquivo como prompts/<name>.md ou string template em código

Insight central: prompts e tools são código legacy também quando:

• 100 linhas

• Em uso em produção
• Mudanças quebram silenciosamente (output diferente, downstream parser falha)
• Sem characterization tests

Regras absolutas

• Prompts são código. Tratam-se com mesmo rigor: versionado, testado, code-reviewed. NÃO são "config text que muda livremente".
• Determinismo via temperature=0 + seed. Anthropic Claude e OpenAI ambos suportam seed. Sem isso, characterization é flaky.
• Capture mais que text. Outputs incluem: text, finish_reason, tool_calls (se function calling), input_tokens, output_tokens, model_version. Snapshot de TODOS estes campos.
• Sanitize aggressively. Outputs LLM frequentemente incluem timestamps mencionados, UUIDs gerados, datas relativas. Normalize ANTES de snapshot.
• 5+ inputs cobrindo intents distintas. Não é "happy path × 5"; é "5 intents qualitativamente diferentes" — concision request, troubleshooting, explanation, creative, edge case.
• Behavioral coverage = % intents cobertas. Métrica não é coverage de "linhas do prompt" (não existe); é coverage de variações comportamentais.
• Re-rodar em CI quando model_version muda. Anthropic publica nova versão de Claude → re-rode characterization → revisar diffs → aceitar/rejeitar.

Patterns canônicos

Pattern 1: Setup canônico de characterization de prompt

// tests/characterization/prompts/generate-summary.test.ts
import { Anthropic } from '@anthropic-ai/sdk'
import { describe, test, expect } from 'vitest'
import { readFileSync } from 'fs'

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })
const PROMPT = readFileSync('prompts/generate-summary.md', 'utf-8')

interface PromptInput {
  systemPrompt: string
  userMessage: string
  maxTokens?: number
}

async function runPrompt(input: PromptInput) {
  const response = await client.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: input.maxTokens ?? 500,
    temperature: 0,  // determinismo
    system: input.systemPrompt,
    messages: [{ role: 'user', content: input.userMessage }],
  })
  return {
    text: response.content[0].type === 'text' ? response.content[0].text : '',
    stopReason: response.stop_reason,
    inputTokens: response.usage.input_tokens,
    outputTokens: response.usage.output_tokens,
    modelVersion: response.model,
  }
}

function sanitizeForSnapshot(o: any): any {
  return JSON.parse(
    JSON.stringify(o, (key, value) => {
      // normalizar timestamps mencionados ("Today is 2026-05-08") → "<DATE>"
      if (typeof value === 'string') {
        value = value.replace(/\d{4}-\d{2}-\d{2}/g, '<DATE>')
        value = value.replace(/\d{2}:\d{2}(:\d{2})?/g, '<TIME>')
        value = value.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/g, '<UUID>')
      }
      // permitir model version mas separar para audit (não no snapshot)
      if (key === 'modelVersion') return '<MODEL>'
      return value
    })
  )
}

describe('generate-summary prompt — characterization', () => {
  test('intent: concise summary of long article', async () => {
    const captured = await runPrompt({
      systemPrompt: PROMPT,
      userMessage: 'Resuma em 2 sentenças: [longo artigo de 500 palavras]...',
    })
    expect(sanitizeForSnapshot(captured)).toMatchSnapshot()
  })

  test('intent: bullet-list summary', async () => { /* ... */ })
  test('intent: technical/code summary', async () => { /* ... */ })
  test('intent: ambiguous request (edge)', async () => { /* ... */ })
  test('intent: hostile / prompt injection attempt', async () => { /* ... */ })
})