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
