Manutenção de biblioteca de prompts Claude Code para equipes

Prompt bom não deve ficar só no histórico

Equipes começam no Claude Code de forma informal. Um prompt útil fica no Slack, outro no comentário de PR, outro em nota pessoal e outro no Notion. Por alguns dias isso funciona. Depois surgem cinco versões, ninguém sabe qual foi aprovada, e cada revisão volta a começar do zero.

Uma biblioteca de prompts não é uma pasta de frases. É um ativo operacional. Ela precisa de versionamento, owner, review gate, regra de depreciação e métricas. A Claude Code Prompt library oficial oferece bons padrões, mas a equipe precisa ligar esses padrões ao próprio repositório, páginas de produto, preços, CTAs e treinamento. Também vale consultar a documentação de CLAUDE.md e memory, Skills, Subagents e Hooks.

Este artigo continua o checklist de review Claude Code e o checklist dos primeiros 30 minutos. O foco é ajudar times a transformar prompts reutilizáveis em templates pagos, material de treinamento e processos de consultoria.

Comece por um registro

Versionamento mostra como o prompt mudou. Owner define quem responde por ele. Review gate é a passagem obrigatória antes do uso oficial. Depreciação retira uma versão antiga sem quebrar a rotina dos outros. Métricas mostram se o prompt reduz risco, melhora conversão ou economiza tempo.

Salve este exemplo como prompt-library.json.

[
  {
    "id": "review-risk-finder",
    "version": "1.2.0",
    "owner": "platform",
    "status": "active",
    "useWhen": "A pull request changes behavior, data flow, pricing, or CTA routing.",
    "inputs": ["goal", "diff", "riskAreas", "expectedTests"],
    "output": "Findings ordered by severity with evidence and smallest fix.",
    "reviewGate": "Owner approval plus one successful run on a known risky diff.",
    "deprecates": ["review-risk-finder@1.1.0"],
    "metrics": ["reuse_count", "accepted_findings", "false_positive_rate"],
    "officialDocs": [
      "https://code.claude.com/docs/en/prompt-library",
      "https://code.claude.com/docs/en/memory"
    ]
  }
]

O registro não melhora sozinho o texto, mas torna o prompt governável. Se a saída gerar ruído, existe um owner. Se a página de produto mudar, o time decide se o prompt de CTA precisa de versão minor. Se entrar em um workshop, o instrutor sabe qual versão está sendo ensinada.

Um template, um resultado

O erro caro é pedir review, testes, documentação, refatoração e melhoria de CTA em uma única instrução. Parece eficiente, mas mistura responsabilidades e esconde falhas. Em uma biblioteca de equipe, cada prompt deve entregar um artefato claro.

# review-risk-finder

You are reviewing a production change for business and user risk.

Context:
- Goal: {{goal}}
- Diff or changed files: {{diff}}
- Risk areas: {{riskAreas}}
- Expected tests: {{expectedTests}}

Return findings first. For each finding include:
1. Severity
2. Evidence from the diff
3. User or revenue impact
4. Smallest safe fix
5. Verification command

If there are no findings, list what you checked and what remains unverified.

Esse formato define o que é risco e qual prova deve voltar. Engenharia avalia o comando de verificação. Produto avalia impacto em receita. A pessoa de treinamento transforma a mesma estrutura em exercício de adoção.

Use case: três fluxos ligados a receita

Use case 1 é review de pull request. Em vez de pedir “procure problemas”, envie objetivo, diff, testes esperados e áreas de risco como cobrança, autenticação, permissões, exclusão de dados ou roteamento de CTA. A resposta vira finding acionável.

Use case 2 é manutenção de página de produto. Mesmo que o conteúdo em português aponte para products, o prompt deve checar promessa, público, resultado após compra, linguagem de preço, prova e links. O owner costuma ser produto ou marketing, não só engenharia.

Use case 3 é treinamento e consultoria. Para training, o prompt deve levantar dor do time, maturidade do fluxo atual, riscos de adoção do Claude Code e materiais que ficarão depois do workshop. A métrica não é apenas tráfego, mas consultas qualificadas.

Use case 4 é atualização editorial. Artigos publicados envelhecem quando docs oficiais, comandos, links internos e exemplos mudam. Um prompt de refresh verifica official links, updatedDate, exemplos executáveis, imagens e a seção de experiência real.

Gates antes do status active

Três estados bastam: draft, active e deprecated. Draft é testado. Active pode entrar em documentação, produtos e treinamento. Deprecated fica visível com caminho de migração.

Use versionamento semântico de modo prático. Mudança que quebra formato de saída sobe major. Novo input sobe minor. Ajustes de texto ou exemplos sobem patch. O objetivo é evitar que alguém dependa de comportamento antigo achando que está usando a versão atual.

flowchart LR
  Draft["draft prompt"] --> Owner["owner review"]
  Owner --> Gate["known-risk gate"]
  Gate --> Active["active library"]
  Active --> Metrics["monthly metrics"]
  Metrics --> Deprecate["deprecate or improve"]

O known-risk gate é a prova com falha real. Guarde um diff arriscado que passou, um CTA quebrado, um log em que o primeiro erro ficou escondido ou um artigo que manteve link oficial antigo. Se o prompt não lida com esse caso, não está pronto.

Agents com escopo claro

Um agent é útil quando a tarefa é estreita e o resultado pode ser resumido. Subagents oficiais trabalham em contexto próprio; por isso a delegação precisa ser precisa. Para a biblioteca, separe librarian para metadados, reviewer para testar saídas e owner para aprovar.

Exemplo para .claude/agents/prompt-librarian.md:

---
name: prompt-librarian
description: Maintains prompt library metadata, ownership, versions, metrics, and deprecation notes.
tools: Read, Grep
---

You audit prompt library entries. Do not rewrite product copy.
Check that each prompt has id, version, owner, status, useWhen, inputs, output,
reviewGate, deprecation note, and metrics. Report missing fields first.

Esse agent deve ler e auditar, não reescrever CTA ou copy de produto sem revisão. Regras que precisam bloquear ações devem ficar em Hooks, permissões ou CI. Prompt guia julgamento; gate aplica regra.

Pitfall: onde a biblioteca se degrada

Pitfall 1 são nomes vagos. good-review, debug-helper e marketing-check não ajudam depois de um mês. Prefira checkout-cta-risk-review, build-log-first-failure ou training-page-objection-check.

Pitfall 2 é guardar só sucesso. Casos positivos escondem limites. Guarde uma entrada ruim e uma nota concreta: “perdeu link de preço antigo” ou “olhou nomes de testes, não implementação”.

Pitfall 3 é colocar tudo no CLAUDE.md. Ele é contexto valioso, mas não política dura. Para bloquear, use Hooks, permissões ou CI.

Pitfall 4 é acrescentar CTA no final. Produto e treinamento precisam fazer parte do caminho desde o começo: conteúdo grátis, template para quem quer velocidade, training para times que precisam governança.

Script mínimo de auditoria

Depois de dez entradas, automatize o básico.

import fs from "node:fs";

const file = process.argv[2] ?? "prompt-library.json";
const entries = JSON.parse(fs.readFileSync(file, "utf8"));
const required = [
  "id",
  "version",
  "owner",
  "status",
  "useWhen",
  "inputs",
  "output",
  "reviewGate",
  "metrics"
];

let failed = false;
for (const entry of entries) {
  const missing = required.filter((key) => !entry[key]);
  if (!/^\\d+\\.\\d+\\.\\d+$/.test(entry.version ?? "")) {
    missing.push("version must be semver");
  }
  if (!["draft", "active", "deprecated"].includes(entry.status)) {
    missing.push("status must be draft, active, or deprecated");
  }
  if (missing.length > 0) {
    failed = true;
    console.error(`${entry.id ?? "(missing id)"}: ${missing.join(", ")}`);
  }
}

if (failed) process.exit(1);
console.log(`OK: ${entries.length} prompt entries checked`);

O script não julga estilo, mas impede prompts sem owner, versão ou reviewGate de entrar em materiais pagos.

Poucas métricas, decisões reais

Métrica	Por que importa	Ação
reuse_count	Mostra se o time encontra o prompt	Renomear ou mover
accepted_findings	Mostra se gera correções reais	Apertar formato de saída
false_positive_rate	Mostra se desperdiça tempo	Especificar riskAreas
time_to_fix_minutes	Mostra se reduz tempo de correção	Exigir smallest safe fix
cta_click_rate	Mostra impacto em produto e training	Rever contexto e posição

Uma revisão mensal basta. Prompt sem uso, sem confiança ou sem decisão associada deve ser depreciado.

Conectar produtos e treinamento

Uma biblioteca bem mantida cria uma escada comercial clara. Artigos gratuitos ensinam o raciocínio. ClaudeCodeLab products entrega templates para quem quer avançar sozinho. Claude Code training and consultation ajuda equipes a adaptar owner, gates, hooks, métricas e rollout ao repositório real.

Masa primeiro tentou manter mais de trinta prompts. Parecia completo, mas aumentou o tempo de escolha. A versão útil ficou em quatro categorias: review, debug, product page e training page, com até três prompts active em cada uma. Os exemplos de falha guardados foram o que mais melhorou as versões seguintes.