Una configuración de ocho capas para Claude Code: CLAUDE.md, Memoria, Ganchos y Límites.

La configuración determina hasta qué punto se puede confiar en la respuesta

Cualquiera puede escribir una instrucción en Claude Code, pero la configuración asociada decide si el resultado merece confianza. A continuación se presenta un recorrido capa por capa de una configuración realista para trabajos de ingeniería serios, junto con la lógica detrás de cada capa. No se trata de una lista de funciones ni de una versión publicitaria. Ocho capas juntas crean algo más parecido a una herramienta de ingeniería bien configurada que a una ventana de chat que casualmente escribe código.

Capa 1: CLAUDE.md en dos niveles de alcance

Claude Code lee los archivos CLAUDE.md en varios ámbitos, y la separación entre ellos es más importante de lo que la mayoría de las personas imagina. Un archivo personal en ~/.claude/CLAUDE.md se aplica en cada proyecto, independientemente del repositorio que esté abierto. Cada proyecto también cuenta con su propio CLAUDE.md que se guarda en el control de versiones, de modo que todo el equipo lee las mismas instrucciones a través del control de versiones.

Una regla sencilla mantiene separados ambos tipos de información. Todo lo relacionado con la forma en que trabaja una persona, independientemente del código fuente, se incluye en el archivo global: reglas de uso de herramientas como preferir una búsqueda mediante inteligencia de código en lugar de un análisis simple con grep, preferencias y convenciones de comunicación que deben aplicarse en todas partes. Todo lo relacionado con un código fuente específico se incluye en el archivo correspondiente a cada repositorio: comandos de compilación, decisiones arquitectónicas, convenciones de nomenclatura y categorías de errores que ya han afectado a ese proyecto. En cualquier otro proyecto, esos elementos son ruido que consume contexto sin motivo alguno.

El motivo para anotar algo es concreto. Imagine un patrón de error que aparece dos veces en la misma área de un proyecto. La solución parece correcta y pasa desapercibida a primera vista, pero vuelve a introducir el mismo problema porque la restricción subyacente nunca se registró en ningún lugar visible para el responsable. La primera vez, la restricción se explica en la conversación y todos siguen adelante. La segunda vez, el mismo error lleva a la misma explicación. Ese es la señal. Una regla debe estar en CLAUDE.md no porque pueda ser útil algún día, sino porque hizo que la misma conversación se repitiera dos veces. Una vez que se trata de una regla concreta y verificable, y no de una advertencia vaga, el problema deja de repetirse.

Un detalle práctico: el contenido de CLAUDE.md se entrega como un mensaje del usuario y no está integrado en el prompt del sistema, por lo que la especificidad es más importante que la longitud. Un archivo con menos de 200 líneas de reglas claras es mejor que uno largo lleno de reglas vagas.

Capa 2: memoria automática

CLAUDE.md es lo que el desarrollador le indica al agente, mientras que la memoria es lo que el agente determina por sí mismo. Realizan funciones diferentes y no deben confundirse. Claude Code cuenta con un segundo sistema, memoria automática, que se va construyendo según el proyecto y se almacena fuera del repositorio; es el agente quien escribe en él. Este sistema guarda cuatro tipos de notas: el rol y las preferencias de trabajo del desarrollador, las correcciones y comentarios ya proporcionados, el estado actual del proyecto que no puede deducirse del código, y referencias externas que apuntan a información que se encuentra fuera de la base de código. Un archivo ligero MEMORY.md indexa todo esto.

La diferencia radica en que CLAUDE.md contiene instrucciones escritas intencionadamente, mientras que la memoria almacena el contexto acumulado a lo largo de sesiones de trabajo, sin ser documentado formalmente. Una es un manual de reglas; la otra se asemeja al conocimiento institucional que posee un colega con larga trayectoria sin ningún documento de inducción. Tres ejemplos muestran qué cambia:

• Una corrección puntual, como “no toque este archivo sin preguntar primero”, se traslada a la siguiente sesión y no es necesario repetirla cada vez que se inicia una conversación.
• Se recuerda el estado del proyecto que no se ve en el código: una migración en curso, una decisión deliberadamente pospuesta, o una arquitectura que parece incorrecta intencionadamente debido a una restricción que ningún diferencial muestra.
• Se mantienen las indicaciones sobre dónde se encuentran las respuestas, como qué panel de control, qué documento externo o qué sistema contiene la información que la base de código no puede indicar.

Nada de eso pertenece a CLAUDE.md, ya que nada de ello constituye una regla que se aplique. Se trata de contexto que desaparecería en el momento en que se cierre una sesión.

Capa 3: ganchos como fricción deliberada

La fricción elegida intencionadamente no es nada similar a la fricción con la que simplemente uno se topa. Los ganchos se ejecutan de manera determinista, como comandos de shell reales en momentos fijos del ciclo de vida, lo cual ofrece una garantía más sólida que confiar en que el modelo recuerde habitualmente. Un gancho PreToolUse se activa antes de cualquier llamada a una herramienta y puede detenerla por completo. Un gancho Stop se activa cuando Claude finaliza su respuesta y puede obligarlo a continuar si aún no se ha cumplido alguna condición.

El patrón más útil es un gancho PreToolUse limitado a las ediciones de archivos. Antes de que se proceda con la edición, se requiere un relato escrito de los hechos: qué módulos importan el archivo, qué podría romperse y cuál fue realmente la solicitud. Funciona como un freno deliberado contra cambios descuidados, y esa precaución se compensa por sí misma, ya que interviene justo donde es necesario ser cauteloso. A diferencia de la atención humana, un gancho no ignora ni apresura la cuadragésima edición de una sesión larga.

Un segundo gancho se encarga de la disciplina en la salida al mantener las respuestas breves, eliminando el exceso de palabras innecesarias y las expresiones evasivas que aparecen en sesiones más largas. Se trata menos de seguridad y más de no desperdiciar tiempo de lectura en contenido irrelevante. Un tercero supervisa el estado del contexto, incentivando la compresión en un límite natural y no en uno arbitrario. Un gancho PreCompact o SessionStart vinculado a eventos de compresión puede solicitar un resumen cuando la conversación realmente llegue a un punto de finalización, evitando así que se interrumpa a mitad de pensamiento.

¿Vale la pena este esfuerzo? En el caso de la protección contra ediciones erróneas en archivos, sin duda, ya que ha evitado que los errores reales se conviertan en problemas graves. Los ganchos relacionados con la brevedad y el contexto sirven más bien para ajustar la comodidad de uso que como medida de protección, pero resultan útiles una vez configurados adecuadamente.

Capa 4: un grafo de conocimiento de código supera a grep

Grep muestra dónde aparece una cadena de texto, pero no qué la llama, a qué llama ni qué falla cuando cambia. La exploración tradicional consiste en un bucle: buscar un término, abrir el archivo, buscar lo que ese archivo importa, abrir también ese archivo, y continuar hasta que se forme una imagen mental. Funciona, pero de forma lenta, y requiere muchas llamadas a herramientas para reconstruir un modelo basado en datos estructurales que no deberían tener que ser redescubiertos por fuerza bruta en cada sesión.

Un grafo de conocimiento preindexado cambia la dinámica económica. Una sola consulta devuelve la fuente relevante junto con las rutas de llamada reales: quién la llama, a qué llama y cuán larga es la cadena de dependencias. Esto se logra en una sola pasada en lugar de múltiples búsquedas, por lo que hay menos idas y venidas y se obtiene una visión más completa desde el principio, ya que los detalles de las rutas de llamada que grep nunca podría generar vienen incluidos directamente en el resultado. La documentación oficial de Claude Code sostiene algo similar respecto a los complementos de inteligencia de código, señalando que los grandes conjuntos de código tipado se benefician enormemente de las consultas conscientes de la estructura en comparación con la coincidencia de texto, donde los ciclos repetidos de búsqueda y lectura se vuelven costosos rápidamente.

Capa 5: verificación en un dispositivo real

Lo importante es determinar si un cambio funciona en el dispositivo o simplemente se compila, ya que se trata de dos afirmaciones distintas. En Flutter, esta capa es la que se utiliza con mayor frecuencia. Reconstruir todo desde cero para probar un pequeño ajuste en la interfaz de usuario es un desperdicio cuando existe una conexión a una aplicación que funciona en hardware real, y dicha conexión permite cubrir lagunas que la generación de código no puede resolver. Permite tomar capturas de pantalla, navegar por los flujos de interacción y examinar el árbol de la interfaz de usuario en tiempo real. Claude Code ahora soporta esto adecuadamente, ofreciendo acceso al simulador de iOS y funciones para usar la computadora que permiten validar una compilación nativa, reproducir errores de diseño o ejecutar flujos en el simulador en comparación con lo que se muestra en pantalla.

Al conectarse a la VM de Dart para el recargo en tiempo real y el reinicio en tiempo real, el ciclo pasa de “adivinar, reconstruir, esperar, verificar” a “adivinar, recargar, verificar”. Eso es más rápido y también evita una trampa frecuente: considerar que una compilación sin errores es prueba de que la corrección funciona. Que un código se compile y que funcione correctamente en el hardware son afirmaciones distintas, y la costumbre de solo reconstruir no permite distinguirlas. Ejecutarlo en el dispositivo responde directamente a la pregunta.

Capa 6: cargar las herramientas solo cuando sea necesario

Cada herramienta presente en el contexto, ya sea utilizada o no, afecta cada paso del proceso, no solo aquellos en los que se usa. Por eso no todo se carga por defecto, y esa es una elección de diseño intencionada. Las herramientas especializadas, como la automatización de navegadores, los servidores MCP menos comunes y cualquier herramienta que se use ocasionalmente, se cargan bajo demanda y no ocupan el contexto durante toda la sesión.

El efecto se agrava a lo largo de una sesión prolongada, ya que cada definición de herramienta cuesta tokens en cada turno, independientemente de si ese turno la utiliza o no. La función de búsqueda de herramientas MCP de Claude Code existe precisamente para superar este problema. Los servidores pueden registrarse para un descubrimiento bajo demanda en lugar de cargar todas las definiciones al inicio de la sesión, lo que mantiene eficiente una sesión de varias horas y evita que esté sobrecargada por contexto inútil que nunca se utiliza pero sigue costando tokens.

Capa 7: utilice los flujos de trabajo empacados que realmente necesita

Claude Code incluye un amplio ecosistema de flujos de trabajo empacados, como revisiones de código, revisiones de seguridad, revisores específicos para frameworks, y agentes para la planificación y ejecución. Cada uno puede ser invocado de forma explícita, de modo que no se vuelve a crear la misma lógica ad hoc en cada sesión. Una gran biblioteca sirve de poco si solo se utilizan tres elementos, por lo que un recuento honesto del uso real es mejor que una lista completa del catálogo.

Tres se utilizan con regularidad. Se realiza una revisión general del código antes de que se realicen fusiones significativas. Un revisor especializado en seguridad se encarga de todo lo relacionado con la autenticación o el manejo de datos. Un subagente dedicado a la planificación se ocupa de las tareas lo suficientemente grandes como para que pasar directamente a la implementación impida un análisis arquitectónico adecuado. Estos tres abarcan casi todas las invocaciones explícitas.

La mayoría de los revisores específicos de framework para tecnologías que no se utilizan quedan sin ser empleados, al igual que los patrones de subagentes más complejos diseñados para tareas de investigación en paralelo a gran escala. No se trata de herramientas deficientes; simplemente el trabajo diario no requiere ese nivel de investigación, y utilizar herramientas más complejas de las necesarias es un desperdicio. El valor radica en conocer esas tres o cuatro herramientas fiables que vale la pena usar, sin sentirse obligado a emplear el resto solo porque existen.

Capa 8: confirmación mediante reversibilidad

La velocidad solo cuenta como ventaja mientras el resultado siga siendo fiable; una vez que se pierde esa confianza, la velocidad es precisamente lo que causa el daño. Incluso con todas las capas activas, ciertas acciones siempre requieren confirmación explícita: operaciones destructivas en Git, envíos de cambios y cualquier acción verdaderamente irreversible. Ningún grado de automatización permite saltarse ese requisito, porque un error en ese punto no significa solo tener que volver a hacer el trabajo, sino reparar daños que podrían ser irreparables.

El equilibrio depende de cuán reversible sea la acción en cuestión, no de cuán arriesgada parezca la tarea. Una gran refactorización que afecta a docenas de archivos requiere mucho esfuerzo, pero sigue siendo completamente reversible gracias al control de versiones, por lo que puede realizarse con una supervisión menor. Un git push --force casi no requiere esfuerzo y podría resultar irreparable de forma permanente, por lo que se prohíbe su uso sin importar cuán rutinario parezca. El esfuerzo y el riesgo se encuentran en ejes diferentes, y mezclarlos es la forma en que se otorga una autonomía excesiva a tipos de acciones inadecuados.

Elegir entre actuar de inmediato o preguntar primero no se trata de ajustar un único parámetro. Es una decisión que se toma según el tipo de acción, una vez de antemano, y que nunca se vuelve a considerar en el momento en que el agotamiento hace que la solicitud de confirmación parezca un obstáculo molesto.

Lo que aportan las capas

Ninguno de los ocho niveles destaca por sí solo. CLAUDE.md es un archivo de texto plano, y un hook es una orden de shell que se ejecuta en el momento adecuado. Juntos, convierten a Claude Code de un simple mecanismo de escritura rápido que carece de contexto persistente y de cualquier sentido de reversibilidad en una herramienta con memoria, medidas de seguridad, conocimiento estructural del código y verificación real del dispositivo.

La configuración en sí no es lo interesante, sino el razonamiento detrás de cada nivel. Quien utilice Claude Code sin tener nada de esto configurado no debería intentar añadir los ocho niveles de una sola vez. Comience con un CLAUDE.md real basado en errores que ya han ocurrido dos veces, y luego vaya ampliándolo gradualmente.

Leer más

• Notas prácticas: Claude Code Agent Teams: Un guía práctico para construir un equipo — Guía paso a paso de las Notas prácticas: Claude Code Agent Teams: Un guía práctico para construir un equipo: contratos, verificaciones y espacios para código listos para usar para los equipos que implementan este patrón.
• Notas prácticas: Deja de ver a tu agente de programación: Construye un sistema en el que puedas confiar — Guía paso a paso de las Notas prácticas: Deja de ver a tu agente de programación: Construye un sistema en el que puedas confiar: contratos, verificaciones y espacios para código listos para usar para los equipos que implementan este patrón.