La calidad del codigo generado por IA depende casi totalmente de lo que pides y como lo pides. Esta guia cubre los patrones que consistentemente producen mejores resultados con Claude Code.
Desde el alcance de tareas hasta los prompts de sistema, desde el refinamiento iterativo hasta las instrucciones por rol. Tecnicas practicas que puedes aplicar en tu proxima sesion de codigo.
Cuando le pides a un desarrollador humano que 'construya una página de login', hace preguntas clarificadoras: ¿que proveedor de autenticacion? ¿Que campos? ¿Deberia manejar OAuth? ¿Mensajes de error? ¿Estados de carga?
Los agentes de codigo IA intentaran responder todas esas preguntas ellos mismos. A veces aciertan. Muchas veces adivinan algo razonable pero no lo que querias. La brecha entre 'razonable' y 'exactamente correcto' es lo que cierra la ingenieria de prompts.
Los buenos prompts no necesitan ser largos. Necesitan ser especificos sobre las cosas que importan y silenciosos sobre las que no. Ese equilibrio es de lo que trata esta guia.
Patrones que mejoran resultados independientemente de 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 nombres de proyectos, soporte arrastrar para reordenar y use nuestro tema Tailwind existente.' Deja que el agente decida como llegar.
Avoid
Crea un componente. Añade useState. Añade un boton toggle. Estilizalo con Tailwind.
Better
Construye un componente de barra lateral plegable que liste proyectos por nombre. Debe soportar arrastrar para reordenar y coincidir con nuestro tema oscuro (bg-[#111318], border-[#262b38]). El estado colapsado debe persistir entre recargas de página.
Los agentes funcionan mejor cuando conocen los limites. Especifica que archivos tocar (o evitar), que patrones seguir y como se ve 'terminado'. Las tareas sin limites llevan a cambios extensos dificiles de revisar.
Avoid
Refactoriza el sistema de autenticacion.
Better
Refactoriza el handler de login en src/api/auth/login.ts para usar bcrypt en lugar de sha256 para el hash de contraseñas. No cambies la logica JWT ni el manejo de cookies de sesion. Actualiza los tests relacionados en tests/auth/.
Claude Code puede leer los archivos de tu proyecto, pero no puede leer tu mente. Si hay una convencion que sigues, una biblioteca que prefieres o un patron que ya estableciste, dilo. Esto ahorra retrabajo.
Avoid
Añade validacion de formulario.
Better
Añade validacion de formulario al formulario de registro usando zod (ya lo usamos para el formulario de configuración en src/forms/settings.ts). Muestra mensajes de error en linea debajo de cada campo. Sigue el mismo estilo de error que el formulario de login.
Los prompts compuestos ('construye la API, escribe tests, actualiza la documentacion y despliega') fuerzan al agente a mantener demasiados objetivos a la vez. Divide el trabajo complejo en tareas secuenciales y enfocadas. Cada una se basa en el resultado anterior.
Avoid
Construye la página de perfil de usuario, escribe endpoints de API, añade tests, actualiza el README y arregla la barra de navegación de paso.
Better
Construye el endpoint GET /api/user/profile. Devuelve los campos id, name, email y plan. Usa el middleware de autenticacion existente.
Si el primer resultado no es correcto, refina el prompt en lugar de empezar de cero. Claude retiene el contexto completo de la conversacion. Di que esta mal, que cambiar y que mantener. La iteracion es mas rápida que la reinvencion.
Avoid
Eso esta mal. Empieza de nuevo y construye el componente diferente.
Better
El layout esta bien pero el breakpoint movil esta mal. Por debajo de 768px, apila las tarjetas verticalmente en lugar de usar grid. Mantiene todo lo demas como esta.
Los prompts de sistema establecen el comportamiento base de un agente antes de que digas nada. Son la herramienta mas infrautilizada en el codigo con IA.
Un prompt de sistema le dice al agente quien es, en que debe enfocarse y que debe evitar. Se aplica a cada mensaje de la sesion. Piensa en el como la descripcion de puesto del agente.
AgentsRoom incluye 14 prompts de sistema por rol: uno para cada tipo de agente. El prompt del agente de Frontend le dice que se enfoque en componentes, accesibilidad y diseño responsivo. El prompt del agente de QA le dice que piense en casos limite y escriba tests completos. Puedes personalizarlos o escribir los tuyos propios.
Eres un desarrollador frontend senior. Enfocate en componentes React, estilos CSS/Tailwind, accesibilidad (WCAG AA) y diseño responsivo. Usa la biblioteca de componentes existente del proyecto antes de crear nuevos componentes. Prefiere composicion sobre herencia. Escribe HTML semantico. Nunca modifiques archivos de backend.
El prompt mas efectivo no se escribe en un chat. Vive en tu repositorio.
CLAUDE.md es un archivo markdown en la raiz de tu proyecto que Claude Code lee automáticamente. Contiene estructura del proyecto, convenciones, detalles del stack y directrices que aplican a cada sesion de agente.
En lugar de repetir 'usamos Tailwind CSS 4, Prisma ORM y Next.js 16' en cada conversacion, escribelo una vez en CLAUDE.md. Cada agente hereda este contexto. AgentsRoom incluye un editor integrado para CLAUDE.md que puedes actualizar sin salir de la app.
Un CLAUDE.md bien escrito vale mas que docenas de prompts individuales cuidadosamente elaborados. Se acumula: cada sesion se beneficia de el.
Deja de reescribir las mismas instrucciones. Guarda lo que funciona y reutilizalo.
Si te encuentras escribiendo el mismo tipo de solicitud en todos los proyectos ('escribe tests unitarios para este archivo', 'refactoriza esto para usar el patron repositorio', 'añade manejo de errores a todas las rutas API'), guardalo como un prompt reutilizable.
AgentsRoom incluye una función de biblioteca de prompts con dos niveles: prompts por proyecto para tareas especificas del proyecto y prompts globales (sincronizados en la nube) para patrones que usas en todas partes.
Buenos candidatos para prompts de biblioteca: listas de verificacion de revision de codigo, plantillas de escritura de tests, scripts de migracion, instrucciones de scaffolding de componentes, pasos de auditoria de seguridad. Cualquier cosa que pondrias en una wiki de equipo como procedimiento estandar.
Escribe tests unitarios para [archivo]. Usa vitest. Cubre el camino feliz, casos limite (entrada vacia, null, tipos invalidos) y manejo de errores. Mockea dependencias externas. Apunta a >90% de cobertura de ramas.
Revisa los cambios en el diff de git actual. Busca: imports no usados, manejo de errores faltante, problemas de seguridad de tipos, posibles condiciones de carrera e inconsistencias de nomenclatura. Sugiere correcciones para cada problema encontrado.
Crea un endpoint REST para [recurso]. Incluye validacion de entrada con zod, respuestas de error apropiadas (400, 401, 404, 500), tipos TypeScript para request/response y un comentario JSDoc describiendo el endpoint. Sigue el patron existente en src/api/.
Tecnicas para tareas complejas que van mas alla de prompts individuales.
Divide una tarea grande en pasos ordenados. Inicia el primer agente con el paso uno, espera a que termine, luego inicia el siguiente agente con el paso dos (referenciando la salida del paso uno). Cada paso es mas pequeño y enfocado. Ejemplo: el Agente 1 diseña el esquema de base de datos, el Agente 2 escribe la API usando ese esquema, el Agente 3 escribe tests contra la API.
Despues de que un agente termina, apunta a un agente diferente a su salida. 'Revisa los cambios que el agente de frontend acaba de hacer en src/components/. Busca problemas de accesibilidad y estados de error faltantes.' Un agente fresco con un rol diferente detecta cosas que el agente original paso por alto.
Comienza con un prompt amplio para ver como el agente aborda el problema. Luego añade restricciones en mensajes de seguimiento: 'Buena estructura, pero usa server components en lugar de client components.' 'Mantiene el hook, pero elimina el useEffect y usa una mutacion de React Query en su lugar.' Cada iteracion se acerca a la solución que deseas.
Señala al agente codigo existente: 'Construye una página de configuración siguiendo el mismo patron que src/pages/profile.tsx. Misma estructura de layout, mismo manejo de formularios, misma visualizacion de errores.' Esto suele ser mas efectivo que describir el patron con palabras.
Patrones que consistentemente producen peores resultados.
Decirle al agente exactamente que funciones escribir, que variables nombrar y en que orden implementar. Esta microsgestion elimina la capacidad del agente de encontrar un mejor enfoque. Describe el resultado, no el procedimiento.
Pedir a un agente que 'mejore el codebase' sin restricciones. Sin limites, el agente podria refactorizar archivos que no querias tocar, cambiar APIs de las que depende otro codigo, o gastar tokens en mejoras de baja prioridad.
No mencionar que un patron, utilidad o componente ya existe en el proyecto. El agente creara uno nuevo. Un simple 'ya tenemos un hook useAuth en src/hooks/' ahorra retrabajo significativo.
Meter cinco tareas en un mensaje. El agente intentara todas, pero la calidad baja cuando maneja objetivos en competencia. Dividelas en solicitudes secuenciales y enfocadas.
AgentsRoom te ofrece prompts de sistema, una biblioteca de prompts y edicion de CLAUDE.md integrados. Menos tiempo elaborando prompts, mas tiempo construyendo.
App complementaria: supervisa tus agentes en movimiento
Usa Claude, Codex, Gemini CLI u otro proveedor de IA.
Envía bugs y peticiones directamente a tu backlog público.