Mantenimiento de una biblioteca de prompts de Claude Code para equipos

Un prompt útil no debería vivir solo en el historial

Los equipos empiezan con Claude Code de forma informal: un prompt bueno queda en Slack, otro en un comentario de PR, otro en una nota personal y otro en una página de Notion. Durante unos días funciona. Después aparecen cinco variantes, nadie sabe cuál está aprobada y cada revisión vuelve a empezar desde cero.

Una biblioteca de prompts no es una carpeta de frases. Es un activo operativo. Necesita versionado, propietario, review gate, reglas de deprecación y métricas. La Claude Code Prompt library oficial sirve como referencia de patrones; el equipo debe añadir su contexto de repositorio, producto, precios, CTA y formación. También conviene revisar la documentación oficial de CLAUDE.md y memory, Skills, Subagents y Hooks.

Este artículo continúa el checklist de review de Claude Code y el checklist de los primeros 30 minutos. El objetivo es que un equipo convierta instrucciones repetibles en plantillas vendibles, material de entrenamiento y procesos de consultoría.

Empieza con un registro

Versionado significa saber cómo cambió un prompt. Owner significa que una persona o función responde por él. Review gate es la prueba que debe pasar antes de entrar en uso. Deprecación es retirar una versión antigua sin romper el trabajo de otros. Métricas significa observar si el prompt reduce riesgo, mejora conversión o ahorra tiempo.

Puedes guardar este ejemplo 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"
    ]
  }
]

El registro no mejora mágicamente el texto, pero evita que la biblioteca se vuelva invisible. Si el prompt genera ruido, el owner lo corrige. Si cambia la página de producto, el equipo decide si la revisión de CTA necesita una versión menor. Si se entrega en un taller, el formador sabe qué versión está enseñando.

Un template, un resultado

El error caro es pedir demasiadas cosas en una sola instrucción: review, tests, documentación, refactor y mejora de CTA. Suena eficiente, pero mezcla responsabilidades y hace ilegible el fallo. En una biblioteca de equipo, cada prompt debe producir un artefacto 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.

Este formato define qué cuenta como riesgo y qué evidencia debe devolver Claude Code. Ingeniería puede revisar el comando de verificación. Producto puede juzgar el impacto en ingresos. La persona responsable de formación puede convertir el mismo patrón en un ejercicio para el equipo.

Use case: tres flujos ligados a ingresos

Use case 1: revisión de pull requests. En vez de decir “busca problemas”, pasa objetivo, diff, pruebas esperadas y áreas de riesgo como pagos, permisos, autenticación, borrado de datos o routing de CTA. El resultado deja de ser consejo genérico y se convierte en hallazgos accionables.

Use case 2: mantenimiento de páginas de producto. Aunque el sitio en español use la página de products en inglés, el prompt debe comprobar promesa, público objetivo, expectativa de compra, lenguaje de precio, prueba social y enlaces. El owner aquí suele ser producto o marketing, no solo ingeniería.

Use case 3: formación y consultoría. Para una página de training, el prompt debe detectar dolor del equipo, madurez del flujo actual, riesgos de adopción de Claude Code y activos que quedarán después del workshop. La métrica no es solo tráfico: son consultas cualificadas y menos preguntas repetidas.

Use case 4: actualización editorial. Los artículos publicados envejecen cuando cambian docs oficiales, comandos, enlaces internos o productos. Un prompt de refresh revisa official links, updatedDate, ejemplos ejecutables, imágenes y la sección de experiencia real.

Puertas de revisión antes de activar

Tres estados bastan: draft, active y deprecated. Draft se prueba, active se puede usar en docs, productos y formación, deprecated conserva el camino de migración.

Usa versionado semántico de forma práctica. Un cambio que rompe el formato de salida sube major. Un nuevo input sube minor. Correcciones de redacción o ejemplos suben patch. La meta es que nadie dependa de un comportamiento antiguo pensando que usa la versión actual.

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"]

El known-risk gate es una prueba con un fallo real: un diff que antes se escapó, un CTA roto, un log donde el primer error estaba oculto o un artículo que mantuvo una URL oficial antigua. Si el prompt no detecta ese caso, todavía no está listo.

Define bien el papel de los agents

Un agent es útil cuando tiene una tarea estrecha y puede devolver un resumen. Los subagents oficiales trabajan en su propio contexto, por eso conviene no darles tareas ambiguas. Para una biblioteca de prompts, separa tres papeles: librarian para metadatos, reviewer para probar salidas y owner para aprobar.

Ejemplo 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.

Este agent debería leer y auditar, no reescribir CTAs ni páginas de venta. Si una regla debe bloquearse, pásala a Hooks, permisos o CI. El prompt guía el juicio; la puerta aplica la política.

Pitfall: dónde se degrada la biblioteca

Pitfall 1: nombres vagos. good-review, debug-helper y marketing-check no se encuentran después de un mes. Usa nombres con objetivo y resultado, como checkout-cta-risk-review o build-log-first-failure.

Pitfall 2: guardar solo éxitos. Los casos positivos hacen que el prompt parezca más fuerte de lo que es. Guarda al menos una entrada fallida y una nota concreta: “omitió enlace de precio antiguo” o “miró nombres de tests, no implementación”.

Pitfall 3: meter todo en CLAUDE.md. Es un contexto valioso, pero no una política dura. Para bloquear acciones, usa Hooks, permisos o CI.

Pitfall 4: añadir la venta al final. Un CTA pegado después de escribir el artículo parece anuncio. Diseña desde el principio el camino: contenido gratis, producto para quien quiere plantillas y training para equipos que necesitan gobernanza.

Script mínimo de auditoría

Cuando la biblioteca supera diez entradas, automatiza lo 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`);

No evalúa la calidad narrativa, pero impide que prompts sin owner, versión o gate entren en materiales pagados.

Métricas pequeñas, decisiones claras

Métrica	Por qué importa	Acción
reuse_count	Muestra si el equipo lo encuentra	Cambiar nombre o ubicación
accepted_findings	Muestra si genera correcciones reales	Ajustar formato de salida
false_positive_rate	Muestra si desperdicia tiempo	Concretar riskAreas
time_to_fix_minutes	Muestra si reduce el tamaño del arreglo	Exigir smallest safe fix
cta_click_rate	Muestra si mejora producto o training	Revisar contexto y posición

Revisa una vez al mes. Si un prompt no se usa, no se confía o no informa una decisión, deprecarlo es mejor que dejarlo crecer.

Conectar con productos y training

Una biblioteca mantenida crea una escalera comercial clara. Los artículos gratuitos enseñan el razonamiento. ClaudeCodeLab products ofrece plantillas para quien quiere avanzar rápido. Claude Code training and consultation ayuda a equipos a diseñar owner, gates, hooks, métricas y rollout en un repositorio real.

Masa probó primero una biblioteca de más de treinta prompts y el resultado fue peor: demasiada elección y poca responsabilidad. Al reducirla a review, debug, product page y training page, con tres prompts activos por categoría, el equipo eligió más rápido. Los casos fallidos guardados dieron la materia prima para mejorar cada versión.