Estructurando Agentes de Código Claude con Patrones de CLAUDE.md y Directorio .claude/

Estructura del Directorio del Agente

La configuración implica crear directorios separados para cada agente en ~/Documents/. El ejemplo muestra cinco agentes: planner (función ejecutiva, enrutamiento, responsabilidad), content (canal de contenido), youtube (producción de YouTube), life (dominios personales) y control-center (panel de control, base de datos, API).

Cada agente sigue esta estructura de plantilla:

nombre-del-agente/
├── CLAUDE.md # Identidad + misión + capacidades
├── .claude/
│   ├── rules/ # Contexto cargado automáticamente (siempre activo)
│   └── skills/ # Flujos de trabajo bajo demanda
├── inbox/ # Entrada de otros agentes
├── outputs/ # Salida generada
└── archive/ # Nada se elimina sin archivarse

Distinción entre Reglas y Habilidades

Los archivos en .claude/rules/ se cargan automáticamente al inicio de cada sesión. Claude los lee como parte de su ventana de contexto. Aquí es donde se colocan las cosas que el agente necesita saber siempre: su alcance, contexto empresarial, cómo debe comportarse.

Los archivos en .claude/skills/ están bajo demanda. Solo se cargan cuando se invocan con /nombre-de-la-habilidad. Aquí es donde se colocan flujos de trabajo específicos como procesos de varios pasos, plantillas, rutinas estructuradas.

Los archivos de reglas se cargan en la ventana de contexto al inicio de la sesión y permanecen allí. Claude Code usa almacenamiento en caché de prompts para que el contenido repetido no se facture a precio completo en cada turno, pero los archivos de reglas grandes aún aumentan la presión del contexto y pueden causar degradación en las respuestas. Con las habilidades, solo el nombre y la descripción residen en el contexto por defecto; el flujo de trabajo completo se carga bajo demanda, ya sea cuando lo llamas o cuando Claude decide que es relevante.

Regla General

• Reglas (siempre activas): Límites de alcance, contexto empresarial, lógica de enrutamiento, convenciones de nomenclatura: cosas que afectan cada decisión.
• Habilidades (bajo demanda): Flujos de trabajo paso a paso, plantillas, operaciones por lotes. Cosas que haces ocasionalmente (Nota: las descripciones de las habilidades siempre están en el contexto para que Claude sepa lo que está disponible; solo el contenido completo está bajo demanda).

Contenido de CLAUDE.md

El archivo CLAUDE.md debe mantenerse en menos de 120 líneas y cubre:

• Identidad (2-3 líneas): quién es este agente y qué hace.
• Fase actual (2-3 líneas): en qué estamos trabajando ahora mismo.
• Capacidades principales (10-15 líneas): qué habilidades están disponibles, qué puede hacer.
• Ubicaciones clave (10-15 líneas): rutas de archivos que necesita consultar.
• Lo que se ha construido (10-20 líneas): historial de trabajos completados.
• Lo que sigue (5-10 líneas): prioridades inmediatas.
• Principios (5-10 líneas): barreras de comportamiento.

Ejemplo de Estructura de Reglas

Para un Agente de Planificación, el directorio .claude/rules/ contiene archivos numerados que controlan el orden de carga:

.claude/rules/
├── 01-business-context.md # Modelo de ingresos, posicionamiento, clientes objetivo
├── 02-agent-ecosystem.md # Todos los agentes, sus misiones, cómo se conectan
├── 03-roadmap.md # Fase actual, hitos, criterios de salida
├── 04-content-architecture.md # Canales de contenido, pilares, flujo de trabajo
├── 05-daily-routine.md # Horario, filtrado de ideas, reglas anti-distracción
├── 07-godin-strategy.md # Principios de marketing, seguimiento de hitos
├── 08-control-center.md # Referencia de herramientas CLI, esquema de BD
├── 98-end-of-session.md # Ritual: actualizar hoja de ruta, capturar conocimiento
└── 99-content-capture.md # Extracción automática de señales de contenido de cada sesión

Comunicación entre Agentes

Los agentes no se llaman directamente entre sí. Se coordinan a través de:

• Base de datos SQLite: Fuente de verdad para tareas, estado del canal de contenido, sesiones, métricas.
• Archivos de bandeja de entrada: Cuando un agente necesita pasar contexto a otro, deja un archivo markdown en la bandeja de entrada (inbox/) del objetivo.
• Puntos finales de API: Lecturas del panel de control.