Puntos clave
- Todo prompt de producción necesita como mínimo una Tarjeta One-Liner (propósito, modelo, fecha, autor)
- Todo prompt modificado necesita un Bloque de Versión (qué cambió, por qué, resultado de prueba)
- Todo prompt probado necesita un Encabezado de Suite de Pruebas (criterios de éxito, ejemplos golden, modos de fallo)
- Almacena la documentación en el mismo sistema que el prompt — los docs separados quedan abandonados
- La justificación del cambio ("por qué") es el campo más importante: los equipos que la omiten vuelven a los patrones anteriores cuando el autor se va
- PromptHub ofrece la estructura de documentación incorporada más completa; Git funciona para equipos de ingeniería con buena disciplina de commits
Por qué los prompts sin documentar rompen los equipos
📍 In One Sentence
Los prompts sin documentar rompen los equipos mediante regresión silenciosa, duplicación y pérdida de conocimiento — cada una prevenible con 5–10 minutos de documentación por prompt.
💬 In Plain Terms
Cuando un prompt no tiene registro de qué hace ni por qué se escribió así, el equipo no puede cambiarlo de forma segura, recuperarlo después de una edición ni entregárselo a un nuevo miembro sin contexto.
Los prompts sin documentar rompen los equipos de tres maneras: regresión silenciosa (sin registro de qué cambió), duplicación (los equipos reescriben prompts existentes porque no los encuentran) y pérdida de conocimiento (los prompts se vuelven imposibles de mantener cuando el autor se va). Cada fallo es prevenible con 5–10 minutos de documentación por prompt.
El fallo más costoso es la regresión silenciosa. Un equipo modifica un prompt de producción para solucionar un problema, inadvertidamente rompe otro, y no tiene un baseline con el que comparar. Sin historial de versiones y un encabezado de suite de pruebas, diagnosticar la regresión requiere comparación manual y suposiciones.
Usa documentación para todo prompt utilizado más de una vez, almacenado en infraestructura compartida o desplegado en producción. Omítela para prompts exploratorios de un solo uso en una única sesión.
⚠️ Riesgo de regresión silenciosa
Sin un Bloque de Versión y ejemplos golden, un equipo que modifica un prompt de producción no tiene baseline. Cada edición es una suposición sobre cuál era el estado anterior.
6 plantillas de documentación de prompts
Seis plantillas cubren el ciclo de vida completo del prompt desde el primer borrador hasta la retirada en producción. Cada plantilla está diseñada para completarse en menos de 10 minutos y proporcionar la información mínima requerida para cada etapa del ciclo de vida.
- 1Tarjeta One-Liner
Why it matters: Propósito: capturar el registro mínimo para cualquier prompt reutilizado. Campos: nombre del prompt, propósito (1 oración), modelo objetivo, fecha de creación, autor. Úsala cuando: un prompt se guarda por primera vez. Almacenamiento: cualquier herramienta compartida (Notion, Git, PromptHub). - 2Bloque de Versión
Why it matters: Propósito: rastrear el historial de prompts que cambian con el tiempo. Campos: número de versión, fecha de modificación, autor, qué cambió (1 oración), razón del cambio (1 oración), resumen del resultado de prueba. Úsalo cuando: se modifica un prompt. Almacenamiento: mensaje de commit de Git o entrada de versión en PromptHub. - 3Encabezado de Suite de Pruebas
Why it matters: Propósito: definir los criterios de aceptación antes de escribir las pruebas. Campos: objetivo de la prueba (qué debe hacer el prompt), criterios de éxito (qué características de salida definen el éxito), ejemplos golden (2–3 pares entrada/salida), modos de fallo conocidos. Úsalo cuando: un prompt entra en la suite de pruebas. Almacenamiento: junto al archivo de prueba en Git o en el proyecto de Braintrust. - 4Registro de Decisiones
Why it matters: Propósito: registrar decisiones de diseño que no son obvias en el texto del prompt. Campos: decisión tomada, alternativas consideradas, razón por la que se eligió esta opción, fecha. Úsalo cuando: se toma una decisión de diseño no obvia (por ejemplo, por qué se estableció una temperatura específica). Almacenamiento: doc enlazado desde el bloque de versión. - 5Justificación de Cambio
Why it matters: Propósito: explicar por qué se cambió un prompt en términos que permitan revertir o replicar el cambio. Campos: descripción del problema (qué estaba mal), cambio realizado, mejora esperada, resultado medido. Úsalo cuando: se modifica un prompt en respuesta a un fallo o regresión. Almacenamiento: cuerpo del commit de Git o nota de cambio en PromptHub. - 6Bloque de Config API
Why it matters: Propósito: registrar los parámetros del modelo utilizados en producción. Campos: modelo (por ejemplo, GPT-4o, Claude 4.6 Sonnet), temperatura, max tokens, top_p, stop sequences, versión del system prompt, versión del user prompt. Úsalo cuando: se despliega un prompt en producción. Almacenamiento: archivo de configuración de despliegue, referenciado en el bloque de versión.
📌 Guía de selección de plantilla
Nuevo prompt → Tarjeta One-Liner. Prompt modificado → Bloque de Versión. Prompt probado → Encabezado de Suite de Pruebas. Decisión de diseño tomada → Registro de Decisiones. Cambiado tras un fallo → Justificación de Cambio. Desplegado en producción → Bloque de Config API.
Dónde almacenar la documentación de prompts
Almacena la documentación de prompts en el mismo sistema que el prompt. Si el prompt vive en código, almacena los docs en Git. Si vive en una herramienta GUI, almacena los docs en las notas de esa herramienta o en un doc enlazado.
- Git: mejor para equipos de ingeniería con prompts almacenados como archivos. Los mensajes de commit sirven como bloques de versión. Gratuito. Requiere disciplina. Sin flujo de trabajo de revisión incorporado.
- PromptHub: gestión de prompts con historial de versiones, firmas de revisores y almacenamiento de resultados de pruebas. $0–$49/mes. Mejor para equipos con 3+ personas escribiendo prompts.
- Notion: funciona para equipos que gestionan prompts como documentos en lugar de código. Fácil de configurar. Carece de control de versiones e integración de pruebas — trátalo como capa de documentación, no como fuente de verdad.
- Braintrust: almacena encabezados de suite de pruebas y resultados de evaluación junto a las versiones del prompt. Mejor para equipos que ejecutan evaluaciones automatizadas regulares.
- PromptQuorum: plataforma de optimización de prompts para despachar prompts documentados a más de 25 proveedores de IA simultáneamente. Úsala para validar que los prompts documentados generalizan entre modelos antes de confirmar una versión. Nivel gratuito.
💡 Co-localiza la documentación
La documentación almacenada en un sistema separado (Notion, Confluence, Google Docs) del prompt quedará obsoleta en días. La única documentación que se mantiene actualizada es la que vive con el prompt.
Errores comunes de documentación
❌ Sin documentación en absoluto
Why it hurts: Los prompts no pueden recuperarse tras ediciones, el equipo no puede entender por qué se escribió un prompt de cierta manera
Fix: Usa como mínimo la plantilla Tarjeta One-Liner — 3 campos, menos de 2 minutos
❌ Documentación almacenada por separado del prompt
Why it hurts: La documentación queda obsoleta a medida que cambian los prompts; los equipos olvidan actualizarla
Fix: Almacena la documentación en el mismo archivo o commit de Git que el prompt
❌ Campo "por qué" ausente — solo describe qué hace el prompt
Why it hurts: Los editores futuros no conocen las restricciones, no pueden refactorizar de forma segura
Fix: Añade un campo "justificación" a cada plantilla: 1-2 oraciones sobre por qué se eligió esta estructura
❌ Sin bloque de versión
Why it hurts: Sin forma de saber si el prompt que corre en producción coincide con la versión documentada
Fix: Añade versión y dateModified a cada archivo de prompt de producción
Preguntas frecuentes
¿Por qué los prompts necesitan documentación?
Los prompts sin documentación no pueden revisarse, auditarse ni reproducirse. Cuando el autor cambia el prompt y no deja ningún registro, el equipo no puede diagnosticar regresiones, no puede volver a una versión conocida como buena ni puede incorporar a nuevos miembros.
¿Cuál es la documentación mínima que necesita un prompt?
El mínimo es una tarjeta one-liner: propósito del prompt (una oración), modelo objetivo, fecha de creación y autor. Esto tarda 2 minutos en escribirse y previene el fallo de documentación más común — prompts cuyo propósito es desconocido 6 meses después.
¿Dónde debe almacenarse la documentación de prompts?
Almacena la documentación de prompts en la misma ubicación que el prompt. Git funciona para prompts almacenados como archivos de código. PromptHub proporciona almacenamiento estructurado con historial de versiones y firmas de revisores incorporadas. Notion funciona para equipos que gestionan prompts como documentos, pero carece de control de versiones.
¿Qué tan detallada debe ser una justificación de cambio?
Tres líneas: qué cambió (una oración), por qué (el problema que resuelve el cambio) y qué prueba confirmó que funcionó. Los equipos que omiten el "por qué" invariablemente vuelven al patrón anterior cuando el autor se va.
¿Qué plantilla debo usar para un nuevo prompt?
Comienza con la Tarjeta One-Liner. Si el prompt va a producción, actualiza a un Bloque de Versión. Si tiene múltiples casos de prueba, añade un Encabezado de Suite de Pruebas. Si requirió una decisión de diseño no obvia, añade un Registro de Decisiones.
¿Con qué frecuencia debo actualizar la documentación de prompts?
Actualiza cada vez que cambie el texto del prompt. Añade un incremento de versión y una entrada de Justificación de Cambio para cada edición sustancial. No actualices la documentación de forma retroactiva.
¿Puedo usar estas plantillas en PromptHub?
Sí. PromptHub almacena campos de metadatos de prompts que se mapean directamente a las plantillas de Bloque de Versión y Bloque de Config API. Usa la plantilla como borrador y luego copia los campos a PromptHub cuando estés listo para compartirlo con tu equipo.