# La Arquitectura dual del contexto inteligente

## Lado izquierdo: CLAUDE.md (las reglas generales)

Imagina que llegas a trabajar a una empresa.

Lo primero que te entregan es un **manual del empleado**.

Ahí encuentras cosas como:

*   cómo está organizada la empresa
    
*   cómo hacer commits en Git
    
*   cómo ejecutar pruebas
    
*   convenciones de código
    
*   cosas que nunca debes hacer
    

Eso es el **CLAUDE.md**.

La imagen dice que este archivo contiene:

*   **Root of repository**
    
    *   Está en la raíz del proyecto.
        
*   **Handles architecture**
    
    *   Explica la arquitectura general.
        
*   **Git workflow & testing approach**
    
    *   Cómo trabajar con Git y cómo ejecutar pruebas.
        
*   **Global anti-patterns**
    
    *   Cosas prohibidas o malas prácticas.
        

Es decir, información que **siempre** es útil.

Podrías imaginar algo así:

> `Proyecto:`
> 
> *   `Arquitectura Hexagonal`
>     
> *   `Java 21`
>     
> *   `Spring Boot 3`
>     
> 
> `Reglas:`
> 
> *   `Nunca acceder a la BD desde un Controller`
>     
> *   `Todo cambio debe tener pruebas`
>     
> *   `Usar Conventional Commits`
>     
> 
> `Estilo:`
> 
> *   `Constructor Injection`
>     
> *   `No usar Field Injection`
>     

Toda la IA necesita saber esto en cualquier tarea.

## Lado derecho: .claude/skills/

Ahora imagina que eres un ingeniero nuevo.

No siempre necesitas saber cómo funciona absolutamente todo.

Si hoy vas a trabajar en facturación...

solo necesitas el manual de facturación.

Si mañana trabajas en pagos...

necesitas el manual de pagos.

Eso son las **Skills**.

Cada carpeta contiene conocimiento especializado.

Por ejemplo:

.claude/ skills/ kafka/ payments/ ddd/ mif/ oracle/

Cada skill explica un tema muy concreto.

### ¿Por qué dividirlo?

Porque si metieras TODO en **CLAUDE.md**...

> Arquitectura
> 
> Git
> 
> DDD
> 
> Oracle
> 
> Kafka
> 
> Docker
> 
> OpenAPI
> 
> ISO8583
> 
> Facturación
> 
> MIF
> 
> Validaciones
> 
> Seguridad
> 
> OAuth
> 
> Testing
> 
> ...

terminaría siendo un archivo de cientos de páginas.

La IA tendría que leer todo incluso cuando solo quieres cambiar un botón.

Eso consume contexto.

### Entonces...

El archivo principal dice:

> "Así funciona este proyecto."

Las Skills dicen:

> "Así funciona ESTE dominio específico."

### La analogía de la universidad

Piensa en una universidad.

Todos los alumnos reciben un reglamento general.

> Horario
> 
> Uniforme
> 
> Reglas
> 
> Calendario
> 
> Biblioteca

Ese sería el **CLAUDE.md**.

Luego cada carrera tiene sus propios libros.

Ingeniería:

> Álgebra
> 
> Programación
> 
> Redes

Medicina:

> Anatomía
> 
> Farmacología
> 
> Cirugía

Derecho:

> Derecho Penal
> 
> Civil
> 
> Constitucional

Esos libros son las **Skills**.

No todos los estudiantes necesitan leer todos los libros.

## ¿Por qué aparecen chips (microprocesadores)?

Los dibujos de chips representan módulos independientes de conocimiento.

En vez de una IA con un enorme bloque de información:

██████████████████████████

TODO EL CONOCIMIENTO

tienes pequeños módulos:

> \[DDD\]
> 
> \[Kafka\]
> 
> \[Oracle\]
> 
> \[OpenAPI\]
> 
> \[Payments\]
> 
> \[ISO8583\]

La IA carga solamente los que necesita.

### Relación con DDD

Esto tiene un paralelismo muy interesante con **Domain-Driven Design**.

En DDD no creas un sistema gigante con todo mezclado:

> Sistema
> 
> *   Productos
>     
> *   Pagos
>     
> *   Inventario
>     
> *   Clientes
>     

Lo divides en **Bounded Contexts**:

> Ventas
> 
> Inventario
> 
> Facturación
> 
> Pagos

Cada contexto conoce únicamente lo suyo.

Con Claude ocurre algo parecido:

CLAUDE.md | + reglas globales | + skills | + payments + kafka + ddd + mif + spring

El **CLAUDE.md** sería como la visión global del sistema, mientras que cada **Skill** se parece a un **Bounded Context**: encapsula conocimiento especializado que solo se carga cuando la tarea lo requiere.

Esa es precisamente la idea que la imagen quiere transmitir: el contexto para la IA no es un único documento enorme, sino una combinación de reglas universales (siempre presentes) y módulos especializados (cargados según la tarea). Esto hace que el asistente sea más eficiente, más preciso y mucho más fácil de mantener a medida que el proyecto crece.

Enjoy!

Joe