Dentro de la Carpeta .claude/
El directorio .claude/ se está convirtiendo en el sistema nervioso de las bases de código asistidas por IA. Qué contiene, por qué importa y cómo lo estructuran los equipos.
Hay una carpeta que está apareciendo en bases de código que no existía hace dos años. Se ubica junto a .git/ y .github/, rara vez se incluye en commits por accidente, y la mayoría de los desarrolladores que la usan han llegado a su propia estructura idiosincrásica mediante prueba y error. El directorio .claude/ — y, en términos más amplios, la capa de configuración a nivel de proyecto para los asistentes de codificación con IA — se está convirtiendo en la convención no documentada más importante del desarrollo de software moderno.
Nadie impuso un estándar. Nadie escribió un RFC. Los equipos están improvisando, y los patrones en los que están convergiendo revelan algo importante sobre lo que realmente se necesita para que las herramientas de codificación con IA funcionen a nivel de proyecto, no solo a nivel de sesión.
Qué Contiene Realmente la Carpeta
El directorio .claude/ es el mecanismo principal de Claude Code para el contexto persistente con alcance de proyecto. En su núcleo se encuentra CLAUDE.md — un archivo markdown que funciona como el documento de briefing permanente de la IA para tu base de código. Pero llamarlo "solo un archivo markdown" subestima lo que está ocurriendo.
Un CLAUDE.md bien estructurado suele contener:
- Decisiones de arquitectura que no son obvias al leer el código (por qué usas event sourcing, por qué la capa de autenticación está estructurada de esta manera, qué SDK de terceros tiene la trampa oculta que aprendiste de la peor forma posible)
- Convenciones que no están reforzadas por herramientas (patrones de nomenclatura, formatos de mensajes de commit, qué abstracciones son fundamentales frente a cuáles son experimentales)
- Anti-patrones explícitos — la lista de "no hagas esto" que normalmente solo vive en la cabeza de los ingenieros senior que ya se han quemado antes
- Comandos de prueba y compilación para que el modelo pueda ejecutar verificaciones sin necesidad de preguntar
- Restricciones específicas del equipo como "nunca modifiques el módulo de facturación sin incluir una señal de segundo revisor en tu respuesta"
Más allá de CLAUDE.md, la carpeta puede contener definiciones de slash commands — plantillas de prompts reutilizables almacenadas como archivos markdown en .claude/commands/. Un equipo podría definir /review como "revisar este PR según nuestra checklist específica", o /incident como "ayúdame a redactar un postmortem en nuestro formato estándar". Son atajos con alcance de proyecto que viajan junto al repositorio.
El Problema de Contexto que Esto Resuelve
Todo desarrollador que ha usado un asistente de codificación con IA durante más de unas pocas sesiones ha chocado contra la misma pared: el modelo no recuerda nada. Le explicas tu arquitectura el lunes y el martes, en la siguiente sesión, vuelves a explicársela. La IA te da consejos genéricos porque no sabe que estás usando una configuración de base de datos inusual o que tienes una restricción firme contra añadir nuevas dependencias sin una votación del equipo.
Este es el problema que la carpeta .claude/ está resolviendo silenciosamente. Es una forma de memoria de proyecto externalizada — contexto que antes solo existía en la cabeza de las personas (o disperso en documentos de Notion que nadie lee) y que ahora vive en una ubicación legible por máquina que se carga al inicio de cada sesión.
El artículo reciente del GitHub Blog sobre cómo Squad ejecuta agentes de IA coordinados dentro de repositorios aborda un desafío relacionado: cuando ejecutas múltiples agentes sobre la misma base de código, el contexto de proyecto compartido no es opcional. Sin él, los agentes se contradicen entre sí, duplican trabajo o violan convenciones que no están escritas en el código.
La carpeta .claude/ es la versión para un solo agente de esa misma idea, aplicada a escala humana.
Cómo es una Buena Estructura
Los desarrolladores que experimentan con Claude Code — incluyendo varios que han documentado sus configuraciones en dev.to — están convergiendo en algunos patrones estructurales:
Mantén CLAUDE.md podado sin piedad. Más largo no es mejor. Cada línea compite por atención en la ventana de contexto. El objetivo es el briefing mínimo viable — las cosas que el modelo genuinamente no puede inferir al leer la base de código. Las decisiones de arquitectura van. Las preferencias de estilo que ya están reforzadas por linters, no.
Separa los comandos por flujo de trabajo, no por frecuencia. Una carpeta .claude/commands/ con un único comando masivo de "hacer todo" es peor que no tener ningún comando. Las buenas bibliotecas de comandos reflejan flujos de trabajo reales: revisión de código, respuesta a incidentes, generación de descripciones de PR, redacción de changelogs. Cada comando es preciso y tiene una opinión clara.
Ponlo bajo control de versiones, pero trátalo como documentación. La carpeta .claude/ merece el mismo proceso de revisión que tu README o tu carpeta docs/. No es configuración — es una descripción viva de cómo trabaja tu equipo. Cuando cambia tu arquitectura, CLAUDE.md debería cambiar en el mismo PR.
No pongas secretos en ella. Esto es obvio en retrospectiva, pero ya ha quemado a gente. El archivo CLAUDE.md se carga en el contexto y potencialmente se registra en logs. Trátalo como documentación pública incluso en repositorios privados.
La Implicación Organizacional de la que Nadie Habla
Aquí es donde se pone interesante: mantener una buena carpeta .claude/ requiere que alguien en tu equipo entienda el sistema lo suficientemente bien como para articularlo. Eso suena obvio, pero muchas bases de código han crecido hasta un punto en que nadie puede escribir el CLAUDE.md sin descubrir lagunas en su propio entendimiento.
El ejercicio de escribirlo fuerza el tipo de documentación que los equipos postergan perpetuamente. Es la misma dinámica sobre la que Simon Willison ha escrito en el contexto de los prompts — la disciplina de explicar tus restricciones con precisión revela cuáles nunca has hecho realmente explícitas.
También hay un ángulo de transferencia de conocimiento. Cuando se une un nuevo ingeniero, la carpeta .claude/ puede proporcionar contexto de incorporación en una forma que es inmediatamente accionable. En lugar de leer documentación y esperar que hayan absorbido las advertencias importantes, pueden iniciar una sesión de Claude Code e interactuar con la base de código en un contexto que refleja tus convenciones de trabajo reales.
La cobertura de InfoQ sobre la arquitectura de sistemas portátiles con estándares abiertos toca una tensión relevante aquí: a medida que los equipos invierten más en configuración de proyectos específica para IA, surge una pregunta real sobre portabilidad. Una carpeta .claude/ es específica de Claude Code. Si cambias de herramienta — o cuando inevitablemente uses múltiples herramientas — esa inversión no se transfiere automáticamente.
Algunos equipos se están cubriendo escribiendo CLAUDE.md de una manera que es, en realidad, un superconjunto: útil para cualquier herramienta de IA que acepte archivos de contexto en markdown, no solo Claude. Las convenciones que captura el archivo son agnósticas a la herramienta, aunque el nombre del archivo no lo sea.
La Convención que Necesita un Estándar
La carpeta .claude/ está llenando un vacío real, pero lo está haciendo de manera fragmentada. Diferentes equipos ponen diferentes cosas en ella, no existe un esquema para CLAUDE.md, y no hay una guía mantenida por la comunidad sobre cómo es una configuración de calidad para producción.
Ese es el estado natural de una convención que emergió de la práctica en lugar del diseño. La pregunta es si el ecosistema avanza hacia algo más estandarizado — un esquema compartido, interoperabilidad entre herramientas, quizás un registro open-source de patrones de comandos útiles — o si el contexto de IA a nivel de proyecto se queda siendo la capa de configuración permanentemente ad hoc que es hoy.
Por ahora, lo que más impacto puede tener para la mayoría de los equipos es simple: abrir un CLAUDE.md, escribir tres cosas que la IA sigue haciendo mal porque no conoce tu base de código, y hacer commit. Ese es el punto de partida.
Todo lo demás es iteración.
Fuentes: GitHub Blog sobre agentes de IA coordinados · Dev.to sobre codificación asistida por IA en la práctica · InfoQ sobre arquitectura de sistemas portátiles · Blog de Simon Willison