Prompts para Claude Code/Codex: 5 patrones prácticos para principiantes

Empieza aquí: un buen prompt es un brief de trabajo claro

Cuando Claude Code o Codex devuelve una respuesta desordenada, el problema muchas veces no es que el agente “no sepa programar”. El prompt no le dio suficientes límites de trabajo. Un prompt no es una frase mágica. Es un brief para un agente de programación: qué cambiar, qué no tocar, qué significa terminado, qué evidencia de verificación debe reunir y qué debe saber la siguiente persona.

Esta guía para principiantes convierte esa idea en 5 patrones prácticos: alcance, contexto del repositorio, criterios de aceptación, evidencia de verificación y traspaso. Puedes usarlos para corregir bugs, añadir funciones pequeñas, generar artículos, auditar un repositorio o revisar código. El objetivo no es sonar sofisticado. El objetivo es reducir la adivinación.

Para referencias oficiales, mantén cerca la documentación del producto. Empieza por Claude Code overview, Claude Code memory y Claude Code settings. Para Codex y flujos de código con OpenAI, consulta la OpenAI code generation guide. Si todavía estás empezando con la herramienta, lee también la guía inicial de Claude Code y las buenas prácticas de CLAUDE.md.

Los 5 patrones

Patrón	Significado simple	Qué pasa si falta
Alcance	El límite de la tarea	El agente modifica archivos no relacionados
Contexto del repo	Reglas y ejemplos existentes	El resultado no sigue las convenciones locales
Criterios de aceptación	Definición de terminado	“Terminado” significa cosas distintas
Evidencia de verificación	Prueba de que se revisó	El trabajo acaba en “lo implementé”
Traspaso	Nota breve para la siguiente sesión	Nadie recuerda por qué se cambió algo

Los criterios de aceptación son condiciones concretas que deben cumplirse antes de aceptar el cambio. La evidencia de verificación es el recibo: comandos ejecutados, pantallas revisadas, pruebas manuales o limitaciones declaradas. El traspaso ayuda a que tu yo de mañana, un compañero o un nuevo agente continúe sin releer toda la conversación.

Patrón 1: define un alcance estrecho

Un prompt débil empieza demasiado amplio.

Mejora esta app y déjala mejor.

Ese prompt no dice si el agente puede tocar UI, API, tests, copy, esquema de base de datos, dependencias o despliegue. Claude Code y Codex pueden inferir, pero cada inferencia aumenta el riesgo.

Usa algo así:

Edita solo site/src/content/blog-es/5-tips-for-better-prompts.mdx.
Objetivo: hacer el artículo más práctico para principiantes de Claude Code/Codex.

Permitido:
- title, description, updatedDate y tags en frontmatter
- cuerpo del artículo

No cambiar:
- heroImage
- slug
- otros artículos
- configuración de build

Esto es vital en sitios monetizados. Una reescritura amplia puede borrar enlaces internos, CTA de productos o atributos de analítica. Un alcance claro da libertad para trabajar sin convertir una mejora de artículo en una refactorización global.

Para tareas de exploración, el límite debe ser aún más explícito:

Lee los archivos relacionados y propón solo un plan. No edites todavía.
Lista los archivos que cambiarías, por qué y el comando de verificación para cada cambio.

El fallo típico es pedir “solo revisa” mientras se permite editar. Separa descubrimiento e implementación cuando no conoces bien el repositorio.

Patrón 2: entrega contexto del repositorio

Claude Code/Codex puede leer archivos, pero no conoce automáticamente tu prioridad comercial, decisiones de estilo o errores pasados. El contexto del repositorio le dice en qué proyecto está trabajando.

Este sitio usa Astro content collections para artículos MDX localizados.
Usa site/src/content/blog-es/claude-code-productivity-tips.mdx como referencia de calidad.

Contexto del proyecto:
- Los artículos deben ser tutoriales evergreen prácticos, no resúmenes finos de IA.
- Incluye 3 o más casos de uso concretos.
- Incluye enlaces oficiales externos y enlaces internos.
- Conserva la ruta de conversión: /es/thanks/, /en/products/, /en/training/.
- Mantén frontmatter válido.

Sin este contexto puedes recibir un artículo limpio, pero que no encaja con ClaudeCodeLab. Aquí importan los prompts copiables, ejemplos de fallo, hábitos de verificación y un siguiente paso natural hacia cheatsheet, productos o training.

Si repites el mismo contexto a menudo, mueve la parte estable a CLAUDE.md. En consejos de productividad con Claude Code verás cómo las reglas del proyecto, comandos seguros y verificación reducen la explicación repetida.

Patrón 3: escribe criterios de aceptación antes de empezar

Los criterios de aceptación evitan el bucle de “hazlo mejor”. Un prompt débil sería:

Haz este artículo más legible y mejor para SEO.

Legibilidad y SEO importan, pero así no son suficientemente comprobables. Divídelos en condiciones:

Criterios de aceptación:
- Solo se modifica el archivo objetivo.
- La description tiene 120 caracteres o menos.
- Cada uno de los 5 patrones incluye un ejemplo Before/After.
- Hay plantillas para bugfix, nueva función y generación de artículo.
- Hay fallos concretos y cómo evitarlos.
- Se añaden enlaces oficiales, enlaces internos y una CTA clara.
- Al final se reportan verificación y riesgos restantes.

Para una función, los criterios deben ser más técnicos:

Criterios de aceptación:
- Se conserva el layout UI existente.
- No hay errores de TypeScript.
- Se añaden validación y estados de error visibles.
- Se añade o actualiza al menos un test relevante.
- Se reporta el resultado de npm test y npm run build.

La clave es que cada punto pueda comprobarse. Si el agente no puede probarlo, debe decirlo en lugar de fingir que todo está verificado.

Patrón 4: pide evidencia de verificación

“Implementado” no basta. Pide un verification receipt.

Al final, devuelve un verification receipt:

- Archivos modificados:
- Comandos ejecutados:
- Resultados:
- Revisiones manuales:
- No verificado:
- Riesgos restantes:

Este hábito captura muchos errores de principiante. También obliga al agente a ser claro cuando no puede ejecutar un comando porque faltan dependencias, el test suite tarda demasiado o un servicio local no está disponible. Entonces tú decides si el riesgo es aceptable.

No resumas demasiado los errores. Esto es débil:

El build falló. Arréglalo.

Esto sirve:

Comando:
npm run build

Error:
Type error: Property 'name' does not exist on type 'User | undefined'.
File: src/components/Profile.tsx:15:22

Solicitud:
Explica la causa probable, haz la corrección mínima segura y vuelve a ejecutar npm run build.

Para una rutina más completa, lee la guía de verification receipt. El formato puede cambiar, pero el principio no: no cierres una tarea sin pruebas.

Patrón 5: solicita una nota de traspaso

El trabajo con agentes suele durar más de una sesión. Una nota de traspaso evita redescubrir todo.

Al final, escribe una handoff note con:
- Objetivo
- Qué cambió
- Qué no cambió
- Resultados de verificación
- Archivos a revisar después
- Riesgos o decisiones abiertas

Esto ayuda en artículos, SEO, checkout flows y repositorios de equipo. Un diff muestra qué cambió, pero rara vez explica por qué una CTA quedó en una sección concreta o por qué se eligió una corrección pequeña en lugar de una refactorización grande.

Para equipos, combínalo con reglas de traspaso para Claude Code. Un formato constante hace que las sesiones con IA sean revisables.

Plantillas copiables

Plantilla para bugfix

Objetivo:
  Corregir el bug con el diff seguro más pequeño.

Síntoma:
  Qué ocurre:
  Comportamiento esperado:
  Comportamiento real:

Pasos de reproducción:
  1.
  2.
  3.

Alcance:
  Archivos que puedes editar:
  Archivos que no debes editar:

Contexto del repositorio:
  Implementación similar a seguir:
  Reglas locales a preservar:

Criterios de aceptación:
  Explicar causas probables antes de editar.
  Corregir la causa raíz, no solo ocultar el síntoma.
  Añadir o actualizar un test relevante si es posible.
  Devolver evidencia de verificación y riesgo restante.

Plantilla para nueva función

Objetivo:
  Añadir una función pequeña de forma segura.

Función:
  Cambio visible para el usuario:
  Cambios en API/base de datos/configuración:

Restricciones:
  Preservar el estilo UI existente.
  Seguir los patrones actuales de nombres y archivos.
  Si hace falta un cambio de diseño mayor, explicarlo antes de implementar.

Criterios de aceptación:
  Incluir implementación, tipos, estados de error, tests y verification receipt.

Plantilla para generar o reescribir un artículo

Objetivo:
  Convertir esto en un artículo evergreen para principiantes.

Lector:
  Desarrollador individual o equipo pequeño que empieza con Claude Code/Codex.

Elementos obligatorios:
  3 o más casos de uso concretos.
  Ejemplos de prompts Before/After.
  Fallos específicos y soluciones.
  Plantillas copiables.
  Enlaces oficiales, enlaces internos y CTA.

Criterios de aceptación:
  Description de 120 caracteres o menos.
  Frontmatter válido.
  Code fences balanceados.
  Cierre con una breve autoevaluación.

Tres casos de uso reales

El primer caso es una pantalla en blanco después del login. No digas “arregla el dashboard”. Entrega pasos de reproducción, resultado esperado, error real de consola, archivos editables y comandos de verificación. Así el agente se acerca a la causa raíz en lugar de esconder el síntoma.

El segundo caso es añadir un campo “tipo de consulta” a un formulario de leads. Un buen prompt nombra opciones como training, consulting y other; la regla de validación; el contrato de API; el evento de analítica; y el test esperado. Esto protege la ruta de monetización mientras el diff sigue pequeño.

El tercer caso es generación de artículos. Para ClaudeCodeLab, el prompt debe especificar profundidad, ejemplos concretos, fallos, enlaces oficiales, enlaces internos, CTA y un párrafo final sobre el resultado de probar el flujo. Así evitas un resumen genérico de IA y produces algo útil.

Rúbrica rápida para revisar prompts

Antes de enviar un prompt, puntúalo sobre 10.

Puntos	Área	Pregunta
0-2	Alcance	¿Están claros los archivos editables y protegidos?
0-2	Contexto	¿Incluí ejemplos locales, lector y propósito de negocio?
0-2	Aceptación	¿El agente puede saber cuándo terminó?
0-2	Verificación	¿Nombré comandos o revisiones manuales?
0-2	Traspaso	¿Definí qué debe reportar al final?

Ocho puntos o más suele estar listo. Cinco o menos significa que estás pidiendo al agente compensar contexto humano faltante.

Generador ejecutable de brief

En vez de pedir “mejóralo”, conviene crear siempre el mismo tipo de brief. Este script genera prompt-brief.md; cambia la ruta y los criterios de aceptación antes de pasarlo a Claude Code o Codex para que el alcance, las restricciones y la verificación queden claros desde el primer turno.

cat > prompt-brief.md <<'EOF'
# Task brief for Claude Code / Codex

Goal:
- Improve one article or feature without changing unrelated files.

Scope:
- May edit: site/src/content/blog/example.mdx
- Do not edit: hero images, routes, unrelated articles, billing code.

Context to read first:
- AGENTS.md
- A similar high-quality article
- The target file

Acceptance criteria:
- The intro explains who the reader is and why this matters.
- The draft includes at least three concrete examples.
- Code or prompt templates are copy-pasteable.
- Pitfalls and verification steps are explicit.
- Internal links and a natural CTA are included.

Verification:
- npm run build
- node scripts/check-code-fences.mjs
- Read the changed file once as a reviewer.

Return:
- What changed
- Checks run
- Remaining risks
EOF

CTA: convierte el patrón en tu flujo

No necesitas reescribir estas reglas cada día. Empieza con el cheatsheet gratuito de Claude Code para comandos diarios y hábitos seguros. Si quieres packs de prompts y material de setup listo para usar, revisa ClaudeCodeLab products. Si tu equipo necesita ayuda con CLAUDE.md, permisos, política de review, verification receipts y rollout, visita Claude Code training and consultation.

Después de usar este flujo en tareas reales de artículos y sitio de ClaudeCodeLab, la mayor mejora vino de escribir alcance, criterios de aceptación y evidencia de verificación antes de pedir ediciones. Las notas de traspaso también redujeron el tiempo de review al día siguiente, porque seguía visible la razón de cada CTA y enlace.