Gancho Personalizado PostToolUse para Carga Bajo Demanda de CLAUDE.md Fuera del Árbol del Proyecto

Comportamiento de Carga de CLAUDE.md en Claude Code

La fuente detalla cómo Claude Code maneja los archivos CLAUDE.md bajo diferentes condiciones:

• Carga jerárquica: Al iniciar una sesión en un subdirectorio, se cargan tanto el archivo CLAUDE.md local como los archivos CLAUDE.md del directorio padre. Ejemplo: Sesión en root/a/ carga tanto root/a/CLAUDE.md como root/CLAUDE.md.
• Carga bajo demanda de directorios hijos: Los directorios hijos del directorio raíz de la sesión actual cargan sus archivos CLAUDE.md cuando Claude accede a archivos en esos directorios. Ejemplo: Sesión en root/ carga root/CLAUDE.md inicialmente, luego carga root/a/CLAUDE.md cuando Claude lee un archivo en root/a/.
• Acceso a directorios adicionales mediante banderas: Usar --add-dir con CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 permite acceder a archivos CLAUDE.md en directorios fuera del árbol del proyecto, pero estos se cargan al inicio de la sesión en lugar de bajo demanda.

El Problema: Archivos CLAUDE.md de Directorios Externos No Se Cargan Bajo Demanda

El autor señala que al trabajar en un proyecto e instruir a Claude para que lea archivos de directorios fuera del árbol de directorios de la sesión, cualquier archivo CLAUDE.md en esos directorios externos no se cargará automáticamente. Esto crea problemas para la divulgación progresiva del contexto y requiere intervención manual cada vez.

Solución: Enlace Personalizado PostToolUse

La solución implica crear un enlace PostToolUse que:

• Verifica si Claude está operando fuera del árbol del proyecto en cada llamada de herramienta
• Recorre hacia arriba desde ese directorio buscando archivos CLAUDE.md
• Si se encuentran, sale con el código 2 para enviar instrucciones de vuelta a Claude diciéndole que los lea
• Realiza un seguimiento de qué archivos ya se han presentado en un archivo temporal de alcance de sesión para evitar instrucciones repetidas

Un enlace SessionStop limpia el archivo temporal utilizado para el seguimiento. El autor proporciona un script llamado check_claude_md.py (fuente enlazada en la publicación original) que implementa esta funcionalidad de enlace PostToolUse.

Implementación Práctica

Este enfoque aborda la limitación específica donde los archivos CLAUDE.md de directorios externos solo se cargan al inicio de la sesión cuando se usa la bandera --add-dir con CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. Al interceptar las llamadas de herramientas y verificar operaciones fuera del árbol del proyecto, el enlace permite la carga bajo demanda similar a cómo funcionan los directorios hijos dentro del árbol del proyecto.

Este tipo de enlace personalizado es útil para desarrolladores que trabajan frecuentemente en múltiples proyectos o necesitan hacer referencia a archivos de contexto compartidos desde directorios externos sin tener que instruir manualmente a Claude para que lea los archivos CLAUDE.md cada vez.