Un reciente hilo de Akshay Pachaar en X ha vuelto a poner sobre la mesa una idea que cada vez comparten más equipos de desarrollo: en Claude Code, la diferencia entre obtener resultados mediocres y conseguir un agente realmente útil no suele estar solo en el prompt, sino en cómo está configurado el proyecto. Y ahí entra en juego la carpeta .claude, que ya no puede verse como un detalle secundario, sino como la infraestructura que define contexto, permisos, automatizaciones y especialización del agente.
La documentación oficial de Anthropic respalda buena parte de esa visión, aunque con algunos matices importantes. Claude Code distingue entre configuración de usuario en ~/.claude/, configuración de proyecto en .claude/ dentro del repositorio y configuración local en .claude/settings.local.json, pensada para ajustes personales no compartidos con el equipo. Es decir, sí existen al menos dos niveles claros de carpeta .claude, y esa separación entre lo que se versiona y lo que permanece privado es una pieza central del modelo.
Uno de los puntos más importantes es CLAUDE.md, porque sigue siendo el archivo de mayor palanca en cualquier proyecto. Ahí es donde se condensan comandos útiles, decisiones de arquitectura, convenciones de estilo, advertencias operativas y contexto que el equipo no quiere repetir una y otra vez en cada sesión. Sin embargo, aquí conviene corregir una idea que se repite mucho en redes: según la documentación oficial, el contenido de CLAUDE.md no entra como system prompt, sino como un mensaje de usuario después del system prompt, lo que significa que Claude intenta seguirlo, pero no existe obediencia estricta garantizada si las instrucciones son vagas, excesivas o entran en conflicto con otras.
Anthropic también deja una recomendación muy clara: cuando CLAUDE.md se alarga demasiado, el rendimiento empeora. La guía oficial explica que los archivos por encima de unas 200 líneas consumen más contexto y pueden reducir la adherencia del modelo, por lo que recomienda mover procedimientos extensos a reglas o archivos auxiliares. En otras palabras, el archivo más importante del sistema también exige disciplina editorial.
A partir de ahí entra en juego la carpeta .claude/rules/, que en la práctica resuelve uno de los problemas más comunes: convertir CLAUDE.md en un cajón de sastre imposible de mantener. Las reglas permiten separar instrucciones por tema —por ejemplo testing.md, security.md o api-design.md— y además pueden activarse solo en rutas concretas mediante frontmatter YAML con el campo paths. Esto permite, por ejemplo, que unas normas solo se apliquen cuando Claude trabaja sobre src/api/**/*.ts, sin contaminar el resto del proyecto.
Otra de las piezas que más valor aportan, y que el hilo de Akshay resumía bastante bien, son los hooks. En Claude Code, los hooks se configuran dentro de settings.json y permiten automatizar acciones en distintos momentos del ciclo de trabajo: bloquear comandos antes de ejecutarlos, autoformatear archivos tras una edición, reinyectar contexto o lanzar notificaciones cuando Claude necesita atención humana. La guía oficial insiste en que son deterministas y que, si se quiere bloquear una acción, hay que devolver código de salida 2 o una decisión explícita de bloqueo; cualquier otro código deja pasar la acción. Ese matiz técnico es importante porque convierte los hooks en algo más parecido a una política operativa que a una simple sugerencia.
Luego están las skills, que quizá son la parte más interesante para quienes ya han superado la fase de “usar Claude como chat con esteroides”. Anthropic define las skills como paquetes reutilizables de instrucciones en un archivo SKILL.md, que Claude puede cargar cuando detecta que son relevantes o que también pueden invocarse directamente con /skill-name. La documentación añade un detalle clave: los antiguos custom commands se han fusionado en el modelo de skills, de modo que un archivo en .claude/commands/ sigue funcionando, pero el enfoque moderno pasa por .claude/skills/, donde además pueden convivir ficheros de apoyo, frontmatter y lógica de invocación más rica.
Este punto cambia bastante cómo debería estructurarse el trabajo repetitivo. Lo que antes muchos equipos resolvían con prompts pegados a mano o documentos largos dentro de CLAUDE.md, ahora puede empaquetarse como skill: revisiones de seguridad, checklists de despliegue, flujos de depuración, procesos de análisis o incluso guías internas de PRs. Y como su contenido solo se carga cuando se usa, el coste en contexto es mucho menor que si todo viviera en el prompt base.
La siguiente capa son los subagentes o agentes especializados, que viven en .claude/agents/ y permiten definir perfiles con herramientas restringidas, descripciones enfocadas y modelos más baratos o rápidos cuando el trabajo lo permite. Anthropic señala que Claude Code ya incluye subagentes integrados como Explore y Plan, pero también permite crear otros personalizados para revisión de código, auditoría de seguridad o cualquier tarea recurrente que se beneficie de aislamiento de contexto y restricciones de herramientas. Esta es una de las partes más potentes del sistema porque permite dividir exploración, planificación y ejecución sin llenar la conversación principal de ruido.
Por último, settings.json es donde se aterriza la gobernanza real del agente. Ahí se definen permisos, listas de allow/deny, plugins y hooks. La documentación oficial muestra ejemplos concretos para denegar lectura de .env, secretos o rutas sensibles mediante permissions.deny, y también contempla un nivel local no compartido con el equipo en .claude/settings.local.json. Esto convierte a .claude no solo en una carpeta de contexto, sino en una capa de control de riesgo: qué puede hacer Claude sin pedir permiso, qué queda bloqueado y qué no debería ni tocar.
En paralelo, Anthropic también ha desarrollado todo un sistema de memoria del proyecto. El comando /memory permite ver qué archivos CLAUDE.md, CLAUDE.local.md y reglas están cargados, así como revisar la memoria automática que Claude va guardando bajo ~/.claude/projects/<project>/memory/. Esto ayuda a entender por qué el agente “recuerda” ciertas cosas entre sesiones y, sobre todo, permite auditarlo, editarlo o borrarlo cuando haga falta.
Visto en conjunto, el hilo de Akshay acierta en lo esencial: la carpeta .claude se está consolidando como el verdadero control center de Claude Code. Pero la documentación oficial añade una lección importante: no todo es magia ni todo entra en el system prompt ni todas las piezas pesan igual. CLAUDE.md sigue siendo la base, sí, pero lo que marca la madurez real de un proyecto es cómo se combinan instrucciones, reglas, skills, hooks, subagentes y permisos para que el agente trabaje con más contexto, menos fricción y más consistencia.
Qué debería tener un proyecto bien armado con Claude Code
Un proyecto serio con Claude Code no necesita empezar con diez capas de complejidad, pero sí suele beneficiarse de una progresión bastante lógica. Primero, un CLAUDE.md breve y útil. Después, permisos y exclusiones en settings.json. Más adelante, reglas modulares en .claude/rules/ para no convertir las instrucciones en un bloque inmanejable. Y, cuando el equipo ya tiene flujos repetitivos o tareas suficientemente complejas, skills y subagentes. Es una evolución bastante natural: primero contexto, luego control, después automatización y finalmente especialización.
Preguntas frecuentes
¿La carpeta .claude es solo un detalle técnico o algo realmente importante?
Es bastante importante. Anthropic la usa para separar configuración de usuario, proyecto y entorno local, y dentro de ella viven instrucciones, permisos, hooks, skills y subagentes.
¿CLAUDE.md funciona como system prompt?
No exactamente. La documentación oficial dice que su contenido se entrega como un mensaje de usuario después del system prompt. Claude intenta seguirlo, pero no existe obediencia estricta garantizada.
¿Las reglas en .claude/rules/ se aplican siempre?
Solo si no tienen paths. Las reglas con paths en YAML se activan cuando Claude trabaja con archivos que coinciden con esos patrones.
¿Los hooks pueden bloquear acciones peligrosas?
Sí. Un hook puede bloquear una acción devolviendo código de salida 2 o una decisión explícita de bloqueo. Es una de las capas más útiles para imponer políticas automáticas.
¿Custom commands y skills son cosas distintas?
Cada vez menos. Anthropic indica que los custom commands se han integrado en el modelo de skills, aunque los comandos antiguos en .claude/commands/ siguen funcionando.
