Cómo Estructurar CLAUDE.md y Configurar Permisos (2026)

El Problema: Tu CLAUDE.md Es Demasiado Largo

Si llevas tiempo usando Claude Code, tu archivo CLAUDE.md probablemente se convirtió en un monstruo. El mío llegó a 379 líneas antes de darme cuenta del problema.

¿Por qué importa? Porque CLAUDE.md se convierte en parte del system prompt de Claude en cada conversación. Cada línea cuesta tokens. Cada sección, sea relevante o no, se carga.

La recomendación de Anthropic es clara: menos de 300 líneas máximo, idealmente bajo 60.

HumanLayer, una empresa que construye herramientas de IA, mantiene su CLAUDE.md raíz en apenas 60 líneas.

¿Cómo llegamos ahí sin perder todas nuestras guías cuidadosamente documentadas?

Si apenas estás comenzando con Claude Code, te recomiendo primero leer nuestra guía completa sobre agentes de código IA para entender el contexto.

La Solución: Divulgación Progresiva con .claude/rules/

Después de investigar la documentación oficial de Anthropic y las mejores prácticas de la comunidad, descubrí que Claude Code tiene una característica poderosa pero subutilizada: el directorio .claude/rules/.

Cómo Funciona

Cualquier archivo markdown que coloques en .claude/rules/ se carga automáticamente con la misma prioridad que tu CLAUDE.md principal. No necesitas imports. Solo deja archivos ahí.

.claude/
├── commands/
│   └── tu-comando-personalizado.md
├── rules/                        # ← ¡Se carga automáticamente!
│   ├── arquitectura.md
│   ├── seguridad.md
│   ├── estilos.md
│   └── testing.md
└── settings.local.json

Esto te da:

• Organización modular - Cada tema en su propio archivo
• Misma prioridad - Todas las reglas se tratan igual
• Compartir con el equipo - Haz commit a git, todos obtienen las mismas reglas
• Mantenimiento fácil - Actualiza un archivo sin tocar otros

El Sistema de Memoria Jerárquico

Claude Code lee memorias de múltiples ubicaciones, en orden:

1. ~/.claude/CLAUDE.md - Personal, aplica a TODOS los proyectos
2. ~/.claude/rules/*.md - Reglas personales para todos los proyectos
3. Directorios padre - Para configuraciones de monorepo
4. CLAUDE.md en la raíz del repositorio - Específico del proyecto, compartido con el equipo
5. .claude/rules/*.md - Reglas del proyecto (se cargan automáticamente)
6. CLAUDE.md en subdirectorios - Se carga cuando trabajas en ese subárbol

Los archivos más arriba en la jerarquía proporcionan una base sobre la que las memorias más específicas construyen.

Para un análisis más profundo de las actualizaciones recientes de Claude Code incluyendo mejoras en CLAUDE.md, consulta nuestro post sobre las actualizaciones de Claude Code 2.0.

Sintaxis de Import: Referencia Otros Archivos

Los archivos CLAUDE.md soportan una sintaxis de import usando @ruta/al/archivo:

# Guías del Proyecto

Ver @README.md para el overview del proyecto.
Ver @docs/arquitectura.md para el diseño del sistema.

## Flujo de Git
Seguir las instrucciones en @docs/git-workflow.md

Esto te permite:

• Referenciar documentación existente sin duplicar
• Mantener tu CLAUDE.md escaneable
• Importar recursivamente (máximo 5 niveles de profundidad)

¿Qué Debe Quedarse en CLAUDE.md?

Tu CLAUDE.md principal debe contener solo contenido universalmente aplicable:

✅ Mantener en CLAUDE.md

• Overview del proyecto (1-2 oraciones)
• Comandos de desarrollo (npm run dev, npm run build)
• Resumen del stack tecnológico
• Ubicaciones de archivos clave
• Info de deployment
• Reglas rápidas (4-5 bullet points máximo)

❌ Mover a .claude/rules/

• Guías de código detalladas
• Políticas de seguridad
• Convenciones de estilos
• Patrones de arquitectura
• Estrategias de testing
• Documentación de componentes

❌ No Incluir en Absoluto

• API keys o secretos
• Connection strings de base de datos
• Info detallada de vulnerabilidades de seguridad
• Instrucciones que solo aplican a tareas raras

Ejemplo Real: Mi Proyecto Reestructurado

Antes (379 líneas)

# CLAUDE.md

## Project Overview
...

## Architecture
### Server Components
(50 líneas de ejemplos)

### Client Components
(30 líneas de ejemplos)

## Security Guidelines
(60 líneas)

## Styling Guidelines
(40 líneas)

## Performance
(50 líneas)

... y así sucesivamente

Después (74 líneas)

# CLAUDE.md

## Project Overview
MX WHMCS Modules - Sitio web Next.js 15 para módulos WHMCS.
Objetivos: Rápido, confiable, seguro. Priorizar SSR.

## Commands
npm run dev      # Servidor dev (localhost:3000)
npm run build    # Build de producción
npm run lint     # ESLint

## Tech Stack
- Next.js 15.5.0 (App Router, Turbopack)
- React 19.1.0
- Tailwind CSS 4
- Path alias: @/* → ./src/*

## Quick Rules
1. Server Components por defecto
2. SSOT solo para precios
3. Color primario: Teal (text-primary-700 para WCAG)
4. Un H1 por página

## Deployment
Plataforma: Coolify | Branch: main | Dominio: mxwhmcsmodules.com

---

## Detailed Guidelines
Ver `.claude/rules/`:
- architecture.md - SSR, componentes, performance
- products.md - Patrones SSOT
- styling.md - Tailwind, accesibilidad WCAG
- security.md - XSS, env vars, staging mode

El Directorio Rules

.claude/rules/
├── architecture.md   (3.3 KB) - Componentes, SSR, data fetching
├── products.md       (1.7 KB) - Configuración SSOT
├── styling.md        (1.7 KB) - Tailwind, colores, WCAG
└── security.md       (1.8 KB) - XSS, env vars, staging

Comandos Slash Personalizados

Ya que estamos, no olvides .claude/commands/. Cualquier archivo markdown aquí se convierte en un comando slash:

.claude/commands/
├── seo-check.md      → /project:seo-check
├── deploy.md         → /project:deploy
└── fix-issue.md      → /project:fix-issue

Ejemplo de archivo de comando:

# Comando SEO Check

Ejecuta el validador SEO y corrige los problemas:

1. Ejecutar: npm run seo
2. Reportar resultados
3. Ofrecer corregir problemas encontrados

Puedes usarlo con argumentos: /project:fix-issue 1234

Si quieres ver cómo estos comandos se integran con testing automatizado, revisa nuestro artículo sobre TestSprite para testing autónomo con IA.

Resumen de Mejores Prácticas

Archivos Locales vs Compartidos

• CLAUDE.md - Compartido con el equipo (en git)
• CLAUDE.local.md - Preferencias personales (auto-gitignored)
• .claude/rules/*.md - Reglas compartidas (en git)
• ~/.claude/rules/*.md - Reglas personales para todos los proyectos

Templates de Permisos: Usa Claude Sin Miedo

El archivo .claude/settings.json (o settings.local.json para preferencias personales) permite configurar permisos granulares. No todos los proyectos son iguales.

Template: Proyecto Personal

{
  "permissions": {
    "read": "allow",
    "edit": "allow",
    "bash": { "*": "allow" }
  }
}

Claude puede leer, editar y ejecutar cualquier comando. Útil cuando solo tú trabajas en el proyecto.

Template: Proyecto de Producción (Recomendado)

{
  "permissions": {
    "read": "allow",
    "edit": "ask",
    "delete": "deny",
    "bash": {
      "npm run *": "allow",
      "npm test": "allow",
      "git status": "allow",
      "git diff": "allow",
      "git commit": "ask",
      "git push": "deny",
      "*": "ask"
    }
  }
}

Este template permite:

• Lectura libre: Claude explora todo el codebase (su principal ventaja)
• Ediciones con confirmación: Siempre pregunta antes de modificar
• Scripts de desarrollo: npm run, test, build sin interrupciones
• Git seguro: Ve estado y diff, pregunta antes de commit, nunca push

Por Qué la Lectura Libre Es Importante

La diferencia entre Claude Code y otras herramientas (Codex, Antigravity) es que Claude explora proactivamente. Si necesita entender una dependencia en otra carpeta, va y la lee.

Bloquear la lectura convierte a Claude en un agente "ciego". La configuración ideal es:

• Lectura: Libre (deja que explore)
• Escritura: Con confirmación (tú decides)
• Git push: Bloqueado (nunca sin supervisión)

Para más contexto, lee Codex vs Claude Code: Review Honesto.

El Comando /init

¿Empezando desde cero? Claude Code puede generar un CLAUDE.md para ti:

/init

Claude examina tu codebase (leyendo archivos de configuración, documentación, configs y estructura de código) y genera un CLAUDE.md personalizado.

Revisa y refina el output basándote en las prácticas reales de tu equipo.

Combinando con Otras Herramientas de IA

Esta estructura modular funciona especialmente bien cuando combinas Claude Code con otras herramientas:

• Context7 para mantener documentación actualizada que alimenta tu CLAUDE.md
• Gemini Code Assist para tareas específicas del ecosistema Google
• Google Antigravity si necesitas testing visual con browser control

La clave está en que cada herramienta tenga acceso al contexto correcto sin sobrecargarse.

Fuentes y Lecturas Adicionales

• Claude Code: Best practices for agentic coding - Blog oficial de ingeniería de Anthropic
• Using CLAUDE.MD files - Blog oficial de Claude
• Manage Claude's memory - Documentación oficial
• Writing a good CLAUDE.md - HumanLayer (tips prácticos)
• The Complete Guide to CLAUDE.md - Builder.io
• GitHub: claude-code-best-practices - Ejemplos de la comunidad

Conclusión

El insight clave es que CLAUDE.md debe tratarse como cualquier otro prompt: conciso, enfocado, e iterativamente refinado.

Al mover guías detalladas a .claude/rules/ y mantener tu archivo principal bajo 100 líneas, lograrás:

• Reducir uso de tokens en cada sesión
• Hacer la documentación más fácil de mantener
• Habilitar divulgación progresiva de información
• Seguir los patrones recomendados por Anthropic

Empieza auditando tu CLAUDE.md actual. Si tiene más de 300 líneas, es hora de reestructurar.

Servicios de Nandark

¿Quieres optimizar tu flujo de trabajo con Claude Code y otras herramientas de IA?

En Nandark implementamos configuraciones de desarrollo asistido por IA que maximizan la productividad de tu equipo.

Conoce nuestros servicios de desarrollo o conversemos sobre tu proyecto.

Recursos Relacionados:

• Guía completa de agentes de código IA
• Actualizaciones de Claude Code 2.0
• Cómo construimos nandark.com con Claude Code
• 🇺🇸 Claude Code Setup for Teams (EN)

Escrito después de reestructurar un CLAUDE.md de 379 líneas a 74 líneas mientras se preservaban todas las guías.

Tags: Claude Code, Desarrollo con IA, Herramientas de Desarrollo, Documentación, Mejores Prácticas