Progressive Disclosure: la Arquitectura por Capas que Revoluciona la Eficiencia de Claude Code con archivos MD
Hoy en día, utilizar archivos .md para impartir instrucciones específicas a los Agents Code (como Claude Code) es necesario para obtener buenos resultados de inmediato sin deteriorar la ventana de contexto.
En el panorama de la inteligencia artificial aplicada al desarrollo de software, uno de los desafíos más relevantes concierne la gestión óptima de la context window. Cuando trabajamos con sistemas como Claude Code, cada token cuenta y la eficiencia en el uso del contexto disponible determina no solo la calidad de las respuestas, sino también la sostenibilidad económica y de rendimiento de todo el sistema. Es en este escenario donde emerge el concepto de progressive disclosure, una arquitectura inteligente que está redefiniendo la forma en que los agentes de IA acceden y procesan la información.
El Problema de la Context Window: un Cuello de Botella a Superar
Antes de adentrarnos en la arquitectura de progressive disclosure, es fundamental comprender la naturaleza del problema que esta metodología resuelve. La context window representa la cantidad máxima de información que un modelo de lenguaje puede procesar en un único momento. Por muy avanzados que sean los modelos como Claude, esta ventana permanece limitada y valiosa.
Imaginen tener que consultar una enciclopedia completa para responder a una simple pregunta: ¿cargarían todos los volúmenes simultáneamente o buscarían primero en el índice general? La respuesta es obvia, pero tradicionalmente muchos sistemas de IA han seguido precisamente el enfoque "enciclopédico", cargando en la context window enormes cantidades de documentación, skills y referencias, independientemente de su relevancia efectiva para la tarea específica.
Esta ineficiencia se traduce en tres problemáticas concretas:
- Saturación prematura de la context window con información irrelevante
- Aumento de los costos computacionales y de los tiempos de respuesta
- Potencial degradación de la calidad de las respuestas por "ruido informativo"
Progressive Disclosure: un Índice por Capas para la Inteligencia Artificial
La arquitectura de progressive disclosure representa un cambio de paradigma radical. En lugar de cargar todo el contenido disponible, el sistema opera a través de niveles progresivos de detalle, revelando información solo cuando es efectivamente necesaria.
La Primera Capa: Frontmatter y Metadata
Cuando Claude Code recibe una nueva tarea, la primera operación no consiste en cargar skills o documentaciones completas, sino en analizar exclusivamente el frontmatter de los archivos .md disponibles. Este frontmatter contiene metadatos esenciales:
---
name: "Form Validation"
description: "Gestión avanzada de la validación de formularios con React Hook Form y Zod"
category: "frontend"
tags: ["forms", "validation", "react"]
---
Esta operación cuesta muy pocos tokens, típicamente entre 10 y 30 por skill, permitiendo a Claude escanear rápidamente decenas de skills diferentes sin impactar significativamente en la context window. Es el equivalente a hojear el índice de un libro antes de decidir qué capítulo leer.
La Segunda Capa: SKILL.md y Panorama General
Una vez identificadas las skills potencialmente relevantes a través del frontmatter, Claude procede a la carga del archivo SKILL.md principal. Este documento proporciona:
# Form Validation Skill
## Objetivo
Implementar sistemas de validación de formularios robustos y user-friendly
## Principios Guía
- Validación client-side y server-side
- Feedback inmediato al usuario
- Schema-based validation con Zod
## Estructura
- forms.md: Patrones y componentes de formularios
- validation.md: Lógicas de validación avanzadas
- error-handling.md: Gestión de errores UX
El archivo SKILL.md actúa como un mapa conceptual, ofreciendo el panorama general sin entrar en los detalles de implementación. Permite a Claude comprender la arquitectura global de la skill, las reglas básicas y los principios fundamentales, permitiéndole tomar decisiones informadas sobre qué profundizaciones específicas podrían ser necesarias.
La Tercera Capa: Referencias Específicas On-Demand
Solo en este punto, si la tarea lo requiere explícitamente, Claude carga los archivos de referencia específicos. Si el trabajo concierne la creación de un formulario de registro, se cargará forms.md. Si en cambio se trata de implementar lógicas de validación complejas, será validation.md el que se consulte.
Este enfoque garantiza que la context window contenga exclusivamente información directamente aplicable a la tarea actual, maximizando la eficiencia y la pertinencia de las respuestas generadas.
Las Ventajas Concretas de la Arquitectura por Capas
Eficiencia de la Context Window
El beneficio más inmediato concierne el uso óptimo del espacio contextual disponible. En un escenario tradicional, cargar 10 skills completas podría consumir 50.000-100.000 tokens. Con progressive disclosure, la misma operación de descubrimiento requiere apenas 200-500 tokens para el escaneo del frontmatter, más 2.000-5.000 tokens para los SKILL.md relevantes, dejando amplio espacio para el contenido efectivamente necesario.
Escalabilidad del Sistema
A medida que la base de conocimiento de un agente de IA crece, la arquitectura tradicional se vuelve rápidamente insostenible. Con 50 o 100 skills disponibles, cargar todo preventivamente sería imposible. La progressive disclosure permite en cambio escalar casi linealmente, ya que el costo del descubrimiento permanece contenido independientemente del número total de skills disponibles.
Reducción de los Costos Operativos
Considerando que los modelos de IA avanzados tienen costos proporcionales a los tokens procesados, la optimización de la context window se traduce directamente en ahorros económicos significativos, especialmente en volúmenes elevados de solicitudes.
Mejora de la Calidad de las Respuestas
Contraintuitivamente, menos información puede generar mejores respuestas. Eliminando el "ruido" representado por documentación irrelevante, Claude puede concentrarse exclusivamente en los elementos pertinentes a la tarea, produciendo outputs más enfocados y precisos.
Implementación Práctica: Organización de los Archivos
La eficacia de la progressive disclosure depende fuertemente de la estructura organizativa de los archivos. He aquí un ejemplo de arquitectura óptima:
skills/
├── frontend/
│ ├── forms/
│ │ ├── SKILL.md # Panorama general
│ │ ├── forms.md # Patrones de formularios
│ │ ├── validation.md # Validación
│ │ └── error-handling.md # Gestión de errores
│ ├── state-management/
│ │ ├── SKILL.md
│ │ └── ...
├── backend/
│ ├── api-design/
│ │ ├── SKILL.md
│ │ └── ...
Cada directorio representa una skill autónoma, con el archivo SKILL.md como punto de entrada y los archivos de referencia como profundizaciones modulares.
Best Practices para Frontmatters Eficaces
La calidad del frontmatter determina la eficacia de todo el sistema. He aquí las características de un frontmatter óptimo:
---
name: "API Authentication & Authorization"
description: "Implementación de sistemas auth JWT, OAuth2, gestión de permisos RBAC"
category: "backend"
tags: ["auth", "security", "jwt", "oauth"]
complexity: "intermediate"
related: ["api-design", "security-best-practices"]
---
Elementos clave:
- Name conciso pero descriptivo: debe comunicar inmediatamente el ámbito de la skill
- Description rica en keywords: facilita el matching semántico con las tareas
- Tags específicos: permiten filtrado rápido por tecnologías o patrones
- Metadata estructurados: complexity y related ayudan a Claude a contextualizar
El Flujo de Ejecución: un Ejemplo Concreto
Veamos cómo opera Claude Code con progressive disclosure en un escenario real:
Tarea recibida: "Crea un formulario de login con validación de email y password, gestión de errores user-friendly"
Fase 1: Escaneo del Frontmatter
Claude analiza los frontmatters de todas las skills disponibles (costo: ~300 tokens para 30 skills). Identifica como relevantes:
# forms/SKILL.md frontmatter
name: "Form Validation"
description: "Gestión de formularios con validación"
# auth/SKILL.md frontmatter
name: "Authentication Patterns"
description: "Patrones de login, registro, recuperación de contraseña"
Fase 2: Carga de SKILL.md
Carga los archivos SKILL.md de las dos skills identificadas (costo: ~3.000 tokens). Comprende que:
- Para el formulario necesita consultar
forms/forms.mdyforms/validation.md - Para el contexto auth necesita
auth/login-patterns.md
Fase 3: Referencias Específicas
Carga solo los tres archivos de referencia identificados (costo: ~6.000 tokens). En este punto tiene todo lo necesario para generar la solución, habiendo consumido aproximadamente 9.300 tokens en lugar de los 50.000+ que hubieran sido necesarios cargando todo preventivamente.
Consideraciones Arquitecturales Avanzadas
Caching Inteligente
Una vez cargado un archivo de referencia, este podría permanecer en caché para tareas sucesivas correlacionadas, optimizando ulteriormente la eficiencia. Claude Code puede implementar estrategias de caching basadas en la probabilidad de que una referencia permanezca relevante para las próximas operaciones.
Resolución de Dependencias
Algunas skills dependen conceptualmente de otras. El archivo SKILL.md puede declarar estas dependencias a través del campo related, permitiendo a Claude cargar preventivamente referencias que serán casi con certeza necesarias.
---
name: "Advanced Form Patterns"
related: ["form-validation", "state-management"]
requires: ["form-validation"] # Dependencia obligatoria
---
Carga Adaptativa
Sistemas más sofisticados podrían implementar estrategias de carga adaptativa, donde Claude aprende de la experiencia qué referencias tienden a ser necesarias juntas, optimizando proactivamente la carga.
Limitaciones y Criticidades a Considerar
Como toda arquitectura, también la progressive disclosure presenta algunos desafíos:
Latencia Adicional
La carga progresiva introduce potencialmente latencias adicionales, ya que el contenido se recupera en más fases. En contextos donde la velocidad es crítica, podría ser necesario balancear disclosure progresiva con pre-loading estratégico.
Complejidad de Mantenimiento
Mantener frontmatters precisos y descripciones siempre actualizadas requiere disciplina. Un frontmatter obsoleto puede llevar a Claude a ignorar skills relevantes o cargar las equivocadas.
Sobre-Segmentación
Existe el riesgo de fragmentar excesivamente el conocimiento, creando demasiados archivos pequeños que complican la gestión global. Encontrar el nivel justo de granularidad es un arte.
Un Cambio de Paradigma Necesario
La arquitectura de progressive disclosure no es simplemente una optimización técnica, sino que representa un cambio fundamental en la forma en que concebimos la relación entre agentes de IA y bases de conocimiento. Así como los seres humanos no memorizan enciclopedias completas sino que desarrollan estrategias para acceder eficazmente a la información cuando es necesario, así los sistemas de IA deben evolucionar hacia enfoques más inteligentes y selectivos.
Para quienes desarrollan con Claude Code u otros sistemas basados en agentes, adoptar esta arquitectura significa no solo ahorrar tokens y costos, sino construir sistemas intrínsecamente más escalables, mantenibles y performantes. Es una inversión en una infraestructura que crece de manera sostenible con la expansión de la base de conocimiento.
La progressive disclosure nos enseña una lección fundamental: en la inteligencia artificial como en la vida, no siempre más información equivale a mejor comprensión. A veces, la verdadera inteligencia está en saber qué ignorar y cuándo buscar más.
