Antipatrones: errores comunes de uso

📚 Navegación de la serie: El artículo anterior 49 Mejores prácticas detalló los enfoques correctos en el uso de Claude Code. Este artículo aborda la contraparte: los errores comunes de uso (antipatrones). Con la misma herramienta, algunos desarrolladores logran resultados sobresalientes mientras otros experimentan dificultades; la diferencia no radica en el dominio de funciones avanzadas, sino en evitar los desvíos y malas prácticas más habituales. Analizaremos cada uno de ellos y explicaremos cómo corregirlos. El próximo artículo es 51 FAQ: resolución de problemas.

Al observar a quienes comienzan a utilizar Claude Code, se nota una coincidencia: los errores cometidos suelen ser idénticos. No son fallos aislados, sino un camino recurrente en el que se cae en las mismas trampas de forma sucesiva.

Estos desvíos no se deben a la capacidad técnica del usuario, sino a brechas de concepto. Al no identificar el riesgo previo, es natural cometer el error; una vez identificado, se puede evitar con facilidad. Este artículo expone los siete antipatrones (prácticas que parecen correctas pero introducen ineficiencias o riesgos) más comunes, explicando cómo se presentan, por qué causan problemas y cómo reemplazarlos por los enfoques adecuados.

Considera este artículo como la guía de "los errores de conducción más comunes" del examen práctico: conocer de antemano dónde se suelen perder puntos te ayudará a conducir con mayor seguridad y eficiencia.

Al terminar este artículo, obtendrás:

• Fichas de identificación para los siete antipatrones principales, permitiéndote detectar si estás cometiendo alguno.
• Ejemplos comparativos Antes / Después (Before / After) para corregir la interacción.
• Una tabla de referencia rápida para identificar por qué decae la precisión del agente.
• Referencias cruzadas a los artículos previos para profundizar en las soluciones.
• Un ejercicio práctico de diagnóstico y corrección sobre un escenario real.

---

01 Concepto: por qué las malas prácticas arruinan la interacción

Para empezar, la conclusión: cuando Claude Code no responde adecuadamente, en el 90% de los casos se debe a que la interacción ha caído en un antipatrón de uso, y no a limitaciones de la herramienta.

Muchos usuarios afirman con desilusión "esta IA no es tan útil" o "tardo menos programando yo mismo". Al analizar sus sesiones de trabajo, los fallos se concentran en las mismas prácticas: redactar instrucciones extensas y ambiguas, omitir o saturar el archivo CLAUDE.md, mantener una sola conversación activa para múltiples tareas de desarrollo o aceptar las respuestas del agente sin validación alguna.

Analogía: la lista de faltas comunes en un examen de conducción. Al prepararte para el examen práctico, el instructor no se limita a enseñarte a acelerar, sino que te entrega una hoja con las faltas comunes: no usar las luces direccionales, pisar las líneas continuas, apagar el motor en marcha o no revisar los espejos retrovisores. Esa lista te previene de cometer los fallos que causaron la reprobación de otros. Este artículo es esa lista de faltas para Claude Code.

¿Por qué son tan comunes estos errores? Porque parecen lógicos a primera vista:

• "Si detallo todas las tareas en un solo prompt, las resolverá de una sola vez." (Parece eficiente).
• "Si le pido que lea todo el repositorio al inicio, tendrá un mejor panorama del proyecto." (Parece lógico).
• "Si describo la arquitectura al detalle en CLAUDE.md, recordará mejor las reglas." (Parece correcto).

El riesgo reside precisamente en que parecen lógicos. Estas ideas pueden funcionar en otros contextos, pero bajo el diseño técnico de Claude Code (con límites en el contexto de conversación, necesidad de validación ejecutable y vulnerabilidades ante inyecciones de código), producen el resultado opuesto. Analizaremos cada uno de los siete antipatrones en las siguientes secciones.

Comenzamos con una tabla de referencia general:

#	Antipatrón (Síntoma)	Por qué causa problemas	Artículo de referencia
1	Redactar múltiples requerimientos en un solo prompt	El agente se desvía en la lógica o realiza cambios incompletos	Artículo 15
2	Omitir o saturar de información el archivo CLAUDE.md	Causa que el agente ignore las reglas de diseño o repita consultas	Artículo 18
3	Mantener la misma conversación activa de forma indefinida	El contexto se satura y el agente pierde precisión	Artículo 19
4	Usar a Claude como motor de búsqueda y aceptar sus respuestas sin validar	Causa que programes con API inexistentes creadas por "alucinación"	Artículo 15, Artículo 21
5	No definir métodos de validación ejecutables	Limita la confirmación de la tarea a una evaluación visual subjetiva	Artículo 49
6	Activar el modo de escape de permisos bypassPermissions por comodidad	Expone el sistema local a inyecciones de código y comandos destructivos	Artículo 20, Artículo 21
7	Solicitar investigaciones sin acotar el alcance	Satura la memoria de contexto al leer archivos innecesarios	Artículo 19, Artículo 23

Estos errores no ocurren de forma aislada, sino que suelen retroalimentarse en un círculo vicioso:

Este esquema representa la retroalimentación de los errores: redactar prompts ambiguos (Antipatrón 1) o solicitar investigaciones sin límites (Antipatrón 7) satura la memoria del contexto, causando que el agente empiece a cometer fallos y a responder de forma errática (efecto del Antipatrón 3). Esto provoca que pierdas la confianza en el agente, omitas proveerle pruebas unitarias (Antipatrón 5) y optes por desactivar las confirmaciones de seguridad (Antipatrón 6) para ahorrar clics, incrementando la ineficiencia.

El punto de quiebre de este ciclo se encuentra abajo a la derecha: segmentar las tareas, limpiar el contexto, definir métodos de validación y acotar las investigaciones. Esto restablece la eficiencia de la interacción.

💡 Resumen rápido: Si experimentas ineficiencias con Claude Code, revisa tu metodología de trabajo. Los antipatrones comunes se retroalimentan creando un flujo de trabajo ineficiente; identificarlos y aplicar las correcciones correspondientes restablece el rendimiento.

---

02 Antipatrón 1: Redactar múltiples requerimientos en un solo prompt

Síntoma: Escribes una instrucción extensa que reúne varios objetivos: "Modifica el inicio de sesión para usar OAuth, corrige el fallo del endpoint de usuarios, ajusta los estilos del botón de la página de inicio y añade las pruebas correspondientes". Presionas enter esperando que resuelva todas las tareas a la vez.

Resultado: El agente realiza modificaciones parciales en cada punto sin completar ninguna tarea con precisión, u omite resolver el requerimiento que más te interesaba para enfocarse en el ajuste de estilos estéticos.

Por qué causa problemas: Si presentas múltiples requerimientos mezclados en una sola instrucción, el agente no puede priorizar el flujo lógico de desarrollo. Como vimos en la sección de Planificación del artículo 48, programar directamente sin segmentar la tarea incrementa la probabilidad de desarrollar soluciones que no se ajustan a las especificaciones deseadas.

Analogía: dar una lista de tareas inconexas a un electricista. Le dices: "Repara el cortocircuito del baño, instala un tomacorriente en la cocina, cambia las luces de la sala y limpia el jardín". El electricista resolverá las tareas más sencillas (cambiar luces, limpiar jardín) y postergará o resolverá de forma deficiente la tarea crítica del cortocircuito por falta de foco. Las tareas deben delegarse y validarse una a la vez.

Solución: Estructura la interacción en dos niveles:

• Para tareas pequeñas de alcance directo (renombrar variables, corregir textos): descríbelas de forma directa en la sesión, sin necesidad de planificar.
• Para desarrollos complejos que involucran múltiples archivos: cambia a Plan Mode (modo de planificación, artículo 35) para estructurar el diseño primero, y valida la propuesta antes de proceder con la programación.

Enfoca la sesión en resolver una sola tarea a la vez. Compara la interacción en esta tabla:

❌ Enfoque incorrecto (Antes)	✅ Enfoque correcto (Después)
Enviar un prompt con múltiples tareas mezcladas ("OAuth, estilos, corregir bug, pruebas")	Iniciar con una sola tarea específica: "Quiero implementar Google OAuth en el inicio de sesión. No modifiques otros archivos y preséntame el plan primero."
Dejar el alcance de las tareas ambiguo	Definir los archivos involucrados, el comportamiento esperado y el método de validación de forma específica.
Iniciar la programación de inmediato en cambios estructurales	Planificar el diseño en Plan Mode antes de autorizar las modificaciones.
Aceptar un resultado parcial e incompleto	Validar y dar cierre a la tarea actual antes de iniciar el siguiente requerimiento.

Evita la tentación de usar a Claude como un "buzón de deseos" esperando que resuelva todo de golpe. Claude es un agente de ejecución iterativa que requiere guías precisas paso a paso para ser efectivo.

💡 Resumen rápido: Segmenta tus requerimientos y delega una sola tarea a la vez. Usa Plan Mode para estructurar el diseño de las tareas complejas antes de programar, evitando mezclar requerimientos en un solo prompt (Artículos 15 y 35).

---

03 Antipatrón 2: Omitir o saturar el archivo CLAUDE.md

Este error representa dos extremos opuestos de la misma práctica de configuración.

Caso A: Omitir el archivo CLAUDE.md

Síntoma: En cada conversación nueva debes recordar al agente las mismas convenciones del entorno: "usamos pnpm en lugar de npm", "las pruebas se ejecutan con este comando", "los commits deben tener este prefijo". Al abrir un nuevo chat, debes repetir las directrices desde el principio.

Por qué causa problemas: Claude inicia cada sesión sin memoria del chat anterior. Si omites configurar CLAUDE.md (artículo 18), obligas al agente a asumir el entorno por su cuenta, introduciendo errores de sintaxis o utilizando manejadores de paquetes no compatibles con tu proyecto.

Caso B: Escribir un CLAUDE.md demasiado extenso (saturación)

Síntoma: Con el fin de evitar que el agente olvide directrices, registras en CLAUDE.md la historia de la empresa, el manual completo del Framework, las guías de estilo estándar del lenguaje y descripciones línea por línea de la estructura del repositorio, acumulando cientos de líneas.

Resultado: El agente comienza a ignorar las reglas específicas que definiste y su precisión decae. La documentación oficial lo advierte:

Un archivo CLAUDE.md extenso causará que Claude ignore tus instrucciones en la conversación.

Por qué causa problemas: El contenido de CLAUDE.md se carga en la memoria del contexto al iniciar cada conversación. Un archivo extenso consume espacio útil de tu contexto e introduce ruido, diluyendo la prioridad de las reglas de desarrollo críticas del proyecto.

Analogía: la hoja de instrucciones de la oficina. Si dejas una hoja con tres notas críticas en la pared ("la clave del servidor cambió, la impresora requiere papel especial, avisar al salir"), los empleados la leerán al instante. Si en su lugar dejas un manual de operaciones de trescientas páginas, nadie lo leerá y omitirán las instrucciones críticas. La brevedad asegura que la regla sea leída.

Solución: Aplica el criterio de exclusión oficial:

Pregúntese para cada línea si su eliminación causará fallos en el agente; si no es así, remuévala del archivo.

Compara la organización de la información:

✅ Contenido para CLAUDE.md	❌ Contenido a remover
Comandos específicos del entorno que no se deducen del código	Convenciones estándar del lenguaje o de la comunidad
Estilos de desarrollo del proyecto diferentes a la convención habitual	Documentación extensa de API (sustitúyela por enlaces web)
Criterios específicos para la ejecución de pruebas	Explicaciones conceptuales del diseño del software
Reglas de commits y flujo de ramas del repositorio	Descripciones estáticas del directorio de archivos

Si tienes guías de desarrollo extensas que solo usas en tareas específicas, no las registres en CLAUDE.md; diseña una Skill (artículo 26) para que el agente las cargue únicamente cuando la tarea lo requiera.

💡 Resumen rápido: Registra en CLAUDE.md únicamente comandos y reglas críticas del entorno que no se puedan deducir del código. Mantén el archivo conciso para evitar saturar el contexto, y delega guías extensas a Skills (Artículos 18 y 26).

---

04 Antipatrón 3: Mantener la misma conversación activa indefinidamente

Síntoma: Inicias un chat en la mañana para depurar un error, resuelves el problema y continúas la conversación preguntándole sobre la sintaxis de un script diferente, para luego pedirle que programe una nueva característica en el mismo chat. Al final del día, notas que el agente responde de forma lenta, confunde variables y olvida las directrices que le diste al inicio del día.

Por qué causa problemas: Este error se divide en dos desvíos de gestión de contexto detallados por la documentación oficial:

Conversaciones multipropósito (kitchen sink session). Ocurre cuando inicias una tarea y luego introduces consultas o modificaciones inconexas en el mismo chat, para después volver al objetivo inicial. El contexto se llena de información irrelevante que desvía la atención del agente.

Acumulación de intentos fallidos. Si corriges al agente repetidamente ante un error de lógica en el mismo chat, la documentación oficial señala:

Si corrige a Claude más de dos veces sobre el mismo problema, el contexto se saturará de alternativas fallidas.

El agente leerá las propuestas incorrectas previas guardadas en el historial e insistirá en variantes de la misma lógica errónea.

Analogía: limpiar la mesa de trabajo entre tareas. Si cocinas un platillo, limpias la mesa y retiras los residuos antes de preparar el siguiente. Si dejas los vegetales cortados y los residuos de la mañana en la mesa para preparar la cena, te quedarás sin espacio y mezclarás los ingredientes. El comando /clear limpia tu mesa de conversación.

Solución: Aplica las herramientas de gestión de contexto (artículo 19):

• Si cambias de objetivo o tarea de desarrollo, ejecuta /clear para limpiar por completo el contexto de conversación e iniciar con la mente en blanco.
• Si el desarrollo es extenso y quieres mantener el hilo de la tarea, ejecuta /compact para resumir el historial y liberar espacio útil de memoria.
• Si una corrección lógica falla por tercera vez, no insistas en la misma sesión: ejecuta /clear y abre un chat limpio resumiendo el enfoque correcto y las alternativas que debes evitar.

Escenario	❌ Práctica incorrecta (Antes)	✅ Práctica correcta (Después)
Cambio de tarea de desarrollo	Continuar en el chat actual	Ejecutar /clear antes de iniciar la nueva tarea
Sesión de desarrollo extensa	Mantener el historial completo	Ejecutar /compact para consolidar el contexto
Tercer intento de corrección fallido	Insistir en el mismo chat	Limpiar con /clear e iniciar una sesión con las reglas refinadas

💡 Resumen rápido: Limpia la conversación con /clear si cambias de tarea o si una corrección lógica falla por tercera vez; usa /compact en sesiones extensas para mantener el contexto libre de ruido (Artículo 19).

---

05 Antipatrón 4: Usar a Claude como motor de búsqueda y aceptar sus respuestas sin validar

Síntoma: Utilizas la sesión de Claude para consultar documentación reciente de un framework ("¿cómo configuro el routing en Next.js 15?") o la especificación de un módulo poco común. Copias el código propuesto de forma directa en tu editor sin verificar su validez.

Por qué causa problemas: Este desvío introduce dos niveles de fallos en el código:

La información de los modelos tiene límites de actualización temporal. Los frameworks y bibliotecas cambian sus API de forma frecuente; si preguntas por especificaciones recientes, el modelo podría no tener el dato en su entrenamiento y sugerir convenciones antiguas.

El modelo genera respuestas coherentes pero potencialmente inexistentes (alucinación). Si el modelo no tiene la certeza de un parámetro o nombre de clase, tiende a estructurar una respuesta con nombres lógicos que no existen en la biblioteca real, causando fallos de importación en la compilación.

Analogía: preguntar una dirección a un peatón que no conoce la zona pero es muy cortés. Te dará indicaciones detalladas de forma segura para no decepcionarte, enviándote a una calle inexistente. Aceptas sus indicaciones y caminas sin verificar el mapa, perdiéndote en el camino. Debes validar la ruta con fuentes oficiales.

Solución: Modifica la interacción de la siguiente manera:

Proporciona herramientas de consulta de datos externos. Si requieres información de API recientes o documentación web, indícale al agente que use la herramienta de consulta web WebSearch o conecta un servidor MCP oficial (artículo 22) para acceder a la fuente de datos real.

Valida las propuestas antes de integrarlas. Exige evidencias objetivas de la validez del código:

Pida a Claude que muestre evidencias objetivas del resultado de la validación, como la salida de consola de comandos ejecutados en el sistema o capturas visuales.

Tipo de consulta	❌ Práctica incorrecta (Antes)	✅ Práctica correcta (Después)
Consulta de API de bibliotecas	"Dime cómo uso esta función" (Aceptas el texto generado)	"Busca en la documentación oficial usando WebSearch cómo está definida esta función e imita el patrón."
Validación de código propuesto	Copiar el código al proyecto sin verificar	Pedirle que escriba una prueba unitaria rápida para confirmar que el método propuesto responda correctamente.
Evidencia de ejecución	Aceptar la frase "el código funciona"	Solicitar que muestre el log de salida de la prueba ejecutada en la terminal.

💡 Resumen rápido: Claude no es un motor de búsqueda y puede generar información inexistente. Utiliza WebSearch o MCP para consultar datos externos reales y exige evidencias (logs de consola, pruebas) antes de aceptar las soluciones (Artículos 15, 21 y 22).

---

06 Antipatrón 5: No definir métodos de validación ejecutables

Síntoma: Le pides al agente que programe una función, revisas el código resultante en el chat, te parece correcto a nivel visual y procedes a registrar el commit. No ejecutas pruebas ni compilas el código para validar su lógica de negocio.

Por qué causa problemas: La documentación oficial destaca la consecuencia de esta omisión:

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.

El agente se detendrá al considerar visualmente terminada la tarea. "Parecer correcto" no garantiza que el código controle desbordamientos de datos, nulos o lógica de negocio específica. Delegar la validación al humano reduce la eficiencia de la sesión y propaga fallos al repositorio.

Analogía: un profesor de matemáticas que califica exámenes sin la hoja de respuestas. Debe revisar cada operación línea por línea de forma visual para detectar errores de cálculo, incrementando el tiempo de revisión y el riesgo de omitir fallos. Si cuenta con la hoja de respuestas (la prueba unitaria), califica el examen de forma inmediata y objetiva.

Solución: Proporciona siempre una validación que retorne un resultado objetivo de éxito o fallo.

Estructura tus prompts para que incluyan la validación al finalizar:

Tarea de programación	❌ Sin validación	✅ Con método de validación
Modificación de funciones	"Escribe la función de cálculo de interés"	"Implementa la función de cálculo de interés. Casos: entrada 100 devuelve 5, entrada 0 devuelve 0. Ejecuta las pruebas unitarias para validar."
Corrección de bugs	"Corrige el error de sesión"	"Corrige el error de sesión. Asegura la solución en la suite de pruebas y ejecuta 'npm test' para confirmar que no hay regresiones."
Control de excepciones	"Corrige la compilación"	"La compilación falla con este error [log]. Resuelve el origen del error, no ocultes la alerta de tipos, y valida con 'npm run build'."

Al añadir un método de validación ejecutable, Claude puede iterar de forma autónoma corrigiendo los errores que reporte la consola hasta que la prueba pase con éxito, entregándote código verificado.

💡 Resumen rápido: No confíes en revisiones visuales del código. Define siempre un método de validación ejecutable (pruebas unitarias, compilación, linter) para que el agente verifique la lógica de forma autónoma (Artículo 49).

---

07 Antipatrón 6: Activar el modo de escape de permisos por comodidad

Síntoma: Te resulta molesta la aparición de diálogos de confirmación de permisos para ejecutar comandos en el sistema, por lo que decides iniciar siempre con claude --dangerously-skip-permissions o activar de forma global bypassPermissions en tu configuración.

Por qué causa problemas: Esta opción elimina todas las barreras de seguridad de la sesión. A diferencia del modo automático auto (que evalúa los comandos a través de un modelo de clasificación para bloquear acciones críticas), bypassPermissions deshabilita todos los controles, exponiendo tu máquina a inyecciones de código. La documentación oficial lo advierte:

El modo bypassPermissions no ofrece protección contra inyecciones de instrucciones o comandos destructivos accidentales. Utilice el modo auto para auditorías de seguridad silenciosas.

Esto introduce dos riesgos en tu máquina local:

Ejecución de instrucciones maliciosas ocultas (prompt injection). Si el agente lee repositorios de terceros o comentarios de issues públicos que contengan instrucciones ocultas diseñadas para vulnerar el sistema, las ejecutará de forma directa en tu máquina al no tener controles de permisos activos (visto en el artículo 21).

Comandos destructivos accidentales. Si Claude interpreta de forma errónea una tarea de limpieza y propone un comando destructivo en el directorio equivocado, el comando se ejecutará al instante sin darte la oportunidad de cancelarlo.

Analogía: retirar la puerta de seguridad de tu casa para no usar llaves. Entras más rápido, pero permites que cualquier persona acceda a tu hogar sin restricciones.

Solución: Selecciona el nivel de confirmación adecuado para tu entorno (artículos 20 y 21):

• Para desarrollo cotidiano local: utiliza el modo de aceptación de edición de archivos (acceptEdits), que ejecuta modificaciones de código y comandos de archivos comunes sin confirmaciones, pero solicita aprobación ante comandos de consola externos o accesos fuera del directorio.
• Para automatizaciones desatendidas: utiliza el modo automático (auto), que evalúa la seguridad de los comandos de forma interna antes de autorizarlos.
• Si requieres omitir permisos por completo: hazlo únicamente dentro de contenedores aislados (devcontainer) o entornos de pruebas dedicados (VM), donde un comando destructivo o inyección no comprometa tu máquina principal.

Entorno de ejecución	❌ Opción insegura	✅ Opción recomendada
Máquina de trabajo local	Activar bypassPermissions global	Usar acceptEdits para agilizar las ediciones de código de forma segura
Tareas automatizadas en CI	Desactivar permisos en el host	Usar el modo auto o encapsular el proceso en un contenedor aislado
Ejecución de código de terceros	Correr sin restricciones de permisos	Mantener confirmaciones activas para auditar las llamadas a consola

💡 Resumen rápido: Evita desactivar las confirmaciones de seguridad en tu máquina local. Usa acceptEdits para programar con fluidez de forma segura, y reserva el modo bypassPermissions únicamente para entornos de ejecución aislados (Artículos 20 y 21).

---

08 Antipatrón 7: Solicitar investigaciones sin acotar el alcance

Síntoma: Escribes una instrucción general como: "Analiza el sistema de facturación y explícame cómo funciona", sin indicar directorios de inicio o alcances específicos. El agente empieza a abrir y leer decenas de archivos de forma sucesiva en el proyecto.

Por qué causa problemas: La documentación define este desvío como "búsqueda sin límites (infinite search)":

Solicitar investigaciones generales sin acotar el alcance causa que Claude lea decenas de archivos innecesarios, saturando rápidamente la memoria de contexto.

Cada archivo que lee se almacena en la memoria del contexto. Al leer múltiples archivos, el espacio disponible para planificar y programar se reduce, provocando que el agente comience a fallar o a omitir directrices en las siguientes interacciones de la sesión.

Analogía: pedir a un asistente que busque un recibo en la oficina sin indicarle el año. Revisará archivadores de los últimos diez años, acumulando cajas de documentos en tu mesa y dificultando tu espacio de trabajo. Si le indicas que busque en la carpeta del mes pasado, resolverá la tarea en minutos manteniendo tu mesa ordenada.

Solución: Acota el alcance de las consultas (artículos 19 y 23):

• Indica los directorios específicos a analizar: en lugar de "revisa el sistema de facturación", escribe: "analiza las clases de cobro en el directorio src/billing/services/".
• Delega el análisis a subagentes: usa la instrucción "asigna un subagente para analizar..." para que la lectura de archivos extensos se realice en un contexto independiente y devuelva únicamente el resumen a la conversación principal.

Objetivo de consulta	❌ Consulta abierta	✅ Consulta acotada
Comprender la base de datos	"Explícame cómo funciona la base de datos del proyecto"	"Revisa la declaración de modelos en db/models.py para explicar la relación entre usuarios y suscripciones."
Analizar flujos lógicos	"Busca dónde se manejan los errores de red"	"Asigna un subagente para localizar en qué secciones del cliente HTTP se capturan las excepciones de conexión y reporta solo la lista de funciones."

💡 Resumen rápido: Acota las consultas a directorios específicos o delega el análisis a subagentes para evitar que la lectura sucesiva de archivos sature la memoria del contexto principal (Artículos 19 y 23).

---

09 Ejercicio práctico: diagnóstico de una sesión con antipatrones

Realizaremos un ejercicio de diagnóstico. Analizaremos una sesión de desarrollo que acumula múltiples antipatrones y propondremos la corrección correspondiente para optimizar el flujo.

Escenario de desarrollo:

Un desarrollador inicia su día de trabajo en un proyecto local. Ejecuta claude --dangerously-skip-permissions para omitir confirmaciones.

Escribe la siguiente instrucción en el primer mensaje de la sesión:

Quiero que investigues cómo funciona la API de este proyecto, que me expliques las diferencias entre Next.js 14 y 15 para el routing, que añadas un endpoint de reportes a la base de datos copiando el estilo de los otros endpoints, y que corrijas el error de compilación que está ocurriendo en build-error.log.

El desarrollador mantiene este chat activo durante el resto del día para realizar consultas secundarias y aplicar más cambios de código.

Diagnóstico de fallos (Identificación de antipatrones):

1. Uso de --dangerously-skip-permissions (Antipatrón 6): Desactiva los controles de seguridad exponiendo el sistema a inyecciones de código en la lectura de archivos de terceros.
2. Instrucción multipropósito en un solo prompt (Antipatrón 1): Mezcla investigación general, consultas conceptuales de frameworks, desarrollo de endpoints y corrección de bugs en un solo mensaje.
3. Solicitud de investigación abierta ("investiga la API") (Antipatrón 7): Causará que el agente lea múltiples archivos sin rumbo, saturando el contexto al inicio.
4. Consulta conceptual del framework sin WebSearch (Antipatrón 4): Next.js 15 es reciente; el agente podría alucinar sobre sus características si confía en su memoria interna.
5. No define método de validación para el endpoint ni para el bug (Antipatrón 5): No se indican suites de pruebas ni comandos de compilación para verificar que el código nuevo sea correcto.
6. Mantener la sesión abierta de forma indefinida (Antipatrón 3): Saturna el contexto al acumular el historial del día, reduciendo la precisión de las respuestas por la tarde.

Propuesta de corrección:

Para optimizar el desarrollo, el flujo debe reestructurarse de la siguiente manera:

1. Iniciar la sesión con permisos seguros: ejecutar claude (con confirmaciones activas o usando acceptEdits para agilidad local).
2. Segmentar el desarrollo en conversaciones independientes:
   • Sesión A: Corrección del bug de compilación:

     Revisa el archivo build-error.log. Corrige la causa raíz del fallo en el código y valida la solución ejecutando el comando de compilación del proyecto.

     Una vez resuelto y verificado, ejecuta /clear para limpiar el contexto.
   • Sesión B: Investigación y diseño del endpoint (Plan Mode): Cambia a Plan Mode y escribe:

     Analiza los controladores existentes en el directorio src/api/controllers/ para comprender el estilo de diseño. Propón un plan para estructurar el nuevo endpoint de reportes de base de datos sin modificar los archivos todavía.

     Una vez aprobado el diseño, regresa a la sesión interactiva, programa el endpoint y valida su funcionamiento con su respectiva prueba unitaria. Al finalizar, realiza el commit y limpia con /clear.
   • Sesión C: Consulta conceptual (Uso de WebSearch): Abre una conversación nueva y escribe:

     Utiliza la herramienta WebSearch para consultar los cambios en la estructura de enrutamiento (routing) de Next.js 15 en comparación con Next.js 14 y explícame las diferencias.

Este flujo estructurado en sesiones independientes y acotadas garantiza una programación precisa y libre de errores de contexto.

💡 Resumen rápido: El ejercicio práctico demuestra que identificar y separar las tareas en conversaciones específicas y seguras, acotando el alcance y aplicando validaciones, resuelve los fallos de contexto y la ineficiencia de las sesiones multipropósito.

---

10 Resumen

En este artículo hemos expuesto las prácticas incorrectas más comunes en el uso de Claude Code y cómo corregirlas.

Repasemos los desvíos y sus soluciones:

#	Práctica incorrecta (Antipatrón)	Solución recomendada	Acción técnica
1	Un solo prompt con múltiples tareas	Delegar una sola tarea a la vez	Usar Plan Mode en cambios complejos antes de programar
2	Omitir o saturar CLAUDE.md	Mantener una guía breve de comandos y reglas	Excluir información redundante y usar Skills para datos extensos
3	Una misma sesión indefinida	Limpiar el contexto de forma periódica	Usar /clear al cambiar de tarea y /compact en chats largos
4	Confiar ciegamente en datos conceptuales	Usar WebSearch o MCP para validar información	Exigir evidencias de ejecución de comandos reales
5	No proveer pruebas ejecutables	Definir criterios de validación objetivos	Añadir comandos de prueba o compilación al final de las instrucciones
6	Desactivar permisos en el sistema local	Mantener controles de seguridad activos	Usar acceptEdits en local y restringir bypass a entornos aislados
7	Consultas de investigación abiertas	Acotar el alcance a directorios específicos	Delegar análisis extensos a subagentes para proteger el contexto

Ahora puedes:

• Detectar desviaciones de contexto en tus conversaciones de desarrollo diarias.
• Estructurar prompts específicos acotando los archivos y el comportamiento esperado.
• Mantener la densidad del archivo CLAUDE.md optimizada para el agente.
• Gestionar la limpieza de conversaciones utilizando /clear y /compact de forma oportuna.
• Integrar métodos de validación autónomos para asegurar la calidad de las propuestas.
• Desarrollar tareas en un entorno de permisos seguro libre de inyecciones de código.

Evitar estas malas prácticas te permitirá colaborar con Claude Code de forma fluida y ordenada, manteniendo la consistencia de tu código base y un desarrollo seguro.

---

El siguiente artículo es 51 "FAQ: resolución de problemas". Hemos analizado los enfoques de uso y antipatrones; en el próximo artículo nos enfocaremos en los errores técnicos del sistema y fallos de la herramienta: fallos de instalación, problemas de autenticación de cuentas, comandos bloqueados o conflictos de dependencias del entorno, detallando su diagnóstico y soluciones correspondientes.

---

Lecturas recomendadas

• Estructura del archivo CLAUDE.md
• Conexión y autenticación de cuentas
• Glosario de términos y conceptos clave