Mejores prácticas: consolidando buenos hábitos en un método de trabajo

📚 Navegación de la serie: El artículo anterior 48 Proyecto integrador: de principio a fin, conectando los conocimientos unificó todas las herramientas vistas en un flujo de desarrollo completo. Este artículo adopta otra perspectiva: no enseña nuevas funciones, sino cómo utilizar las existentes con excelencia. Con el mismo Claude Code, algunos desarrolladores avanzan con fluidez mientras otros se enfrentan a bloqueos recurrentes; la diferencia radica en las mejores prácticas desarrolladas por la comunidad y el equipo oficial. Resumiremos estas prácticas en reglas aplicables y tablas comparativas de aciertos y errores.

"Este prompt es demasiado vago."

Considera a un desarrollador que se inicia con Claude Code. Escribe "corrige el bug de inicio de sesión" en la terminal, presiona enter, espera a que Claude modifique el código y termina frustrado al recibir cambios que no esperaba, preguntándose: "¿Acaso no fui lo bastante claro?".

Si le dieras esa misma instrucción a un programador en prácticas que acaba de ingresar al equipo y no conoce el proyecto, ¿lograría corregir el bug de forma correcta? ¿De qué inicio de sesión se trata? ¿Cuál es el fallo? ¿En qué archivo ocurre? ¿Cómo se valida que está resuelto? No indicaste ninguno de estos detalles. Compara con esta instrucción detallada: "Los usuarios reportan fallos de inicio de sesión tras expirar la sesión por inactividad. Analiza la renovación de tokens en src/auth/, escribe una prueba que replique el fallo y corrígelo." Con esta instrucción, Claude resolverá la tarea en el primer intento.

El éxito al usar Claude Code no depende de la herramienta en sí, sino de cómo colabores con ella. Es sumamente capaz, pero no puede adivinar tus intenciones. Este artículo reúne las directrices oficiales de mejores prácticas y la experiencia de los desarrolladores en reglas de uso que puedes aplicar desde hoy.

Al terminar este artículo, obtendrás:

• La regla básica que guía el flujo de trabajo (el contexto de conversación es el recurso más valioso). Entender esta regla aclara el porqué de las demás directrices.
• Cinco reglas de oro: definir métodos de validación, analizar antes de programar, ser específico en las instrucciones, mantener CLAUDE.md conciso y reorientar al agente ante desviaciones.
• Tablas comparativas de malas prácticas vs. buenas prácticas para optimizar tus instrucciones de inmediato.
• Una guía de consulta rápida para cada escenario de desarrollo y un ejercicio práctico de comparación.

---

01 La regla básica: el contexto es tu recurso más valioso

Casi todas las mejores prácticas convergen en el mismo punto de origen. La documentación oficial lo describe al principio:

La mayoría de las mejores prácticas se basan en una restricción física: la memoria de contexto de Claude se llena rápidamente y, a medida que esto ocurre, la precisión de sus respuestas disminuye.

El contexto (la memoria de trabajo donde Claude almacena la conversación) contiene cada mensaje enviado, los archivos que ha leído y los resultados de consola de los comandos ejecutados. Si realizas una sesión extensa de depuración o le pides que analice múltiples directorios, el contexto acumulará miles de tokens rápidamente (el artículo 19 explica el concepto de tokens y contexto).

Cuando el contexto se satura, el agente pierde precisión: empieza a omitir directrices previas o a introducir fallos básicos de lógica.

Analogía: un programador en prácticas con una pizarra de tamaño limitado. El programador es capaz y rápido, pero trabaja bajo una condición: su memoria operativa se limita a una pizarra de tamaño fijo. Todo lo que le pides, las páginas de código que consulta y los logs que ejecuta deben escribirse en esa pizarra. Cuando la pizarra se llena, empieza a borrar información previa para hacer espacio: la regla de "ejecutar pruebas antes de realizar commits" que le indicaste en la mañana se borra para registrar los logs de la tarde.

Esta analogía es clave: casi todas las mejores prácticas buscan optimizar el espacio de esta pizarra corporativa:

• Definir métodos de validación para que el agente verifique sus cambios de forma autónoma, ahorrándote tiempo de supervisión y evitando llenar la pizarra con confirmaciones repetitivas.
• Analizar antes de programar para validar el diseño antes de escribir código, evitando consumir espacio de la pizarra con propuestas erróneas.
• Ser específico en las instrucciones para reducir las rondas de aclaración y el consumo de contexto asociado.
• Mantener CLAUDE.md conciso para no ocupar espacio de la pizarra con explicaciones innecesarias desde el inicio de la sesión.
• Reorientar ante desviaciones de inmediato, evitando saturar la pizarra con intentos fallidos.

Al entender esta limitación física de la memoria de contexto, las cinco reglas siguientes cobran sentido: optimizar el espacio de la pizarra para que el agente trabaje con la mayor precisión.

💡 Resumen rápido: El contexto de Claude es limitado y su saturación reduce la precisión del agente. Trata al contexto como tu recurso más valioso y aplica las reglas siguientes para optimizar el uso de su memoria de trabajo.

---

02 Regla 1: Define un método de validación autónomo

Para empezar, esta es la regla más importante de la guía:

Proporciona a Claude un método de validación ejecutable: pruebas automatizadas, scripts de compilación o comparaciones visuales. Esto diferencia una sesión que requiere tu supervisión constante de una sesión que se ejecuta de forma autónoma.

La documentación oficial destaca este punto de inflexión:

Claude se detendrá cuando considere que la tarea está completada. Sin pruebas ejecutables que pueda correr, la única señal de finalización es visual y te obliga a actuar como el revisor del ciclo.

En otras palabras: si no defines un método de validación, el rol de revisor de calidad recae sobre ti, obligándote a validar cada cambio en el código. Si proporcionas un comando que valide con un resultado de "aprobado / fallido", el ciclo se automatiza: Claude edita el código, ejecuta la validación, procesa los logs si falla y corrige la lógica hasta que la validación pase.

Analogía: la lista de control de una obra de construcción. Si encargas una remodelación y le dices al constructor "avísame cuando termines", es probable que dé por terminada la obra con detalles sin resolver que notarás al mudarte. Si antes de iniciar le entregas una lista de control objetiva ("verificar que todos los tomacorrientes tengan energía, comprobar la nivelación de los pisos"), el constructor validará cada punto él mismo y corregirá los fallos antes de entregarte la obra. La prueba ejecutable es esa lista de control para Claude.

¿Qué recursos sirven como método de validación? La documentación oficial lista los siguientes:

• Suites de pruebas unitarias (el recurso ideal, reporta de inmediato el estado)
• Códigos de salida de compiladores (validación de sintaxis y tipos)
• Herramientas de linter (estilo y convenciones)
• Scripts de comparación de salidas esperadas
• Capturas de pantalla del navegador para interfaces de usuario (visto en el artículo 17)

¿Cómo estructurar esto en tus instrucciones? La documentación oficial proporciona ejemplos comparativos:

Escenario	❌ Sin validación	✅ Con método de validación
Desarrollo de funciones	"Crea una función para validar correos electrónicos"	"Crea la función validateEmail. Casos de prueba: user@example.com es verdadero, invalid es falso, user@.com es falso. Ejecuta las pruebas al finalizar para confirmar."
Diseño de UI	"Mejora el diseño del panel de control"	"Implementa el diseño de esta pantalla [adjuntar imagen]. Al terminar, toma una captura, compárala con el diseño original y corrige las desviaciones."
Corrección de compilación	"La compilación está fallando"	"La compilación falla con este error: [adjuntar log]. Corrígelo y valida que la compilación termine con éxito. Resuelve el origen, no ocultes la alerta."

Observa la diferencia: las instrucciones de la derecha proveen un comando o criterio que el agente puede ejecutar y leer para validar el estado de su propio trabajo.

Puedes graduar el nivel de control según la criticidad de la tarea:

Nivel de control	Implementación	Escenario de uso
Por instrucción	Indica en el prompt: "ejecuta las pruebas y corrige hasta que pasen"	Tareas cotidianas de desarrollo local
Por sesión	Configura el objetivo de la sesión usando /goal	Para mantener un enfoque constante en un criterio de aceptación
Automatizado	Configura ganchos (Hooks) de detención en settings.json	Para asegurar la calidad antes de commits de forma desatendida (Artículo 33)

Para iniciar, aplica el nivel básico: añade siempre al final de tus instrucciones la indicación de ejecutar la suite de pruebas o el comando de compilación para validar los cambios.

Evita también la práctica de "ocultar la alerta en lugar de resolver el origen": no permitas que el agente solucione advertencias de tipos añadiendo declaraciones genéricas de escape (como any en TypeScript) o comentando líneas de código para que la compilación pase. Especifica siempre en tus instrucciones: "Resuelve el origen del error, no ocultes la alerta."

Además, exige evidencias del resultado de la prueba:

Pida a Claude que muestre evidencias del resultado: logs de salida de la prueba, comandos ejecutados con sus respuestas o capturas de pantalla del cambio.

Revisar las evidencias que presenta en la conversación es más rápido que ejecutar los comandos tú mismo, y te da la seguridad de que el cambio fue validado.

💡 Resumen rápido: Proporciona a Claude un método de validación ejecutable (pruebas, compilación o capturas) para que verifique y corrija su trabajo de forma autónoma, liberándote de actuar como revisor manual. Añade al final de tus instrucciones: "ejecuta las pruebas para validar."

---

03 Regla 2: Analiza, planifica y luego programa

La segunda regla previene las desviaciones en la lógica del código.

Pedirle a Claude que programe de inmediato suele resultar en código complejo que resuelve el problema equivocado. Separa la fase de análisis y diseño de la fase de escritura de código.

La documentación oficial sugiere estructurar el desarrollo en un flujo iterativo de cuatro fases:

Este diagrama representa el flujo de trabajo sugerido: a la izquierda, las fases de análisis y diseño conceptual; a la derecha, la fase de programación física del código y su confirmación. La transición se marca al salir de Plan Mode.

¿Por qué separar el diseño de la programación? Sigue la misma lógica que con un programador en prácticas: no le pedirías que modifique el módulo de base de datos el primer día sin antes pedirle que lea el código actual, identifique las dependencias y te explique su plan de acción (fase de análisis y diseño). Una vez que apruebes su propuesta, procede con la edición. Claude funciona de la misma manera: el Plan Mode (modo de planificación, visto en el artículo 35) está diseñado para leer archivos y planificar sin alterar el repositorio.

En la fase de análisis, utiliza Plan Mode para explorar el código base:

Analiza el directorio src/auth para comprender cómo gestionamos las sesiones de usuario. Identifica dónde se administran las variables de entorno de seguridad.

El agente investigará y te presentará su análisis sin modificar tus archivos. Posteriormente, pídele que proponga el diseño técnico:

Quiero integrar autenticación por Google OAuth. ¿Qué archivos requieren modificación? Explícame el flujo de datos propuesto y genera una planificación de pasos.

Si el plan propuesto tiene desvíos, puedes editar el plan directamente en tu editor (presionando Ctrl+G en la terminal) para reorientar el diseño. Una vez de acuerdo, sal de Plan Mode y autoriza la programación de la solución, integrando la validación del código.

Sin embargo, la documentación oficial aclara que Plan Mode no es necesario en todas las tareas:

Para tareas acotadas y de alcance directo (como corregir fallos ortográficos, añadir un log o renombrar una variable), pida al agente que ejecute la modificación de forma directa.

La regla de decisión provista por la documentación es simple:

Si puede describir el diff de cambios en una sola frase, omita la planificación.

Para tareas puntuales como renombrar una variable, agregar un log de depuración o corregir un texto, inicia la programación de forma directa. Si la tarea involucra un componente que no has analizado, requiere modificar múltiples archivos o no tienes clara la solución, inicia siempre en Plan Mode para estructurar el diseño primero.

💡 Resumen rápido: Para cambios extensos, de múltiples archivos o lógica no explorada, analiza y diseña en Plan Mode antes de programar; para cambios simples que defines en una frase, realiza la edición de forma directa.

---

04 Regla 3: Sé específico en las instrucciones

Esta regla es la clave para evitar los commits incomprensibles y las modificaciones no deseadas.

A mayor especificidad en tu instrucción, menor probabilidad de desviaciones y retrabajo. Claude interpreta el contexto, pero no puede leer tu mente.

Identificar los archivos involucrados, establecer límites de diseño y dar ejemplos de referencia optimiza la respuesta del agente. La documentación detalla ejemplos de cómo aplicar especificidad:

Criterio	❌ Instrucción vaga	✅ Instrucción específica
Establecer límites	"Añade pruebas para foo.py"	"Escribe pruebas unitarias para foo.py. Cubre los casos límite de usuario desconectado y evita el uso de mocks."
Indicar referencias	"¿Cómo funciona la API de ExecutionFactory?"	"Analiza el historial de commits de ExecutionFactory para comprender qué decisiones de diseño definieron su API actual."
Imitar patrones	"Añade un widget de calendario"	"Analiza cómo está estructurado el widget HotDogWidget.php en el proyecto. Imita ese patrón de diseño para crear un widget de calendario que admita selección de meses, sin añadir bibliotecas externas."
Detallar síntomas	"Corrige el error de login"	"Los usuarios reportan fallos al iniciar sesión tras expirar el token de sesión. Revisa la lógica en src/auth/ enfocándote en la renovación del token. Escribe una prueba que replique el fallo y corrígelo."

La columna derecha acota el alcance: define qué código analizar, qué casos probar, qué archivos usar de referencia y qué comportamiento se espera al finalizar.

La regla de "imitar patrones" es muy útil: si pides "agrega una función de exportación a CSV", el agente la programará con su lógica general. Si en su lugar indicas: "Analiza cómo se realiza la exportación de datos en export_helper.ts e imita ese patrón de diseño para estructurar la exportación", el código resultante será consistente con el estilo del repositorio y utilizará las mismas bibliotecas de tu proyecto, previniendo el retrabajo. Indicar un archivo de referencia en tu repositorio es más efectivo que describir detalladamente la arquitectura deseada.

Excepción de uso de instrucciones generales descrita en la documentación:

Las instrucciones abiertas o generales son de utilidad durante la fase de exploración para descubrir aspectos del código base.

Instrucciones del tipo: "¿Qué mejoras aplicarías a este módulo?" permiten al agente sugerir refactorizaciones o identificar fallos de diseño que no habías considerado en el código inicial. Usa instrucciones generales para la fase de exploración y adopta la máxima especificidad para la programación.

Acciones complementarias: proveer el contexto necesario

Facilita los datos y archivos necesarios de forma explícita utilizando estas herramientas:

• Menciona archivos con @: escribe la arroba en tu cuadro de entrada para seleccionar el archivo exacto que deseas que lea Claude antes de responder.
• Adjunta imágenes y capturas: copia y pega imágenes de errores o capturas de diseño directamente en la sesión para que las analice de forma visual (visto en el artículo 17).
• Proporciona URLs de API o documentación: pega las direcciones web de referencia directamente en la conversación (puedes agregarlas a la lista de autorización automática para facilitar el acceso).
• Envía datos mediante tuberías (pipes): usa cat error.log | claude en tu terminal para alimentar información de logs directamente al agente.
• Delega la búsqueda de información: indícale "busca el método de validación de contraseñas usando grep o mcp" para que localice los archivos necesarios de forma autónoma.

💡 Resumen rápido: Escribe instrucciones específicas definiendo los archivos, límites, referencias de diseño y el comportamiento esperado al finalizar. Usa instrucciones generales solo en fases de exploración y proporciona el contexto de soporte con @, capturas de pantalla o URLs.

---

05 Regla 4: Mantén el archivo CLAUDE.md conciso y ordenado

La optimización de CLAUDE.md es fundamental para el uso de contexto del agente. En el artículo 18 explicamos su sintaxis y ubicación; aquí nos enfocamos en su densidad de contenido: la brevedad es clave.

Recuerda el propósito de CLAUDE.md: es la guía de estilo y comandos que el agente lee de forma automática al iniciar cada conversación, registrando la información que no se puede deducir leyendo el código.

Analogía: la hoja de notas que dejas en el servidor para el técnico de guardia. Escribes notas esenciales como: "el servidor se reinicia a las 3:00, no te alarmes" o "el servicio A requiere permisos de administrador". Si la hoja contiene solo esas tres directrices críticas, las leerá y aplicará de inmediato. Si en su lugar pegas el manual completo del servidor de cien páginas en la pared, el técnico no lo leerá por falta de tiempo y omitirá las reglas críticas. CLAUDE.md es esa hoja de notas: debe ser lo suficientemente corto para que cada línea sea leída en cada sesión.

La advertencia de la documentación oficial es estricta:

Sea conciso. Para cada línea, pregúntese: "¿Si elimino esto, se incrementará la probabilidad de que Claude cometa un error?". Si la respuesta es no, elimínela. Un archivo CLAUDE.md extenso causará que Claude ignore tus instrucciones en la conversación.

Evita caer en estas malas prácticas de sobredimensionamiento: escribir explicaciones sobre la arquitectura conceptual del proyecto (las cuales puede deducir analizando el código) o registrar especificaciones de diseño temporales que solo usarás en una tarea (muévelas a un archivo de especificaciones SPEC o agrégalas a una Skill, como vimos en el artículo 26). Al remover el contenido redundante, el agente asimilará y respetará las directrices del proyecto de manera más efectiva.

La documentación oficial provee una guía de qué contenido registrar en CLAUDE.md:

✅ Contenido recomendado	❌ Contenido redundante
Comandos de consola específicos que no se pueden deducir	Información que el agente deduce leyendo el código
Reglas de estilo de código que difieren del estándar de la comunidad	Reglas de estilo estándar del lenguaje
Comandos para ejecutar la suite de pruebas del proyecto	Documentación de API extensa (reemplázala por URLs de referencia)
Convenciones de commits y de ramas del repositorio	Información dinámica del proyecto sujeta a cambios frecuentes
Decisiones de arquitectura específicas de la solución	Manuales generales de programación de lenguajes
Variables de entorno requeridas para el inicio	Descripciones de la estructura de archivos del repositorio

La regla para identificar si una directriz es redundante es: si Claude la asimila de forma natural leyendo el código o es una convención estándar del lenguaje, remuévela del archivo.

Recomendaciones para optimizar el archivo:

• Usa términos imperativos de énfasis como IMPORTANT o YOU MUST para resaltar reglas críticas (por ejemplo: IMPORTANT: No modifique los archivos de migración de base de datos existentes).
• Enlaza documentación externa con la sintaxis @ (por ejemplo: Guía de publicación: @docs/release-guide.md) para mantener el archivo CLAUDE.md limpio y permitir que Claude lea las guías secundarias solo si la tarea lo requiere.

Si el agente empieza a omitir reglas que están en CLAUDE.md, reduce su longitud; si te pregunta por directrices que están escritas en el archivo, refina su redacción para que sea más clara.

💡 Resumen rápido: Mantén CLAUDE.md lo más conciso posible, conservando únicamente comandos y convenciones críticas que no se deduzcan del código. Evalúa cada línea preguntándote si su eliminación causará fallos; si no es así, elimínala.

---

06 Regla 5: Reorienta al agente ante desviaciones de inmediato

Esta regla define el control sobre el flujo de la conversación en la sesión.

Interrumpe la ejecución del agente si notas que se desvía del objetivo; no esperes a que finalice una propuesta incorrecta para corregirlo. El flujo es interactivo y reversible.

La colaboración requiere supervisión en tiempo real. Si Claude propone una solución incorrecta, reorientarlo en el momento es más rápido que esperar a que modifique múltiples archivos para luego revertir los cambios. La terminal ofrece herramientas para reorientar el flujo:

Acción deseada	Herramienta a usar	Aplicación práctica
Detener el proceso	Presionar Esc en la consola	Si notas que el agente está leyendo directorios fuera de alcance o inicia una edición incorrecta
Revertir cambios de la sesión	/rewind o doble Esc	Para restaurar el estado del código e historial si una refactorización extensa no funcionó (Artículo 37)
Deshacer la última edición	Decirle: "deshaz el último cambio"	Para revertir de forma rápida una modificación de archivo puntual
Reiniciar la conversación	Comando /clear en la sesión	Para limpiar la memoria del contexto antes de iniciar una tarea diferente

Adopta la siguiente regla de oro compartida por desarrolladores experimentados:

Si tienes que corregir al agente más de dos veces sobre el mismo problema en una conversación, la memoria de contexto ya está saturada con intentos fallidos. Ejecuta /clear para reiniciar el contexto e inicia una conversación limpia detallando el aprendizaje obtenido en las iteraciones anteriores.

Es decir: si el tercer intento de corrección falla, no intentes una cuarta corrección en el mismo contexto. La memoria de trabajo de la conversación contendrá el registro de las soluciones fallidas previas y el agente continuará sugiriendo alternativas erróneas. Reinicia la sesión con /clear y escribe un prompt estructurado como: "Queremos corregir el bug de renovación de tokens. Evita aplicar el cambio en el middleware (ya intentamos esa opción y causa errores de concurrencia); enfócate en interceptar la llamada en el cliente HTTP." Este prompt en un contexto limpio resolverá la tarea en pocas iteraciones.

Estrategias adicionales para optimizar el contexto:

• Delega investigaciones extensas a subagentes: usa la instrucción "asigna un subagente para buscar..." para que el análisis de código o la lectura de logs se realice en una conversación independiente y devuelva solo la síntesis, manteniendo el contexto principal libre de código redundante (Artículo 23).
• Asigna nombres descriptivos a las sesiones: usa claude --resume y asocia nombres como refactor-db a las conversaciones para retomar el trabajo con facilidad, organizando los flujos como si fueran ramas de desarrollo.

💡 Resumen rápido: Usa Esc para detener al agente de inmediato si notas desvíos y /rewind para restaurar el estado del código. Si realizas más de dos correcciones sin éxito en el mismo chat, ejecuta /clear y abre una sesión limpia detallando el enfoque correcto.

---

07 Regla 6: Paraleliza el trabajo una vez dominado el flujo

Una vez que domines la interacción con una sesión individual, puedes incrementar tu productividad escalando el desarrollo en paralelo (visto en los artículos 41 y 44).

Asegura la precisión del flujo de trabajo en una conversación individual antes de paralelizar. Multiplicar sesiones sin control incrementa la complejidad del proyecto.

Estrategias recomendadas para escalar la ejecución:

• Sesiones en paralelo con worktrees: ejecuta múltiples conversaciones asignando a cada una un worktree independiente de git. Esto evita que los cambios de las diferentes sesiones sobrescriban los mismos archivos y permite desarrollar características en paralelo de forma segura.
• Flujos de revisión cruzada (Writer / Reviewer): asigna la programación de código a la conversación A, e inicia una conversación B independiente para que audite los cambios. Dado que la conversación B tiene una memoria de contexto limpia de las decisiones de programación, evaluará el código de forma objetiva detectando fallos lógicos con mayor precisión.
• Procesamiento desatendido por lotes: usa el comando claude -p en scripts de consola para aplicar modificaciones o análisis secuenciales a múltiples archivos de forma automática, especificando los permisos y herramientas a utilizar.
• Auditoría final automatizada: al concluir tareas complejas de forma desatendida, ejecuta la herramienta /code-review para que un subagente evalúe las modificaciones locales frente a los requerimientos antes de registrar el commit.

La documentación oficial advierte sobre el exceso de celo de los revisores automáticos:

Un revisor de código al que se le instruye buscar fallos siempre reportará observaciones, incluso si la lógica del código es correcta. Evite corregir sugerencias estéticas que promuevan la sobreingeniería del código.

Enfoca las revisiones del agente en la detección de fallos de lógica y seguridad, tratando las observaciones de estilo como sugerencias opcionales para evitar complejidades innecesarias en el código base.

💡 Resumen rápido: Asegura el flujo de trabajo individual antes de paralelizar. Usa worktrees para coordinar sesiones en paralelo, implementa flujos de revisión cruzada (Writer/Reviewer) en contextos independientes y procesa tareas por lotes con claude -p, controlando la sobreingeniería en las revisiones.

---

08 Puntos de control en la comunicación con el agente

Presentamos recomendaciones breves y prácticas para optimizar la interacción verbal o escrita con Claude.

1. Trátalo como a un programador experimentado del equipo

Al unirte a un repositorio nuevo o analizar código de terceros, pregúntale a Claude de la misma manera en que lo harías con un programador veterano del proyecto. No requieres de estructuras o términos especiales; realiza preguntas directas sobre el diseño:

¿Cómo está estructurado el sistema de logs del proyecto?
¿Qué pasos debo seguir para añadir un nuevo endpoint en esta API?
¿Qué propósito tiene la declaración async en la línea 124 del archivo de base de datos?
¿Por qué este módulo invoca a la función foo() en lugar de bar() en la inicialización?

Esta es una forma rápida de familiarizarse con la arquitectura del código base.

2. Deja que Claude te entreviste para tareas complejas

Antes de iniciar desarrollos extensos, pídele al agente que te entreviste para definir la especificación técnica. Esto te ayudará a identificar requerimientos de diseño omitidos antes de escribir código:

Quiero desarrollar la característica [descripción rápida]. Utiliza la herramienta AskUserQuestion para entrevistarme sobre los detalles técnicos, de interfaz, casos límite y decisiones de diseño que requieran definición. Genera al terminar el archivo SPEC.md con el resumen.

El tiempo dedicado a definir y refinar la especificación técnica evita reescrituras complejas de código durante el desarrollo.

3. Exige evidencias, no confirmaciones descriptivas

Si el agente reporta que una tarea ha sido resuelta o que las pruebas pasan, indícale: "Muestra la salida de consola de la prueba ejecutada" o "toma una captura de pantalla del resultado". Solicitar evidencias concretas evita dar por buenas modificaciones que no resuelven la lógica de forma real.

💡 Resumen rápido: Pregúntale de forma directa como a un programador experimentado del proyecto; realiza entrevistas de requerimientos en tareas complejas para generar especificaciones de diseño; y exige evidencias concretas (logs, capturas) en lugar de aceptar confirmaciones de texto.

---

09 Ejercicio práctico: comparación del alcance de las instrucciones

Realizaremos un ejercicio básico de comparación: observar el resultado de una instrucción vaga frente a una instrucción específica que define las reglas de aceptación y un método de validación.

Requisitos: Una carpeta vacía en tu máquina local y una sesión activa de Claude Code.

Paso 1: Crear un directorio de prueba e iniciar la sesión

mkdir mi-practica-prompt && cd mi-practica-prompt && claude

Paso 2: Enviar una instrucción vaga

En la sesión, escribe:

Programa una función para comprobar la fortaleza de contraseñas.

Resultado esperado: Claude generará la función (por ejemplo, checkPassword) en un bloque de código. Definirá los criterios de validación (longitud, caracteres especiales) a su criterio; probablemente no incluirá pruebas ni validará el comportamiento con ejecuciones de consola. Deja esta respuesta como referencia.

Paso 3: Limpiar el contexto y enviar una instrucción específica con método de validación

Limpia la conversación:

/clear

Escribe la instrucción aplicando las reglas de especificidad, límites de diseño y método de validación:

Crea la función isStrongPassword(pwd) en el archivo password.js.
Criterios de fortaleza: longitud mínima de 8 caracteres, al menos una letra mayúscula y al menos un número; debe cumplir las tres condiciones para considerarse segura.
Casos de prueba: 'Abc12345' debe devolver verdadero, 'abc12345' debe devolver falso (sin mayúscula) y 'Abcdefgh' debe devolver falso (sin número).
Al terminar de escribir la función, crea un script de prueba que valide estos tres casos de uso, ejecútalo y muéstrame el resultado de la salida de consola como evidencia.

Resultado esperado: Observarás tres diferencias claras en la respuesta:

1. La lógica de la función se ceñirá estrictamente a los criterios detallados.
2. Claude escribirá el código de pruebas, ejecutará la validación en la consola del sistema y reportará los resultados específicos de cada caso de prueba.
3. Dispondrás de evidencias del comportamiento correcto del código sin tener que interpretarlo manualmente.

Paso 4: Limpieza (opcional)

Sal de la sesión y remueve la carpeta de práctica:

cd .. && rm -rf mi-practica-prompt

Este ejercicio demuestra el beneficio de estructurar las instrucciones indicando los límites de diseño y definiendo un método de validación ejecutable, ahorrando tiempo de supervisión en tu desarrollo.

💡 Resumen rápido: El ejercicio práctico consta de cuatro pasos: crear carpeta de práctica → enviar instrucción vaga → limpiar con /clear y enviar instrucción específica con método de validación → comparar las diferencias en la precisión y evidencias del resultado.

---

10 Resumen de mejores prácticas

En este artículo hemos resumido las mejores prácticas de la documentación oficial y de desarrolladores experimentados para optimizar el uso de Claude Code.

Repasemos los puntos de control clave:

Escenario de desarrollo	Criterio a aplicar	Acción de ingeniería
Validación de cambios	Definir método de validación	Añade al prompt la indicación de ejecutar la suite de pruebas o compilar al finalizar para evitar la revisión manual
Diseño lógico	Separar análisis de programación	Usa Plan Mode para explorar código y definir especificaciones técnicas antes de editar archivos
Redacción de prompts	Mantener especificidad	Especifica archivos involucrados, límites de diseño, archivos de referencia y criterios de aceptación específicos
Guía del proyecto	Mantener CLAUDE.md conciso	Conserva únicamente comandos y convenciones críticas que no se deduzcan del código; documenta en enlaces externos
Gestión de la sesión	Reorientar y reiniciar	Usa Esc y /rewind ante desviaciones. Si realizas más de dos correcciones en el mismo chat, ejecuta /clear y abre un chat limpio
Escalado del flujo	Paralelizar con control	Usa worktrees para sesiones paralelas, Writer/Reviewer en contextos independientes y automatiza tareas repetitivas con claude -p

Ahora puedes:

• Optimizar el consumo de la memoria de contexto del agente aplicando criterios de brevedad.
• Diseñar instrucciones que definan métodos de validación autónomos y criterios de aceptación claros.
• Utilizar Plan Mode para estructurar soluciones y especificaciones técnicas antes de programar.
• Redactar y podar el archivo CLAUDE.md para conservar únicamente directrices críticas.
• Gestionar el flujo de la conversación deteniendo desvíos y reiniciando el contexto con /clear ante fallos recurrentes.
• Escalar tu flujo de desarrollo de forma segura utilizando sesiones en paralelo o revisiones cruzadas.

Adoptar estas prácticas te permite colaborar con Claude Code de forma fluida, manteniendo la consistencia de tu código base y un control de calidad efectivo.

---

El siguiente artículo es el 50 "Antipatrones: errores comunes de uso". Hemos detallado el flujo óptimo de trabajo; en el próximo artículo analizaremos la contraparte: las prácticas incorrectas recurrentes en el uso de Claude Code. Estudiaremos desvíos comunes como la acumulación excesiva de contexto en una sola sesión (kitchen sink), las directrices contradictorias en CLAUDE.md y la aprobación ciega de comandos sin validación, identificando sus síntomas y soluciones.

---

Lecturas recomendadas

• Inicialización de proyectos con /init
• Ejemplos prácticos del uso de Skills
• Estructura de equipos de agentes (Agent teams)