Análisis de la estructura de la carpeta .claude/

• La carpeta .claude/ es el directorio central de control de Claude Code, y administra reglas, comandos, permisos y estado de memoria por proyecto
• CLAUDE.md es el archivo principal que define los principios de comportamiento y las reglas del proyecto para Claude, aplicando una combinación de configuraciones de varias capas
• Las carpetas commands/, skills/ y agents/ organizan respectivamente comandos personalizados, flujos de trabajo automáticos y subagentes especializados, mejorando la eficiencia de colaboración
• settings.json controla los permisos de ejecución de comandos y el alcance de acceso a archivos, y permite overrides personales con settings.local.json
• Toda la estructura funciona como un protocolo que transmite a Claude la identidad y las reglas del proyecto, por lo que una configuración clara maximiza la productividad y la eficiencia de colaboración

---

Estructura de la carpeta .claude/ y sus componentes

• La carpeta .claude/ es el directorio clave que controla el funcionamiento de Claude Code, y gestiona reglas, comandos, permisos y estado de memoria por proyecto
• La carpeta ubicada en la raíz del proyecto contiene la configuración compartida del equipo y se confirma en Git
• La carpeta del directorio personal (~/.claude/) almacena configuración personal e historial de sesiones, e incluye memoria automática y comandos personales

• CLAUDE.md — La guía de instrucciones de Claude

  • Es el primer archivo que se lee al iniciar una sesión de Claude Code, y define los principios de comportamiento de Claude y las reglas del proyecto
  • El CLAUDE.md en la raíz del proyecto define las reglas comunes del equipo, ~/.claude/CLAUDE.md contiene las reglas personales globales, y los CLAUDE.md en subcarpetas manejan reglas específicas por carpeta
  • Claude combina y aplica varios archivos CLAUDE.md
  • El contenido recomendado incluye comandos de build y test, decisiones importantes de arquitectura, restricciones poco intuitivas y reglas de nomenclatura y manejo de errores
  • Se recomienda mantenerlo en menos de 200 líneas; una longitud excesiva reduce el nivel de cumplimiento de instrucciones por parte de Claude

• CLAUDE.local.md — Overrides personales

  • Es un archivo que permite reflejar preferencias personales aparte de las reglas comunes del equipo
  • Si se crea CLAUDE.local.md en la raíz del proyecto, Claude también lo leerá
  • Se incluye automáticamente en .gitignore, por lo que no se confirma en el repositorio

• Carpeta rules/ — Gestión modular de reglas

  • Si CLAUDE.md crece demasiado, puede separarse para administrarlo en la carpeta .claude/rules/
  • Cada archivo de reglas se separa por tema, lo que facilita el mantenimiento
    • Ej.: code-style.md, testing.md, api-conventions.md, security.md
  • Si se usa el campo paths del front matter YAML, se pueden definir reglas que se aplican solo a rutas específicas
    • Ej.: aplicar reglas de API solo a la ruta src/api/**/*.ts
  • Las reglas sin ruta especificada se cargan siempre en todas las sesiones

• Carpeta commands/ — Comandos slash personalizados

  • Cada archivo Markdown en .claude/commands/ se registra como un comando slash (/)
    • Ej.: review.md → /project:review, fix-issue.md → /project:fix-issue
  • Con la sintaxis de backticks ! se puede insertar en el prompt de Claude el resultado de ejecutar comandos de shell
    • Ej.: !git diff main...HEAD
  • Con la variable $ARGUMENTS se pueden pasar argumentos al ejecutar el comando
    • Ej.: /project:fix-issue 234 → carga automáticamente el contenido del issue 234 de GitHub
  • Los comandos del proyecto se comparten con el equipo, mientras que los comandos personales se guardan en ~/.claude/commands/ y pueden usarse en todos los proyectos

• Carpeta skills/ — Flujos de trabajo de ejecución automática

  • Funcionan como flujos de trabajo similares a los comandos, pero que se activan automáticamente
  • Claude analiza el contenido de la conversación y se ejecutan automáticamente en situaciones adecuadas
  • Cada skill se define con un archivo SKILL.md dentro de una subcarpeta, y mediante front matter YAML se especifican las condiciones de activación y las herramientas permitidas
    • Ej.: la skill security-review se ejecuta automáticamente en conversaciones relacionadas con seguridad
  • La carpeta de una skill puede incluir documentación auxiliar o archivos de plantilla como DETAILED_GUIDE.md
  • Las skills personales se guardan en ~/.claude/skills/ y pueden usarse globalmente

• Carpeta agents/ — Subagentes especializados

  • En la carpeta .claude/agents/ se definen subagentes (persona) que cumplen roles específicos
  • Cada agente tiene un prompt de sistema independiente, modelo y permisos de acceso a herramientas
    • Ej.: code-reviewer.md, security-auditor.md
  • Con el campo tools se restringen las herramientas accesibles para lograr seguridad y separación de roles
  • Con el campo model se puede elegir el modelo de Claude adecuado para la tarea (ej.: Haiku, Sonnet, Opus)
  • Cuando hace falta, Claude ejecuta ese agente en un contexto separado y solo reporta un resumen del resultado

• settings.json — Permisos y configuración del proyecto

  • .claude/settings.json define los permisos de ejecución de comandos y el alcance de acceso a archivos de Claude
  • El campo $schema permite autocompletado y validación en VS Code y otros entornos
  • La lista allow define comandos con aprobación automática, y la lista deny define comandos completamente bloqueados
    • Ej.: permitidos — Bash(npm run *), Read, Write, Edit
    • bloqueados — Bash(rm -rf *), Bash(curl *), lectura de archivos .env
  • Los comandos que no aparecen en la lista solicitan confirmación del usuario antes de ejecutarse
  • Los cambios personales de permisos se guardan en .claude/settings.local.json y no se incluyen en Git

• Carpeta ~/.claude/ — Configuración global y memoria

  • ~/.claude/CLAUDE.md contiene instrucciones personales compartidas para todos los proyectos
  • ~/.claude/projects/ almacena el historial de sesiones por proyecto y la memoria automática
    • Conserva comandos, patrones e insights estructurales aprendidos por Claude
    • Se puede consultar y editar con el comando /memory
  • ~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/ son repositorios de comandos, skills y agentes personales globales

• Ejemplo de estructura completa

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• Pasos de configuración inicial

  • Paso 1: crear el CLAUDE.md base con el comando /init y dejar solo el contenido esencial
  • Paso 2: crear .claude/settings.json y definir reglas de permisos y bloqueos de ejecución

  • 3er paso:agregar comandos adaptados a los flujos de trabajo más frecuentes (ej.: revisión de código, corrección de issues)

    • Paso 4: si CLAUDE.md crece, separarlo en .claude/rules/
    • Paso 5: agregar reglas de preferencia personal en ~/.claude/CLAUDE.md

Insights clave

• La carpeta .claude/ es un protocolo que transmite a Claude la identidad y las reglas del proyecto
• CLAUDE.md es el archivo más importante, y cuanto más claramente se defina, más se maximiza la productividad de Claude
• El resto de los componentes son capas de optimización complementarias y pueden ampliarse gradualmente
• Una configuración clara lleva a menos solicitudes de corrección a Claude y una colaboración más eficiente

Debate adicional

• La lista deny de settings.json es segura para uso humano, pero en modo agente se necesita protección adicional debido al acceso a Bash
• OneCLI ofrece una capa proxy a nivel de red que reemplaza tokens de credenciales para evitar la exposición de secretos
• Se plantea la necesidad futura de una configuración .claude específica para modo agente (separación de reglas, permisos y skills)
• Según la documentación más reciente, commands y skills se han unificado, por lo que .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md generan por igual el comando /deploy, mientras que las skills admiten funciones adicionales (archivos auxiliares, activación automática, etc.)

[GN⁺]

Opiniones en Hacker News

• Se siente como si construir un toolkit de agentes de IA fuera como buscar la configuración de productividad perfecta
  Uno ve posts de blog y YouTube para armar una rutina, pero al final la persona que trabaja de forma constante con una simple lista de tareas termina yendo más adelante
  En mi experiencia, la forma simple de hacer que Plain Claude planifique, revise y luego ejecute sigue siendo la que mejor funciona

  • En bases de código grandes o sistemas distribuidos, la historia cambia
    Las habilidades técnicas del agente para canalizar datos, crear solicitudes, rastrear sistemas y actualizar código aumentan muchísimo la eficiencia de desarrollo
    En código del orden de 10 millones de líneas, la productividad mejoró mucho, y la generación real de código representa menos del 5%
    La mayor parte se debe a la capacidad de crear rápido una toolchain para pruebas y validación
  • Mucha gente está cayendo en esa trampa y gastando dinero
    En realidad, si sabes qué quieres claramente y puedes comunicarlo bien, ya puedes hacer bastante con IA
    La mayoría no lo sabe. Por eso, hacer que planifique se vuelve un atajo para obtener comprensión
  • Como PM, quiero que los agentes me ahorren tiempo y den un efecto compuesto (compounding) en la producción
    Pero en cada sesión está la ineficiencia de repetir contexto y copiar archivos .md
    El objetivo actual es eliminar esa repetición.
    Tengo curiosidad por cómo manejan un “context bank” que vaya acumulando contexto — por ejemplo, información base como “mi rol, el producto a cargo, la documentación más reciente”
    Hay muchos documentos duplicados y desactualizados, así que no puedo simplemente conectar todo Drive
    Si un contexto repetido aparece más de dos veces, no sé si debería hacer que cree un archivo de Skill, o reunir documentos y administrarlos en una sola carpeta
  • A mí me pasó algo parecido. La mayoría de los artefactos generados durante el trabajo terminan desechándose
    La sobreconfiguración (over-configuration) provoca caída de calidad y problemas de loops
    Como los modelos mejoran cada vez más, instrucciones que antes hacían falta ahora incluso perjudican el rendimiento
    También escuché que el equipo de Anthropic reinicia claude.md cada 30 días
  • En cambio, yo estoy trabajando en un proyecto que necesita integrar una API contable local, y es una API totalmente custom que el LLM no conoce
    Así que hice que Claude creara un servidor MCP, y ahora automatiza tareas contables
    Después del cierre de fin de mes, le hice a Claude extraer las tareas principales y convertirlas en un Skill, y trabaja como si tuviera un contador junior
    Los MCP custom y los Skill me parecen realmente útiles

• Se siente como que mucha gente levanta un enorme muro de configuración antes de empezar con el coding agentic
  Pero al inicio lo correcto es partir con .claude vacío y AGENTS.md e ir aprendiendo a manejarlo por cuenta propia

  • Yo incluso creo que solo deberías usar skills creados por ti mismo
    Si instalas skills hechos por otros sin control, aumenta la no determinación (nondeterminism) y además desperdicias ventana de contexto
    Como excepción, solo recomendaría instalar algo externo como playwright-cli
  • En equipos grandes sí hacen falta guardrails (reglas) consistentes
    Por ejemplo, si lo configuras para verificar precondiciones como en esta regla, se vuelve estable
    Creo que al equipo de seguridad también le gustaría este enfoque
    Yo también definí reglas para que Claude no haga commits sin firma GPG
    Aun así, estas reglas no deben ser fijas, sino evolucionar constantemente
  • Este artículo no está forzando una configuración gigante
    Al contrario, repite una y otra vez que hay que empezar pequeño y mantenerlo corto
    Incluso alguien principiante puede hacer que la IA entienda mejor su intención con solo agregar unas líneas a AGENTS.md
    Una configuración simple reduce muchísimo el mal funcionamiento de la IA
  • Manejar código por tu cuenta y manejar un proyecto compartido en equipo son cosas completamente distintas
    Si cada desarrollador usa herramientas agentic, cambia por completo la forma de colaborar
  • Con usar solo el modo plan ya se resuelve el 90%
    Creo que la mayoría de estas discusiones sobre configuraciones complejas van a desaparecer en un año a medida que mejoren los modelos

• La carpeta ~/.claude/projects es la parte realmente interesante

• A mí me fue mejor mientras menos configuración innecesaria había
  La gente sobrerregula los documentos, pero la IA es como un adulto competente pero nervioso
  Si le das demasiadas instrucciones, se vuelve más tonta

• Este post se siente más generado que basado en experiencia real
  Claude.md debe ser corto, con solo unos cuantos links
  Cuando el contexto se acumula, el rendimiento empeora, así que hay que separar planificación e implementación y reiniciar cada vez

  • La introducción se parecía demasiado al estilo de Claude, así que sentí que mejor podía preguntárselo directamente a Claude
  • Me confunde la diferencia entre skills y comandos
    No me queda claro si los skills están siempre en el contexto y los comandos solo se invocan manualmente

• Ojalá todos los proveedores de modelos compartieran un conjunto estándar de archivos
  Así sería más fácil cambiar entre Claude, Codex, Cursor y Opencode

  • Pero la combinación de modelo y harness influye mucho en el resultado
    Incluso con el mismo prompt, cada modelo reacciona distinto, así que el prompt tuning también debe cambiar según el modelo
  • Puedes crear un solo agents.md, hacer que Claude.md lo referencie y conectarlo entre carpetas con symlinks (sync)
    No es perfecto, pero funciona bastante bien
  • Ahora mismo estamos como en la era temprana de los navegadores. Gracias a que no estaba estandarizado surgieron innovaciones como AJAX
    Por eso, la diversidad actual más bien me parece algo positivo
  • Yo, por ahora, estoy usando dotagents by Sentry para resolver este problema
  • No creo que los proveedores de modelos tengan motivo para hacer que cambiarse sea fácil

• La documentación alternativa de Claude Fast es muy útil
  No entiendo por qué alguien odiaría la definición de la carpeta .claude
  Puedes hacer que el agente principal escriba archivos directamente, los actualice de forma iterativa y construya un sistema que se mejora a sí mismo
  Ahora mismo .claude se clona, evalúa y actualiza por sí solo — en vez de programar código, es como si yo estuviera programando .claude

  • En resumen, CLAUDE.md no es solo un documento, sino el sistema operativo de Claude
    Define el comportamiento, delega conocimiento a skills y construye un sistema que se mejora solo con el tiempo

• Una barrera que mucha gente no conoce es que, aunque hagas que Claude modifique un archivo, si no le indicas explícitamente que lo relea, el cambio no se refleja
  Por ejemplo, si acabas de escribir un nuevo CLAUDE.md, tienes que recargarlo para que Claude lo reconozca como una nueva instrucción

• En la carpeta ~/.claude/plans se guardan los archivos de plan generados al ejecutar el modo plan
  Yo suelo abrir ese directorio seguido para respaldar cosas o usarlo como referencia

• Yo me organizo alrededor de servidores MCP globales y un agente compuesto (composite agent)
  Cada servidor MCP define un conjunto de herramientas, y el agente trabaja de forma autónoma dentro de eso
  .agent.md es simplemente un documento que describe las herramientas disponibles; no hace falta una configuración compleja
  Siento que los skills o prompts reutilizables tienen poco valor
  Los modelos ya son suficientemente inteligentes, así que lo que hace falta es orientación