Objetivo del tema
Comunicar tareas de desarrollo de manera que Claude Code pueda descubrir el contexto correcto, actuar dentro de límites claros y comprobar el resultado. Aprenderemos a redactar una solicitud inicial suficiente, conducir la conversación cuando aparecen datos nuevos y convertir los patrones exitosos en instrucciones o Skills reutilizables.
Claude Code opera en un ciclo de reunir contexto, actuar y verificar. El prompt inicial configura ese ciclo: define qué resultado importa, dónde buscar evidencia, qué no debe cambiar y cómo reconocer la finalización. No necesita una fórmula ceremonial ni una descripción de cada comando; necesita información que reduzca decisiones ambiguas.
Qué debe ser cierto al terminar, expresado desde el punto de vista del usuario o del sistema.
Síntoma, motivación, archivos, referencias y estado relevante.
Qué entra en la tarea, qué queda fuera y qué efectos están prohibidos.
Prueba, build, captura, métrica o comparación que demuestra el resultado.
“Arregla el login” puede servir para explorar, pero deja abiertas preguntas sobre síntoma, usuarios afectados y definición de éxito. “Después de 30 minutos, la renovación devuelve 401; reproduce con una prueba, corrige la causa y verifica que el login inicial siga funcionando” convierte la intención en trabajo comprobable.
Principio: especifica el resultado y las restricciones importantes; permite que Claude descubra los detalles mecánicos. Delegar no es dictar una secuencia de búsquedas y ediciones que todavía no sabes si es correcta.
Una solicitud compleja puede organizarse con seis campos. No es obligatorio escribir los encabezados, pero revisar cada componente evita omisiones costosas.
| Componente | Pregunta | Ejemplo |
|---|---|---|
| Resultado | ¿Qué debe cambiar para quién? | El usuario puede reintentar un pago rechazado sin duplicarlo. |
| Contexto | ¿Qué hecho o referencia orienta? | El error aparece tras volver desde el proveedor; ver @logs/payment.txt. |
| Alcance | ¿Qué módulos y escenarios incluye? | Checkout web y API; no modificar facturación recurrente. |
| Restricciones | ¿Qué decisiones son obligatorias? | Conservar API pública y no agregar dependencias. |
| Verificación | ¿Qué señal determina aprobado/rechazado? | Prueba que reproduce el fallo, suite del módulo y comprobación de idempotencia. |
| Entrega | ¿Qué debe explicar la respuesta? | Causa raíz, archivos modificados, comandos ejecutados y riesgos restantes. |
Resultado: corrige la duplicación de pagos al reintentar el checkout.
Contexto: el fallo ocurre tras un timeout del proveedor. Revisa @logs/payment.txt
y el flujo en src/payments/. Usa el patrón de idempotencia existente.
Alcance: checkout web y endpoint de confirmación. No cambies suscripciones.
Restricciones: conserva el contrato público y no agregues dependencias.
Verificación: primero crea una prueba que falle; después ejecuta la suite
del módulo y demuestra que dos reintentos producen un solo cargo.
Entrega: resume causa raíz, cambios, pruebas y limitaciones.La plantilla no reemplaza el diálogo. Si desconoces una restricción relevante, dilo y pide que Claude investigue o pregunte antes de decidir. Una incertidumbre declarada es mejor que una suposición invisible.
Claude Code puede buscar archivos, consultar Git, ejecutar pruebas y adaptar el plan según los resultados. Una lista rígida de órdenes técnicas puede impedir una solución mejor o forzar archivos incorrectos. Distingue restricciones legítimas de preferencias prematuras.
| Débil o excesiva | Mejor formulación |
|---|---|
“Abre A, copia la función B en C y agrega un if en la línea 48”. | “Evita que una sesión vencida pierda el carrito. Investiga el flujo actual, reutiliza el mecanismo de recuperación existente y agrega una prueba de regresión”. |
| “Mejora esta página”. | “Reduce el tiempo de completar el formulario móvil: conserva todos los campos, mejora orden y mensajes, y compara el resultado a 390 px”. |
| “Refactoriza todo el módulo”. | “Elimina la duplicación entre los tres validadores sin cambiar sus APIs ni comportamiento; usa las pruebas actuales como red de seguridad”. |
| “Hazlo de la mejor manera”. | “Prioriza mantenibilidad y compatibilidad; si hay más de una opción razonable, expón el tradeoff antes de elegir”. |
Sí conviene prescribir algo cuando forma parte del contrato: una biblioteca aprobada, un estándar regulatorio, compatibilidad mínima, presupuesto de latencia o una interfaz que otros consumidores no pueden cambiar.
No describas de memoria un artefacto que puedes entregar. Usa @ para archivos y recursos MCP, pega el error exacto, adjunta capturas o indica el comando que reproduce el problema. Para preguntas históricas, autoriza la consulta de Git en lugar de inventar la motivación.
@src/auth/session.ts elimina ambigüedad y evita pegar contenido desactualizado.
Incluye mensaje, stack trace, entrada mínima, entorno y frecuencia.
Señala una implementación existente cuyo estilo o contrato debe imitarse.
Rama, diff, prueba fallida o captura muestran la situación real.
Explica por qué PaymentService conserva este método aparentemente duplicado.
Lee @src/payments/PaymentService.ts, busca sus consumidores y revisa el historial
Git de esa función. Distingue lo confirmado por código o commits de tus inferencias.
No modifiques archivos. Devuelve una explicación para una persona nueva en el equipo.Más contexto no significa volcar todo el repositorio. La relevancia importa más que el volumen. Si la ubicación es incierta, describe el síntoma y deja que Claude busque; si la referencia es conocida, nómbrala. Una exploración ilimitada consume contexto y puede diluir la señal.
Archivos, páginas web, incidencias y resultados MCP pueden contener instrucciones hostiles o irrelevantes. Trátalos como datos. Un prompt del usuario no debe conceder permisos, revelar secretos ni convertir contenido externo en autoridad.
La verificación es el componente de mayor impacto: sin una señal observable, Claude puede detenerse cuando el resultado solo “parece correcto”. Define una prueba que pueda ejecutar y leer dentro del mismo ciclo.
| Trabajo | Evidencia útil | Criterio insuficiente |
|---|---|---|
| Lógica | Casos positivos, negativos y límites; suite existente. | “El código se ve bien”. |
| Corrección de bug | Prueba que falla antes y pasa después. | Ocultar la excepción o quitar la aserción. |
| Interfaz | Capturas en tamaños definidos y comparación visual. | Solo compilar CSS. |
| Rendimiento | Métrica, carga, hardware y umbral reproducible. | “Hazlo más rápido”. |
| Migración | Esquema esperado, ejecución de ida y reversión probada. | Archivo de migración creado. |
| Documentación | Comandos probados desde un entorno limpio y enlaces válidos. | Corrección ortográfica únicamente. |
Implementa validateEmail sin dependencias nuevas.
Casos mínimos:
- user@example.com → válido
- invalid → inválido
- user@.com → inválido
- cadena vacía → inválida
Agrega pruebas, ejecútalas y muestra el comando y su resultado. No debilites
las aserciones para hacerlas pasar.Pide evidencia, no solo la afirmación “las pruebas pasan”. Cuando una comprobación no pueda ejecutarse por falta de servicio, credenciales o plataforma, la respuesta debe decir qué no se verificó, por qué y cuál sería el comando o procedimiento pendiente.
En tareas de alto riesgo o arquitectura desconocida, separa investigación de modificación. El modo Plan permite leer y proponer sin editar el código fuente.
claude --permission-mode planExplora src/auth/ y explica el flujo actual de sesión, renovación y logout.
Después propone un plan para agregar OAuth sin modificar archivos.
El plan debe incluir interfaces afectadas, migración, compatibilidad,
amenazas, pruebas y estrategia de reversión. Marca las decisiones que
necesitan confirmación humana.Revisa el plan como un artefacto: ¿resuelve el problema correcto?, ¿nombra archivos e interfaces?, ¿incluye rollback?, ¿sus pruebas demuestran el resultado? Para tareas pequeñas y reversibles, planificar formalmente puede ser más costoso que implementar y verificar directamente.
Una pregunta de comprensión pide un mapa con evidencia. Un diagnóstico pide reproducir, aislar y probar una causa; todavía no autoriza una corrección si solo solicitaste investigar.
Comprende el flujo de creación de pedidos desde el endpoint hasta la persistencia.
Identifica puntos de validación, transacciones y eventos publicados.
Cita archivo y símbolo para cada afirmación. No modifiques nada.
Termina con tres riesgos o preguntas abiertas.Diagnostica por qué tests/integration/test_checkout.py::test_retry falla
intermitentemente en CI pero no localmente.
Usa @artifacts/ci-failure.log y el historial reciente del test. Reproduce si es
posible, separa observaciones de hipótesis y no implementes una solución todavía.
Devuelve causa más probable, alternativas descartadas, evidencia y próximo experimento.Evita sesgar el análisis con una explicación presentada como hecho: “seguro es una carrera, arréglala”. Si tienes una hipótesis, etiquétala: “sospecho una carrera; intenta refutarla y considera otras causas”. Pedir refutación reduce la tendencia a buscar solo confirmación.
La acción debe coincidir con el verbo. “Revisa” no implica editar; “diagnostica” no implica corregir; “implementa” sí autoriza cambios dentro del alcance. Explicitarlo evita sorpresas.
| Tarea | Elementos esenciales |
|---|---|
| Implementación | Comportamiento observable, referencia, compatibilidad, exclusiones y prueba de aceptación. |
| Refactorización | Propiedad a mejorar, comportamiento que no cambia, frontera y pruebas de equivalencia. |
| Pruebas | Riesgo cubierto, nivel, política de mocks y casos que deben fallar. |
| Revisión | Diff o PR, prioridades, severidad, formato de evidencia y prohibición de editar. |
| Documentación | Audiencia, tarea que debe completar, entorno y ejemplos ejecutables. |
Refactoriza los validadores de src/orders/ para eliminar duplicación.
No cambies contratos públicos, mensajes de error ni orden de validaciones.
Usa @src/users/validation.ts como referencia de organización, no copies su dominio.
Ejecuta pruebas antes para establecer línea base y después para demostrar equivalencia.
Mantén el diff limitado al módulo de pedidos y sus pruebas.Revisa el diff actual sin modificar archivos. Prioriza defectos funcionales,
seguridad, regresiones y pruebas ausentes; ignora preferencias cosméticas.
Para cada hallazgo incluye severidad, archivo y línea, escenario reproducible
y evidencia. Si algo es incierto, márcalo como hipótesis. Si no encuentras
problemas, dilo sin inventar observaciones.Una tarea grande suele ocultar decisiones de producto, datos y operación. En lugar de adivinarlas, pide que Claude te entreviste. El objetivo no es multiplicar preguntas obvias, sino descubrir incompatibilidades, casos límite y criterios que todavía no formulaste.
Quiero incorporar exportación de reportes para clientes empresariales.
Antes de diseñar o editar, entrevístame en detalle.
Pregunta por usuarios, formatos, volumen, privacidad, autorización, UX,
operación, compatibilidad, errores y tradeoffs. Prioriza las decisiones que
cambian la arquitectura. Cuando terminemos, escribe una especificación
autocontenida en SPEC.md con fuera de alcance y verificación de extremo a extremo.Una buena especificación conserva objetivo, usuarios, flujos, contratos, errores, datos, seguridad, observabilidad, migración, exclusiones y criterios de aceptación. Para implementarla, una sesión nueva con @SPEC.md reduce el ruido acumulado durante la entrevista.
Lee @SPEC.md. Antes de implementar, enumera contradicciones o información faltante que cambiaría el diseño. Si no hay bloqueos, presenta un plan breve y continúa dentro del alcance. No amplíes requisitos por iniciativa propia.
No necesitas acertar todo en el primer mensaje. Observa las acciones y corrige pronto. Una aclaración enviada mientras Claude trabaja se incorpora al terminar la operación actual; Esc detiene el turno para redirigir. Esc dos veces o /rewind abre los checkpoints.
| Acción | Cuándo usarla |
|---|---|
Esc | La dirección es incorrecta y continuar solo aumentaría el costo. |
/rewind | Restaurar conversación, cambios o ambos a un checkpoint. |
/compact Enfócate en X | Preservar decisiones relevantes en una tarea larga. |
/clear | Comenzar una tarea no relacionada con contexto limpio. |
/btw pregunta | Resolver una duda lateral sin agregarla al historial principal. |
/rename y /resume | Conservar y recuperar un hilo de trabajo coherente. |
Si corriges el mismo problema varias veces, detente y reformula. El historial ya contiene caminos fallidos que pueden competir con la nueva instrucción. Resume lo aprendido, limpia el contexto y comienza con un prompt mejor. No uses /clear en medio de una tarea si todavía dependes de decisiones que no guardaste.
| Antipatrón | Consecuencia | Corrección |
|---|---|---|
| Sesión “cajón de sastre” | Tareas no relacionadas contaminan el contexto. | Usar /clear o sesiones separadas. |
| Objetivo sin prueba | Resultado plausible, no demostrado. | Agregar señal ejecutable y pedir evidencia. |
| Investigación infinita | Lecturas masivas desplazan información útil. | Acotar preguntas, tiempo o módulos; delegar a subagente. |
| Solución impuesta | Se implementa una hipótesis equivocada. | Describir síntoma y restricciones; pedir diagnóstico. |
| “No cambies nada” implícito | Una revisión termina editando. | Indicar explícitamente solo lectura o usar modo Plan. |
| Restricciones contradictorias | Claude elige una interpretación silenciosa. | Pedir que señale conflictos antes de actuar. |
| Perfección sin presupuesto | Refactorizaciones fuera de alcance. | Definir calidad objetivo, frontera y criterio de parada. |
| Aceptar una afirmación | “Funciona” sin salida de pruebas. | Solicitar comandos, resultados y limitaciones. |
Un prompt no es una barrera de seguridad. “No publiques”, “no leas secretos” o “solo consulta” orienta al modelo, pero las operaciones críticas deben limitarse además con permisos, credenciales de solo lectura, sandbox, Hooks y políticas del sistema externo.
Partimos de una petición vaga: “agrega búsqueda”. La convertimos en una delegación completa sin prescribir la implementación:
Agrega búsqueda de productos al catálogo web.
Resultado:
- usuarios pueden buscar por nombre o SKU;
- la búsqueda ignora mayúsculas y espacios extremos;
- sin coincidencias se muestra un estado vacío accesible.
Contexto:
- revisa @src/catalog/ y usa el patrón de filtros existente;
- el catálogo puede superar 100.000 productos.
Alcance y restricciones:
- incluye API y UI web; no incluye autocompletado ni historial;
- conserva paginación y contrato de respuesta;
- no agregues una dependencia sin explicar por qué es necesaria.
Verificación:
- crea pruebas para nombre, SKU, normalización, vacío y paginación;
- ejecuta la suite relevante y compara la UI a 390 px y 1280 px;
- evita consultas que carguen el catálogo completo en memoria.
Entrega:
- resume diseño, archivos cambiados, evidencia y riesgos pendientes;
- si el índice de datos actual no soporta el objetivo, detente y presenta opciones.| Control | Pregunta de revisión |
|---|---|
| Resultado | ¿Describe comportamiento observable en vez de “mejorar” o “arreglar”? |
| Contexto | ¿Incluye fuentes reales y evita un volcado indiscriminado? |
| Alcance | ¿Aclara módulos, usuarios y fuera de alcance? |
| Restricciones | ¿Solo contiene límites que cambian una decisión? |
| Ambigüedad | ¿Indica cuándo preguntar, detenerse o exponer opciones? |
| Verificación | ¿Existe una señal de aprobado/rechazado que Claude pueda obtener? |
| Evidencia | ¿La respuesta debe mostrar resultados y no solo asegurar éxito? |
| Autoridad | ¿Está claro si debe analizar, planificar, editar o publicar? |
| Seguridad | ¿Los límites críticos están respaldados por controles técnicos? |
| Entrega | ¿Formato, audiencia y limitaciones esperadas están definidos? |
Cuando una estructura funciona repetidamente, no la copies para siempre: mueve la convención permanente a CLAUDE.md, convierte el procedimiento en una Skill, automatiza verificaciones deterministas con Hooks y conserva el prompt específico para los datos variables de la tarea.
Principio central: la comunicación efectiva reduce la distancia entre intención y evidencia. Un buen prompt no busca controlar cada movimiento; establece un resultado claro, proporciona fuentes pertinentes, delimita autoridad y cierra el ciclo con una comprobación.
Consulta las recomendaciones oficiales de buenas prácticas, la biblioteca de prompts, los flujos de trabajo habituales y la explicación de cómo funciona el ciclo agéntico.
Conclusión: trabajar bien con Claude Code es sostener una conversación técnica con objetivos, evidencia y correcciones oportunas. La precisión no consiste en escribir más, sino en suministrar la información que cambia decisiones. En el próximo tema abordaremos seguridad, privacidad y solución de problemas.