Módulo 4.1 — Inventário da Biblioteca

📋 Mapeando todos os prompts em produção

O primeiro movimento expert é parar de assumir que você conhece sua biblioteca. Equipes que rodam há 1+ ano no 4.6 tipicamente têm dezenas de prompts espalhados por repos, apps e wiki.

📍 Onde procurar

•claude.md / CLAUDE.md em cada repo
•Strings literais em código (system prompt em .ts/.py)
•Arquivos .prompt, .md, .txt em prompts/
•Slash commands customizados (.claude/commands/)
•Notion/Confluence (humanos copiam e colam)

🔧 Comandos úteis

# Grep por padrões comuns de prompt
git grep -l "system:" | head -20
git grep -l "claude-3" -- '*.ts' '*.py'
find . -iname "*claude*.md"
find . -iname "*.prompt"

# Slash commands locais
ls ~/.claude/commands/

💡 Dica Prática

Peça ao próprio Claude Code: "Varra este monorepo e liste todos os prompts, system instructions e claude.md. Formato: caminho | tipo | última modificação | tamanho." Ele faz em 1 turno.

🏷️ Categorias: System, Harness, Snippet, Docs

Cada categoria tem blast radius diferente. Migrar sem essa taxonomia leva a retrabalho.

Categoria	Exemplo	Blast radius	Frequência mudança
System	Instrução base de um agente em produção	Alto	Trimestral
Harness	Scaffold `init.sh` + `spec.md`	Alto	Mensal
Snippet	Bloco reusável (ex: anti-hardcoding)	Médio	Semanal
Docs	`claude.md` do repo	Baixo	Mensal

🔍 Identificando "prompts de 4.6" silenciosamente

Essas frases são fósseis do 4.6 que ainda rodam. No 4.7 elas ativamente prejudicam performance.

🚨 Regex detector (rode em toda biblioteca)

# Anti-patterns comuns
git grep -iE "double[- ]check|MUST use|CRITICAL:|if in doubt" -- '*.md' '*.ts' '*.py'
git grep -iE "after every [0-9]+ (tool|turn)" -- '*.md' '*.ts' '*.py'
git grep -iE "budget_tokens|budget-tokens" -- '*.ts' '*.py' '*.json'
git grep -iE "be conservative|only report.*confident" -- '*.md'
git grep -iE "claude-3-(opus|sonnet)-20240" -- '*.ts' '*.py'

❌ Smells de 4.6

"double-check your answer"
"after every 5 tool calls, summarize"
"CRITICAL: MUST use Read tool"
"if in doubt, use Grep"
"be conservative; only flag issues you're sure of"
budget_tokens: 10000

✓ Padrões modernos

"Use Read when [condição específica]"
"Use Grep for content search"
"Report every issue + confidence + severity"
thinking: {type: "adaptive"}
Effort calibrado via cliente

📊 Score de risco — qual migrar primeiro

Fórmula simples: Score = Impacto × Dívida.

Impacto (1–5)

1 = prompt pessoal local
2 = usado por 1 dev
3 = usado pelo time (5+ devs)
4 = staging
5 = produção com users externos

Dívida (1–5)

1 = nenhum anti-pattern
2 = 1 smell menor
3 = 2–3 smells
4 = 4+ smells
5 = usa budget_tokens ou deprecated API

Score ≥ 15: migre esta semana. 10–14: migre este mês. < 10: migre no ciclo trimestral.

📝 Template de auditoria por prompt

# Prompt Audit: [nome]

- **Caminho:** `path/to/file`
- **Tipo:** system | harness | snippet | docs
- **Owner:** @usuário
- **Última edição:** 2025-11-XX
- **Modelo-alvo atual:** claude-3-opus-20240229 ⚠️
- **Usuários/dia:** ~N
- **Impacto:** X/5
- **Dívida:** Y/5
- **Score:** X*Y

## Anti-patterns encontrados
- [ ] "double-check" — linha 42
- [ ] budget_tokens em config — linha 8
- [ ] CAPS LOCK imperatives — linhas 15, 33

## Ação
- [ ] Migrar para claude-opus-4-7
- [ ] Remover scaffolds 4.6
- [ ] Adicionar snippet anti-overengineering
- [ ] Validar com eval antes de merge

## Notas
...

🗂️ Versionamento via git

Todo prompt em arquivo versionado, nunca string literal escondida em código. Isso habilita diff, revert, blame e PR review.

❌ Antes

// app.ts
const system = `You are a helpful...
double-check your answer...
MUST use Read tool first...`;
await claude.messages.create({system, ...});

✓ Depois

// app.ts
import systemPrompt from './prompts/agent-review.md';
await claude.messages.create({
  system: systemPrompt,
  model: 'claude-opus-4-7',
});

// prompts/agent-review.md
# Agent Review v3
Investigate before answering...

🎯 Prioridades: produção > staging > local

Tier	Critério	SLA de migração
Produção	Users externos, revenue impact	Esta sprint
Staging	Time interno, QA	2 semanas
Local	Dev individual, scripts pessoais	Oportunístico

📌 Regra

Nunca toque em local enquanto produção tiver anti-patterns. Energia limitada vai pro maior blast radius primeiro.

📋 Resumo

✓

Inventário completo antes de migrar — git grep + lista por categoria

✓

4 categorias — system, harness, snippet, docs

✓

Score = Impacto × Dívida — prioridade objetiva

✓

Prompts em arquivo versionado — nunca string literal

✓

Produção primeiro — blast radius manda

Próximo Módulo:

4.2 — Os 6 Scaffolds para Aposentar

← Módulo Anterior (3.7)Próximo Módulo →