Prompt engineering avanzado para Claude Code y Codex: briefs de tarea que sí se pueden revisar

Cuando Claude Code o Codex produce resultados irregulares, el problema muchas veces no es el modelo. Suele ser la forma en que le entregamos el trabajo. El prompt engineering avanzado no consiste en encontrar una frase mágica. Consiste en diseñar un flujo: objetivo, alcance, contexto, restricciones, criterios de aceptación, verificación y traspaso.

Esta guía muestra cómo crear un “paquete de prompt” reutilizable para Claude Code y Codex. Un principiante puede copiar las plantillas, pero el diseño también sirve para equipos, repositorios reales, trabajo en paralelo, código de producción y artículos publicados. Si necesitas la base, lee primero 5 consejos para mejores prompts y buenas prácticas de CLAUDE.md.

El comportamiento de las herramientas cambia, así que las afirmaciones sobre funciones deben apoyarse en documentación oficial. Para Claude Code, empieza por Claude Code overview, Memory y prompt engineering overview. Para Codex, usa OpenAI Codex docs y AGENTS.md guidance.

Avanzado significa contrato de trabajo

Un prompt débil no solo es corto. No tiene reglas de decisión, no dice qué archivos no se deben tocar, no define qué significa terminar y no pide evidencia. Con esos huecos, el agente adivina.

Un prompt práctico debe funcionar como un contrato pequeño.

Parte	Qué escribir	Falla si falta
Goal	Resultado esperado	La respuesta parece buena, pero resuelve otra cosa
Scope	Qué se puede y no se puede cambiar	Entran refactors no relacionados
Context	Documentos, código similar, fuentes oficiales	Copia patrones viejos o inventa comportamiento
Constraints	Reglas y cambios prohibidos	Cambian dependencias, APIs o tono sin querer
Acceptance criteria	Cómo juzgar el trabajo	La revisión depende del gusto
Verification	Comandos y checks manuales	El trabajo termina sin pruebas

La guía de Anthropic sobre prompt engineering parte de criterios de éxito y pruebas empíricas. En agentes de código esto pesa más, porque Claude Code y Codex pueden leer archivos, editarlos, ejecutar comandos y dejar un diff que parece terminado antes de estar verificado.

Guarda el paquete de prompt en un archivo

Escribir una instrucción larga en el chat cada vez es difícil de revisar y de repetir. Un archivo como prompt-packet.md convierte la petición en un artefacto reutilizable. Este snippet de Bash crea una base mínima.

cat > prompt-packet.md <<'EOF'
# Goal
Improve one published article so it is practical, accurate, and ready for review.

# Scope
May edit:
- site/src/content/blog/example-article.mdx

Do not edit:
- heroImage
- slug
- unrelated articles
- package or deployment files

# Context to read
- AGENTS.md
- site/src/content/blog/claude-md-best-practices.mdx
- Official docs relevant to the article topic

# Constraints
- Preserve existing frontmatter keys unless this task explicitly changes them.
- Use copy-pasteable examples, not pseudocode.
- Avoid unsupported claims. Link to official docs for tool behavior.
- Keep paragraphs short enough for mobile reading.

# Acceptance criteria
- updatedDate is 2026-06-02.
- The article has at least three concrete use cases.
- The article names specific pitfalls and how to avoid them.
- The article includes an internal link, an official external link, and a natural CTA.
- The final section explains what was actually verified.

# Verification
- node scripts/check-code-fences.mjs
- node scripts/check-updated-article-quality.mjs
- Read the diff once as a critical reviewer.

# Return format
- Changed files
- Key improvements
- Checks run
- Residual risks
EOF

Al usarlo, di: “Lee primero prompt-packet.md, revisa el archivo objetivo y el contexto listado, y trabaja solo dentro del Scope.” No es burocracia. Evita el fallo típico en el que el agente intenta ayudar cambiando páginas vecinas, imágenes, configuración o código que no forma parte de la tarea.

Revisa el prompt antes de usarlo

Los prompts son texto natural, así que la calidad puede variar. Un verificador pequeño detecta estructura incompleta antes de entregar la tarea. Guárdalo como check-prompt-packet.cjs.

// save as check-prompt-packet.cjs
const fs = require("node:fs");

const file = process.argv[2] || "prompt-packet.md";
const text = fs.readFileSync(file, "utf8");

const required = [
  "# Goal",
  "# Scope",
  "# Context to read",
  "# Acceptance criteria",
  "# Verification",
  "# Return format",
];

const missing = required.filter((heading) => !text.includes(heading));
const hasDoNotTouch = /do not (edit|change|touch)/i.test(text);
const hasCommand = /npm run|npm test|pnpm |yarn |node scripts\//i.test(text);

if (missing.length || !hasDoNotTouch || !hasCommand) {
  console.error("Prompt packet is not ready.");
  if (missing.length) console.error("Missing headings: " + missing.join(", "));
  if (!hasDoNotTouch) console.error("Add an explicit do-not-touch boundary.");
  if (!hasCommand) console.error("Add at least one verification command.");
  process.exit(1);
}

console.log("Prompt packet looks actionable.");

Ejecútalo así:

node check-prompt-packet.cjs prompt-packet.md

Es simple, pero funciona. En la operación de artículos de Masa, los errores más comunes aparecían cuando faltaba el límite de “no tocar” o la prueba final. En código de producto pasa lo mismo: si la petición no define terminado, la revisión se vuelve subjetiva.

Convierte deseos vagos en criterios de aceptación

“Mejóralo”, “hazlo más SEO” y “déjalo listo para producción” son intenciones válidas, pero no son verificables. Convierte esas frases en checks que puedan pasar o fallar.

Prompt débil:

Mejora este artículo y fortalece el SEO.

Prompt útil:

Reescribe el artículo como una guía práctica para desarrolladores que empiezan con Claude Code.

Acceptance criteria:
- El título incluye "Claude Code" y "prompt engineering".
- La description tiene menos de 120 caracteres.
- El cuerpo incluye al menos tres casos de uso concretos.
- Hay al menos dos malos ejemplos de prompt y dos versiones mejoradas.
- El artículo enlaza documentación oficial y artículos internos relacionados.
- La sección final dice qué se verificó realmente.
- Ejecuta el check de code fences después de editar y reporta el resultado.

Para implementación, usa criterios técnicos.

Acceptance criteria:
- No cambiar el tipo de la API pública.
- Agregar validación y errores visibles para el usuario.
- Agregar o actualizar al menos una prueba de ruta fallida.
- Ejecutar npm test y npm run build, y reportar resultados.
- Explicar archivos modificados y archivos relevantes inspeccionados sin cambios.

Los criterios no son microgestión. Sirven para compartir el estándar de revisión antes de empezar.

Controla el presupuesto de contexto

La documentación de Memory explica que CLAUDE.md y auto memory se cargan como contexto, no como configuración forzada. Instrucciones más largas no garantizan mejor obediencia; pueden ocultar la regla importante.

Divide el contexto en tres capas.

Capa	Ejemplos	Mejor lugar
Siempre necesaria	Comandos de build, nombres, zonas prohibidas	CLAUDE.md o AGENTS.md
Específica de la tarea	Archivo objetivo, ejemplo similar, barra de calidad	prompt-packet.md
Leer solo si hace falta	Specs largas, actas antiguas, logs crudos	Mencionar archivo, no pegar todo

El error común es volcar todo el material en el prompt. Si mezclas actas, notas viejas, logs y tarea actual, el agente debe inferir prioridad. Escribe el orden de lectura.

Context to read in order:
1. AGENTS.md for project rules.
2. The target article.
3. One similar high-quality article for tone and structure.
4. Official docs only for tool behavior.

Ignore:
- Old brainstorming notes unless they contradict the current implementation.
- Unrelated product pages.
- Generated files and build output.

Esto reduce exploración inútil. También es más seguro cuando varias personas editan archivos cercanos en paralelo, porque el agente no interpreta todo lo que ve como permiso para editar.

Separa ejemplos y restricciones

Los ejemplos muestran el patrón. Las restricciones marcan el límite. Mezclarlos crea prompts ambiguos.

Prompt débil:

Haz esta página como el artículo de productividad.

Prompt mejor:

Reference style:
- Use site/src/content/blog-es/claude-code-productivity-tips.mdx only for section density and CTA placement.
- Do not copy its examples or claims.

Constraints:
- Keep this article focused on prompt engineering.
- Do not introduce pricing claims.
- Preserve heroImage and slug.

No termines con “no lo rompas”. Escribe también el límite positivo. “No agregues librerías” mejora si dices “usa solo dependencias existentes”. “No cambies demasiado” mejora si dices “edita solo el archivo listado y conserva la API pública”.

Pide un bucle seguro de iteración

Para trabajo serio, un solo mandato gigante es menos fiable que un bucle claro.

1. Leer objetivo, reglas y ejemplo cercano.
2. Proponer brevemente el plan.
3. Editar solo dentro del alcance.
4. Verificar con comandos y revisión manual.
5. Reportar cambios, evidencia y riesgos.

Puedes escribirlo así.

Workflow:
- First inspect the target file and the nearest quality reference.
- If the change is larger than two files, explain the plan before editing.
- Edit only the files listed in Scope.
- After editing, run the Verification commands if feasible.
- End with a verification receipt, not a general summary.

Una verification receipt es el recibo del trabajo. El patrón completo está en la guía de verification receipt, pero esta forma mínima sirve para el día a día.

Verification receipt:
- Changed files:
- Commands run:
- Results:
- Manual checks:
- Could not verify:
- Residual risks:

Cuatro casos de uso concretos

El primer caso es corregir bugs. Entrega síntoma, pasos de reproducción, resultado esperado, logs y archivos permitidos. Pide que explique la causa probable antes de editar, haga el cambio mínimo y agregue una prueba de ruta fallida. Así evitas arreglos cosméticos.

El segundo caso es agregar una función pequeña. Describe el cambio visible para el usuario, si puede cambiar API o base de datos, qué patrón de UI seguir y qué pruebas demuestran el resultado. Para agregar una categoría a un formulario de contacto, incluye opciones, validación, payload, evento de analítica y localización.

El tercer caso es reescribir artículos. Da lector, intención de búsqueda, longitud objetivo, ejemplos obligatorios, casos de fallo, enlaces internos, CTA y fuentes oficiales. En ClaudeCodeLab esto evita que un artículo delgado se convierta en un resumen más bonito en vez de una guía práctica.

El cuarto caso es revisión de código. El prompt de revisión necesita formato más que creatividad. Pide severidad, archivo y línea, condición de reproducción, dirección de solución y pruebas faltantes. En lugar de “revisa todo”, prioriza seguridad, pérdida de datos, cambios de API pública y rutas de error sin test.

Fallos frecuentes

Fallo 1: mezclar objetivos. “Refactoriza, acelera, mejora SEO y cambia el CTA” son varios trabajos. Usa un objetivo por paquete.

Fallo 2: escribir solo prohibiciones. “No rompas nada” no dice qué puede hacer el agente. Combina zona prohibida con zona permitida.

Fallo 3: tratar conocimiento viejo como comportamiento oficial. Claude Code, Codex, memory, settings y AGENTS.md pueden cambiar. Enlaza fuentes oficiales y evita afirmar más de lo que dicen.

Fallo 4: dejar la verificación como opcional. Si un comando no puede ejecutarse, el agente debe reportarlo. El silencio es peor que una brecha declarada.

Fallo 5: dejar buenos prompts atrapados en el chat. Mueve las instrucciones útiles a prompt-packet.md, CLAUDE.md o una checklist de revisión. Para continuidad de equipo, combínalo con reglas de traspaso.

CTA: estandariza antes de escalar

No tienes que reescribir este paquete cada día. Empieza con la chuleta gratuita para checks diarios, compara materiales reutilizables en productos y plantillas, y usa formación o consultoría de Claude Code cuando el equipo necesite reglas específicas de repositorio para CLAUDE.md, permisos, revisión, verification receipts y calidad editorial.

Qué verifiqué para este artículo

Para este artículo revisé el overview oficial de Claude Code para confirmar que puede leer una base de código, editar archivos y ejecutar comandos. Revisé Memory para distinguir CLAUDE.md, auto memory y configuración forzada. También confirmé en el prompt engineering overview de Anthropic que los criterios de éxito y las pruebas deben definirse antes de optimizar prompts, y alineé la parte de Codex con OpenAI Codex docs y AGENTS.md guidance. La conclusión práctica es tratar el prompt como un contrato revisable, no como un mensaje de chat aislado.