La calidad del código generado por IA depende casi por completo de lo que pides y de cómo lo pides. Esta guía cubre los patrones que producen de forma sistemática mejores resultados con Claude Code.
Desde acotar la tarea hasta los prompts de sistema, desde el refinamiento iterativo hasta las instrucciones por rol. Técnicas prácticas que puedes aplicar en tu próxima sesión de código.
Cuando le pides a un desarrollador humano que 'construya una página de inicio de sesión', te hace preguntas para aclarar: ¿qué proveedor de autenticación? ¿Qué campos? ¿Hay que gestionar OAuth? ¿Mensajes de error? ¿Estados de carga?
Los agentes de codificación IA intentarán responder ellos mismos a todas esas preguntas. A veces aciertan. A menudo producen algo razonable, pero no lo que querías. Ese hueco entre 'razonable' y 'exactamente lo que hacía falta' es lo que cierra el prompt engineering.
Un buen prompt no tiene por qué ser largo. Tiene que ser preciso en lo que importa y callarse en lo que no. De ese equilibrio trata esta guía.
Patrones que mejoran los resultados sea cual sea la tarea.
En lugar de 'crea un componente React, luego añade estado, luego añade estilos', describe el resultado final: 'Construye una barra lateral plegable que muestre los nombres de proyecto, permita reordenar con arrastrar y soltar y use nuestro tema Tailwind actual.' Deja que el agente decida cómo llegar hasta ahí.
Avoid
Crea un componente. Añade useState. Añade un botón de alternar. Dale estilo con Tailwind.
Better
Construye un componente de barra lateral plegable que liste los proyectos por nombre. Debe permitir reordenar arrastrando y respetar nuestro tema oscuro (bg-[#111318], border-[#262b38]). El estado plegado debe persistir entre recargas de página.
Los agentes funcionan mejor cuando conocen los límites. Indica qué archivos tocar (o evitar), qué patrones seguir y qué significa 'terminado'. Las tareas sin límites derivan en cambios dispersos y difíciles de revisar.
Avoid
Refactoriza el sistema de autenticación.
Better
Refactoriza el handler de login en src/api/auth/login.ts para usar bcrypt en lugar de sha256 en el hash de contraseñas. No cambies la lógica JWT ni la gestión de la cookie de sesión. Actualiza los tests relacionados en tests/auth/.
Claude Code puede leer los archivos de tu proyecto, pero no puede leerte la mente. Si sigues una convención, si prefieres una biblioteca concreta o si ya has establecido un patrón, dilo. Eso ahorra rehacer trabajo.
Avoid
Añade validación al formulario.
Better
Añade validación al formulario de registro usando zod (ya lo usamos en el formulario de ajustes, en src/forms/settings.ts). Muestra mensajes de error en línea debajo de cada campo. Usa el mismo estilo de error que el formulario de inicio de sesión.
Los prompts compuestos ('construye la API, escribe los tests, actualiza la documentación y despliega') obligan al agente a sostener demasiados objetivos a la vez. Divide el trabajo complejo en tareas secuenciales y enfocadas. Cada una se apoya en el resultado de la anterior.
Avoid
Construye la página de perfil de usuario, escribe los endpoints de API, añade tests, actualiza el README y, ya de paso, arregla la barra de navegación.
Better
Construye el endpoint GET /api/user/profile. Devuelve los campos id, name, email y plan. Usa el middleware de autenticación existente.
Si el primer resultado no es el correcto, refina el prompt en lugar de volver a empezar. Claude conserva todo el contexto de la conversación. Di qué está mal, qué cambiar y qué conservar. Iterar es más rápido que reinventar.
Avoid
Está mal. Empieza de nuevo y construye el componente de otra forma.
Better
El layout está bien, pero el breakpoint móvil no. Por debajo de 768px, apila las tarjetas en vertical en lugar de usar una cuadrícula. Deja todo lo demás igual.
Los prompts de sistema fijan el comportamiento de base de un agente antes de que digas nada. Son la herramienta más infrautilizada de la codificación con IA.
Un prompt de sistema le dice al agente quién es, en qué debe centrarse y qué debe evitar. Se aplica a todos los mensajes de la sesión. Piensa en él como la descripción del puesto del agente.
AgentsRoom incluye 14 prompts de sistema por rol: uno para cada tipo de agente. El prompt del agente Frontend le indica que se centre en los componentes, la accesibilidad y el diseño responsive. El del agente QA le indica que piense en los casos límite y escriba tests exhaustivos. Puedes personalizarlos o escribir los tuyos.
Eres un desarrollador frontend senior. Céntrate en los componentes React, los estilos CSS/Tailwind, la accesibilidad (WCAG AA) y el diseño responsive. Usa la biblioteca de componentes que ya existe en el proyecto antes de crear componentes nuevos. Prefiere la composición a la herencia. Escribe HTML semántico. Nunca modifiques archivos de backend.
El prompt más eficaz no se escribe en un chat. Vive en tu repositorio.
CLAUDE.md es un archivo markdown en la raíz de tu proyecto que Claude Code lee automáticamente. Contiene la estructura del proyecto, las convenciones, los detalles del stack y las pautas que se aplican a todas las sesiones de agente del proyecto.
En lugar de repetir 'usamos Tailwind CSS 4, Prisma ORM y Next.js 16' en cada conversación, escríbelo una vez en CLAUDE.md. Cada agente hereda ese contexto. AgentsRoom incluye un editor integrado de CLAUDE.md para que puedas actualizarlo sin salir de la aplicación.
Un CLAUDE.md bien escrito vale más que decenas de prompts individuales cuidadosamente elaborados. Se acumula: todas las sesiones se benefician de él.
Deja de reescribir las mismas instrucciones. Guarda lo que funciona y reutilízalo.
Si te descubres escribiendo el mismo tipo de petición en varios proyectos ('escribe tests unitarios para este archivo', 'refactoriza esto para usar el patrón repositorio', 'añade gestión de errores a todas las rutas de API'), guárdalo como un prompt reutilizable.
AgentsRoom incluye una biblioteca de prompts con dos niveles: prompts por proyecto para las tareas específicas de ese proyecto y prompts globales (sincronizados por la nube) para los patrones que usas en todas partes.
Buenos candidatos para la biblioteca: listas de verificación de revisión de código, plantillas para escribir tests, scripts de migración, instrucciones de andamiaje de componentes, pasos de auditoría de seguridad. Cualquier cosa que pondrías en la wiki del equipo como procedimiento estándar.
Escribe tests unitarios para [archivo]. Usa vitest. Cubre el camino feliz, los casos límite (entrada vacía, null, tipos inválidos) y la gestión de errores. Mockea las dependencias externas. Apunta a más de un 90% de cobertura de ramas.
Revisa los cambios del git diff actual. Comprueba: imports sin usar, gestión de errores ausente, problemas de seguridad de tipos, posibles condiciones de carrera e inconsistencias de nomenclatura. Propón una corrección para cada problema encontrado.
Crea un endpoint REST para [recurso]. Incluye validación de entrada con zod, respuestas de error adecuadas (400, 401, 404, 500), tipos TypeScript para la petición y la respuesta, y un comentario JSDoc que describa el endpoint. Sigue el patrón existente en src/api/.
Técnicas para tareas complejas que van más allá de un solo prompt.
Divide una tarea grande en pasos ordenados. Lanza el primer agente con el paso uno, espera a que termine y lanza el siguiente agente con el paso dos (referenciando la salida del paso uno). Cada paso es más pequeño y está más enfocado. Ejemplo: el agente 1 diseña el esquema de base de datos, el agente 2 escribe la API sobre ese esquema, el agente 3 escribe los tests contra la API.
Cuando un agente termina, apunta otro agente distinto a su salida. 'Revisa los cambios que acaba de hacer el agente frontend en src/components/. Busca problemas de accesibilidad y estados de error que falten.' Un agente nuevo con otro rol detecta cosas que al primero se le escaparon.
Empieza con un prompt amplio para ver cómo aborda el agente el problema. Después añade restricciones en los mensajes siguientes: 'Buena estructura, pero usa Server Components en lugar de componentes de cliente.' 'Mantén el hook, pero quita el useEffect y usa en su lugar una mutación de React Query.' Cada iteración estrecha el cerco hacia la solución que quieres.
Apunta al agente hacia código existente: 'Construye una página de ajustes siguiendo el mismo patrón que src/pages/profile.tsx. Misma estructura de layout, misma gestión del formulario, misma presentación de errores.' Suele funcionar mejor que describir el patrón con palabras.
Patrones que producen peores resultados de forma sistemática.
Decirle al agente exactamente qué funciones escribir, cómo nombrar cada variable y en qué orden implementarlo todo. Esa microgestión le quita la posibilidad de encontrar un enfoque mejor. Describe el resultado, no el procedimiento.
Pedirle a un agente que 'mejore la base de código' sin ninguna restricción. Sin límites, el agente puede refactorizar archivos que no querías tocar, cambiar APIs de las que depende otro código o gastar tokens en mejoras de baja prioridad.
No mencionar que un patrón, una utilidad o un componente ya existe en el proyecto. El agente creará otro. Un simple 'ya tenemos un hook useAuth en src/hooks/' ahorra mucho trabajo repetido.
Meter cinco tareas en un solo mensaje. El agente las intentará todas, pero la calidad cae mientras hace malabares con objetivos que compiten entre sí. Divídelas en peticiones secuenciales y enfocadas.
El código ya no es el cuello de botella, la comunicación sí lo es. Aprende a hablar con tus agentes de IA Claude, Codex, Antigravity y Grok Build para entregar más rápido, con más precisión y gastando menos tokens.
Pasar un PDF directamente a Claude o a cualquier LLM quema tokens en silencio: cada página también se convierte en imagen. Convierte primero el archivo a Markdown con MarkItDown, la herramienta open source gratuita de Microsoft, y recorta tu factura de tokens hasta un 80%. Guía completa: CLI, Python y servidor MCP.
AgentsRoom te da prompts de sistema, una biblioteca de prompts y la edición de CLAUDE.md integrada. Menos tiempo redactando prompts, más tiempo construyendo.
App complementaria: supervisa tus agentes en movimiento
Usa Claude, Codex, Antigravity CLI u otro proveedor de IA.
Envía bugs y peticiones directamente a tu backlog público.