Introducción

Claude Code es un agente de codificación que se ejecuta en la terminal: lee tu prompt, razona sobre el contexto y luego ejecuta una secuencia de acciones sobre tu codebase real. Como resultado, la calidad del prompt influye directamente en la calidad del resultado: un prompt vago genera código incorrecto, código innecesario o un agente que no deja de hacer preguntas de aclaración. Esta lección se centra en técnicas concretas de prompting para ayudar a Claude Code a comprender tu intención correctamente en el primer intento.

Principio fundamental: claridad por encima de brevedad

Un error habitual es intentar escribir el prompt más corto posible, asumiendo que la IA "se las arreglará". Con Claude Code, ocurre lo contrario: un contexto suficiente produce, de forma consistente, mejores resultados que los prompts escuetos.

Compara estos dos prompts:

Prompt débil: "Arregla el bug en el archivo de autenticación"

Prompt fuerte: "En src/auth/login.ts, la función validateToken está devolviendo true para tokens expirados. Arréglala para que compruebe el campo exp en el payload del JWT y lance un AuthError si el token ha expirado."

El segundo prompt especifica el archivo exacto, el nombre de la función, el síntoma del bug, el comportamiento esperado y el tipo de error que debe lanzarse. Claude Code no tiene nada que adivinar.

Estructura de un prompt efectivo

Un prompt bien redactado para Claude Code suele incluir cuatro componentes: contexto, requisito, restricciones y resultado esperado. No es necesario escribirlos como cuatro secciones separadas: basta con que la información esté presente en el prompt.

Un ejemplo real para una tarea de añadir una funcionalidad:

Context: Project dùng Express.js + TypeScript, database là PostgreSQL qua Prisma ORM.
Yêu cầu: Thêm endpoint POST /api/users/:id/deactivate để soft-delete user (set trường isActive = false, không xóa record).
Ràng buộc: Chỉ admin mới gọi được endpoint này — dùng middleware isAdmin đã có ở src/middleware/auth.ts. Không thay đổi schema Prisma.
Kết quả: Tạo handler trong src/routes/users.ts, thêm route vào src/app.ts, viết 1 integration test cơ bản.

Este estilo de prompt no requiere ninguna sintaxis especial: la prosa simple o los puntos suspensivos funcionan bien, siempre que la información esté completa.

Técnica avanzada: guiar con ejemplos

Cuando quieres que Claude Code escriba código en un estilo concreto (por ejemplo, siguiendo las convenciones de tu codebase existente), el enfoque más eficaz es señalarle directamente un archivo de referencia.

Viết unit test cho hàm calculateDiscount trong src/pricing/discount.ts.
Dùng cùng cấu trúc test như trong src/pricing/tax.test.ts: describe block theo tên hàm, test case dùng it(), mock bằng jest.fn().

Esto funciona mucho mejor que una descripción larga del estilo deseado, porque Claude Code leerá el archivo de referencia y deducirá el patrón por sí mismo.

Otra técnica consiste en dividir las tareas grandes en prompts secuenciales en lugar de combinarlo todo en uno solo:

Bước 1: Chỉ phân tích file src/payment/processor.ts và liệt kê các hàm hiện có, đừng sửa gì.

Una vez que Claude Code informe con su análisis, proporciona el prompt para el paso 2. Este enfoque te permite validar cada paso y evita que el agente se aleje demasiado de tu intención original.

Errores comunes

Error 1: Usar términos vagos como "optimizar", "mejorar" o "limpiar" sin especificar los criterios. Sustitúyelos por: "reduce el número de llamadas a la base de datos dentro del bucle en fetchUserOrders" o "renombra las variables del archivo X para que sigan la convención camelCase".

Error 2: Omitir restricciones técnicas. Si no quieres que Claude Code instale paquetes nuevos, indícalo de forma explícita: "No uses librerías externas: utiliza solo lo que ya está en package.json". El agente no puede inferir estos límites por sí mismo.

Error 3: Pedir demasiadas cosas en un único prompt. Cuando un mismo prompt incluye refactorización, añadir una funcionalidad y escribir pruebas a la vez, Claude Code puede priorizar mal o pasarse algo por alto. Divide el trabajo en sesiones separadas.

Error 4: No definir el alcance. Si la tarea solo afecta a un módulo, indícalo con claridad: "Realiza cambios únicamente dentro de src/billing/, no toques ninguna otra parte del codebase".

Resumen

Escribir prompts efectivos para Claude Code no requiere técnicas complejas: basta con proporcionar contexto suficiente, exponer claramente las restricciones y dividir las tareas cuando sea necesario. La regla más sencilla que conviene recordar es: si un desarrollador nuevo en el equipo lee tu prompt y no está seguro de qué hacer, Claude Code tampoco lo estará. Escribe como si estuvieras delegando en un compañero: sé específico, aporta contexto y deja claro qué significa "terminado".