La ingeniería de contexto es arquitectura: 650 archivos después

De la guía: Claude Code Comprehensive Guide

Mi CLAUDE.md comenzó con 50 líneas. Seis meses después, había crecido hasta convertirse en una arquitectura distribuida de 650 archivos repartidos en siete capas. Esa evolución reveló que la ingeniería de contexto es arquitectura de software para un sustrato donde la memoria se degrada con cada token, y no ingeniería de prompts con más archivos.

El contexto determina lo que un agente de IA puede pensar, lo que recuerda y lo que olvida. Todas las demás decisiones de diseño dependen de él. Lo que sigue son seis meses de ingeniería de contexto en producción para Claude Code: la arquitectura, los fallos y el sistema que los sobrevivió.

La ingeniería de contexto para agentes de IA es la práctica de diseñar sistemas que entregan al agente las instrucciones correctas en el momento correcto y que, al mismo tiempo, garantizan que las instrucciones irrelevantes nunca se carguen. Va más allá de escribir un buen archivo de prompts: requiere una arquitectura por capas en la que reglas, skills, hooks, configuraciones y archivos de estado se cargan cada uno en eventos específicos del ciclo de vida. Lo que se excluye importa tanto como lo que se incluye, porque cada token irrelevante desplaza contexto que el agente realmente necesita para trabajar correctamente.

Resumen

El artículo de Böckeler sobre ingeniería de contexto (martinfowler.com, 2026)1 y el marco de pensamiento claro de Miessler2 hacen avanzar la conversación, pero ambos subestiman lo que exige el uso en producción. La ingeniería de contexto requiere diseñar un sistema donde las instrucciones correctas lleguen al agente en el momento correcto y las instrucciones incorrectas nunca se carguen. Mi sistema utiliza nueve reglas, 40 skills, 19 agentes, 84 hooks y 14 archivos de configuración distribuidos en una jerarquía de siete capas. La arquitectura reside en qué archivos se cargan y cuándo. Lo que se excluye importa tanto como lo que se incluye.


El contexto no es un archivo

La publicación semanal sobre «cómo escribir un CLAUDE.md» no da en el blanco. Escribir un buen CLAUDE.md es necesario pero insuficiente, del mismo modo que escribir buen código es necesario pero insuficiente para construir un buen sistema. La arquitectura es la estructura que determina cómo interactúan los componentes. En los sistemas de agentes, el contexto es esa estructura.

Lo que empezó con 50 líneas se había convertido en un monolito: mi primer CLAUDE.md tenía 200 líneas que abarcaban estándares de código, estructura de proyectos, preferencias, correcciones, filosofía, credenciales y el estado de los proyectos activos. Funcionó durante un mes. Luego ocurrieron tres cosas a la vez:

  1. El archivo superó las 300 líneas y empezó a contradecirse a sí mismo (la regla A decía «mantenlo simple», la regla B decía «agrega un manejo de errores exhaustivo»)
  2. El contexto del proyecto A se filtró al proyecto B (reglas específicas de iOS contaminando una sesión de desarrollo web)
  3. El agente gastaba tokens leyendo instrucciones irrelevantes para la tarea en curso

Los síntomas apuntan a problemas arquitectónicos, no de documentación: acoplamiento, fuga de alcance y desperdicio de recursos. Son las mismas fuerzas que impulsan las decisiones de arquitectura de software.3


Las siete capas

Después de seis meses de refactorización, mi sistema de contexto se estabilizó en una jerarquía de siete capas. Cada capa cumple un propósito distinto y se carga en un momento específico:

Capa Contenido Cuándo se carga Cantidad
1. Núcleo CLAUDE.md: filosofía, proyectos activos, correcciones Al inicio de cada sesión Un archivo, 205 líneas
2. Reglas Restricciones específicas de dominio (diseño de API, seguridad, testing, git) Al inicio de cada sesión Nueve archivos
3. Skills Módulos de conocimiento reutilizables con procedimientos y ejemplos Bajo demanda (invocados o activados automáticamente por hooks) 40 directorios
4. Agentes Especificaciones de revisores y generadores especializados Bajo demanda (mediante la herramienta Task) 19 archivos
5. Hooks Inyección automática de contexto en eventos del ciclo de vida Por eventos (inicio de sesión, pre-commit, post-tool) 84 scripts
6. Config Parámetros numéricos (umbrales, presupuestos, límites) Referenciados por hooks y skills 14 archivos JSON
7. Estado Seguimiento en vivo (linaje de agentes, calibración de confianza, costos) Referenciado por hooks 36 archivos

La idea clave es la separación de capas. Las reglas se cargan en cada sesión porque se aplican universalmente. Los skills se cargan bajo demanda porque son específicos de dominio. Los hooks se disparan ante eventos porque el momento importa. Cargar los 650 archivos al inicio de la sesión agotaría la ventana de contexto antes de que el agente leyera el primer mensaje del usuario.4

Un ejemplo concreto de cada capa:

Layer 1 (Core):     ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules):    ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills):   ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents):   ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks):    ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config):   ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State):    ~/.claude/state/agent-lineage.json — tracks active agent tree

Cada archivo de la jerarquía tiene una única responsabilidad y un disparador de carga claro. El hook (capa 5) se dispara en el pre-commit sin importar el tipo de proyecto. El skill (capa 3) se carga solo cuando empieza una tarea de FastAPI. Esa distinción determina el costo en tokens.


Tres fallos que moldearon la arquitectura

Fallo 1: el CLAUDE.md monolítico

Mi CLAUDE.md original contenía reglas de iOS, reglas web, patrones de diseño de API, convenciones de git, gestión de credenciales y principios filosóficos, todo en un solo archivo. El agente lo leía completo en cada sesión, incluso al construir un proyecto web que jamás tocaría SwiftUI.

El costo: el contexto irrelevante consumía unos 4.000 tokens estimados por sesión. A lo largo de 50 sesiones, eso suma aproximadamente 200.000 tokens gastados en instrucciones que el agente nunca usó.

La solución: extraer el contenido específico de dominio a archivos en rules/. rules/security.md se carga en cada sesión (la seguridad aplica en todas partes). rules/ios-security.md se carga solo cuando la sesión involucra proyectos de iOS. La publicación sobre gestión de la ventana de contexto documenta la economía de tokens que llevó a esta decisión.

Fallo 2: skills que quedaron obsoletos

Creé un skill de fastapi con ejemplos de FastAPI 0.109. Tres meses después, el proyecto usaba FastAPI 0.115 con patrones distintos. El skill enseñaba en silencio convenciones desactualizadas. El agente producía código que funcionaba, pero que no coincidía con el código base actual.

El costo: una sesión de depuración de 45 minutos para rastrear por qué un endpoint nuevo usaba un patrón de inyección de dependencias diferente al de todos los demás endpoints. El patrón venía del skill obsoleto, no del código base.

La solución: los skills hacen referencia a documentación versionada e incluyen una fecha de última verificación («last verified»). Más importante aún, el ciclo de calidad exige que el código generado coincida con los patrones existentes del código base, una verificación metacognitiva que detecta la desviación de un skill obsoleto sin importar su contenido.

Fallo 3: reglas contradictorias en distintas capas

CLAUDE.md decía «prefiere soluciones simples». Un skill decía «agrega un manejo de errores exhaustivo con lógica de reintentos y circuit breakers». Ambas eran razonables por separado. Juntas, producían resultados inconsistentes (a veces mínimos, a veces sobrediseñados) según qué instrucción ponderara más el agente en un turno determinado.

El costo: calidad de salida impredecible. El mismo tipo de tarea producía niveles de calidad distintos de una sesión a otra, lo que volvía al sistema poco confiable. Estas son las instrucciones contradictorias reales:

# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.

# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
  for all external API calls.

Ambas son correctas por separado. «Prefiere soluciones simples» es un buen consejo general. «Agrega lógica de reintentos para las llamadas externas» es un buen consejo específico del dominio. Pero un agente que lee las dos a veces omite la lógica de reintentos (siguiendo el principio de simplicidad) y a veces sobrediseña una función sencilla (siguiendo la instrucción de manejo de errores).

La solución: establecer una jerarquía de precedencia clara. CLAUDE.md fija principios («prefiere la simplicidad»). Las reglas fijan restricciones («valida toda entrada del usuario»). Los skills fijan procedimientos («así se construye un endpoint de FastAPI»). Cuando entran en conflicto, gana la capa más específica: el procedimiento de un skill prevalece sobre la orientación de un principio para la tarea concreta que cubre el skill. Esta resolución refleja cómo los lenguajes de programación manejan el alcance: lo local prevalece sobre lo global.5 La solución para el ejemplo anterior es agregar una salvedad al skill: «Agrega lógica de reintentos para las llamadas a API externas (esto prevalece sobre el principio general de simplicidad en el código que depende de la red, porque las llamadas externas fallan de forma intermitente y los reintentos no son sobrediseño)».


El presupuesto de contexto como restricción arquitectónica

La ventana de contexto no es infinita. La ventana de contexto estándar de 200K tokens de Claude6 parece grande hasta que mides qué la consume. (Existe una beta de 1M tokens mediante un encabezado de la API, que amplía el presupuesto proporcionalmente pero no elimina los compromisos: cargar 650 archivos agotaría incluso 1M tokens).

Consumidor Tokens típicos % de la ventana
System prompt + CLAUDE.md + reglas 8.000-12.000 4-6%
Historial de conversación 20.000-80.000 10-40%
Lecturas de archivos (por archivo) 5.000-20.000 2,5-10%
Salidas de herramientas (por llamada) 1.000-10.000 0,5-5%
Contexto de skills/agentes (bajo demanda) 3.000-15.000 1,5-7,5%

Las mediciones de consumo de tokens provienen de 50 sesiones de Claude Code que registré entre agosto de 2025 y febrero de 2026.7 Una sesión intensiva de 90 minutos puede agotar la ventana solo con lecturas de archivos e interacciones normales con herramientas. Ten en cuenta que la ventana de 200K es la capacidad total de entrada; la atención efectiva del modelo (la porción a la que atiende con alta fidelidad) es una cifra distinta y menor. La disciplina del presupuesto de contexto importa incluso cuando el uso total de tokens está muy por debajo del límite, porque las instrucciones al principio de un contexto largo reciben una atención más fiable que las que quedan en medio. El presupuesto de contexto impone compromisos arquitectónicos:

Cargar siempre la filosofía central, las correcciones activas y las reglas de seguridad. Las tres son baratas (4-6% del presupuesto) y de aplicación universal. Cargarlas cuando no hacen falta cuesta muy poco. Omitirlas cuando hacen falta cuesta resultados incorrectos.

Cargar bajo demanda skills, especificaciones de agentes y documentación de referencia. Cada skill cuesta entre el 5 y el 15% de la ventana y aplica a un solo dominio. Cargarlos solo cuando son relevantes preserva presupuesto para el trabajo real. Lo que dispara la carga de un skill es el tipo de tarea, no el tipo de sesión: una sesión de desarrollo web que se topa con una migración de base de datos necesita el skill de base de datos aunque no se haya cargado al inicio.

No cargar nunca documentos de traspaso obsoletos, configuraciones en desuso ni estado histórico. Cada archivo obsoleto consume presupuesto sin mejorar la salida. Peor aún, el contexto obsoleto degrada activamente la salida al enseñar patrones desactualizados. El patrón de ingeniería compuesta exige depurar periódicamente el contexto que ya no justifica su costo en tokens.

Presupuestar el contexto refleja el mismo compromiso que impulsa la indexación de bases de datos, las estrategias de caché y la gestión de memoria en el software tradicional.8 La restricción es distinta (tokens en lugar de bytes), pero la disciplina arquitectónica es idéntica.


Propagación de contexto en sistemas multiagente

Cuando el agente principal lanza un subagente mediante la herramienta Task, la elección del contexto que se propaga condiciona todas las demás decisiones de diseño. Mi sistema de deliberación multiagente usa 10 agentes de investigación. Cada agente necesita suficiente contexto para evaluar de forma independiente, pero demasiado contexto compartido provoca el problema de convergencia documentado en la publicación sobre boids: los agentes que comparten demasiado contexto llegan a conclusiones idénticas.

Las reglas de propagación:

Tipo de contexto ¿Se propaga? Por qué
Filosofía central Sí Coherencia entre agentes
Reglas de dominio Sí Estándares de calidad compartidos
Instrucciones específicas de la tarea Sí El trabajo en sí
Historial de conversación No La independencia requiere aislamiento
Hallazgos de otros agentes No (hasta la síntesis) Evita la convergencia prematura
Procedimientos de skills Selectivamente Solo los skills relevantes para el rol del agente

La arquitectura Ralph resuelve un problema relacionado: la propagación de contexto a través del tiempo (iteraciones), no entre agentes (procesos paralelos). Ambas comparten el mismo principio: propagar restricciones y principios, aislar los detalles de implementación.

La propagación en la práctica

Un ejemplo concreto aclara el compromiso. Cuando el agente principal lanza un subagente revisor de seguridad, el prompt de Task incluye:

## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py

## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)

El revisor de seguridad recibe 2.000 tokens de contexto en lugar de 40.000. Evalúa el código según criterios de seguridad sin la distracción de las decisiones de interfaz ni el sesgo de las conclusiones de otro agente. El aislamiento produce una evaluación independiente. Si el revisor de seguridad y el revisor de arquitectura señalan el mismo problema por separado, el hallazgo merece más confianza que si un revisor hubiera visto el informe del otro y estado de acuerdo.


Observar la calidad del contexto

El conteo de tokens es una métrica indirecta. La verdadera medida de la calidad del contexto es: ¿el agente produce la salida correcta en el primer intento?

Después de dar seguimiento a 50 sesiones, identifiqué tres señales de calidad:

Tasa de éxito en el primer intento. ¿Con qué frecuencia la primera respuesta del agente no requiere corrección? Con el CLAUDE.md monolítico, la tasa rondaba el 60%. Tras la arquitectura de siete capas, subió a aproximadamente el 80%. La mejora vino de eliminar contexto irrelevante (menos distracciones) y de agregar skills específicos de dominio (más conocimiento relevante).9

Este es un antes y después representativo del registro de seguimiento. La tarea es idéntica: «agregar limitación de tasa (rate limiting) a un endpoint de la API».

Antes (CLAUDE.md monolítico, julio de 2025). La primera respuesta del agente importó una biblioteca de limitación de tasa que el proyecto no usaba (siguió un ejemplo del skill obsoleto de FastAPI, que se había cargado junto con las reglas de iOS, las reglas de seguridad y 150 líneas de contenido no relacionado). La corrección: «usa la clase RateLimiter existente en app/middleware.py». Una corrección, clasificada como «error factual: falta contexto del código base».

Después (arquitectura de siete capas, noviembre de 2025). El mismo tipo de tarea, otro endpoint. La primera respuesta del agente usó el middleware RateLimiter existente, respetó la convención de nombres de parámetros de los endpoints vecinos y citó la fuente del patrón: «following the rate limiting pattern in app/middleware.py:42». No hizo falta ninguna corrección. El skill de FastAPI (capa 3) se cargó bajo demanda y contenía patrones actuales; las reglas de iOS no se cargaron porque la sesión no implicaba trabajo de iOS.

Para darle seguimiento por tu cuenta: etiqueta cada sesión del agente en un registro como «aceptada» o «corregida» después de la primera respuesta y calcula la proporción cada mes. La granularidad no tiene que ser precisa; las tendencias generales a lo largo de 20 sesiones o más son más útiles que los porcentajes exactos.

Tipo de corrección. Cuando el agente sí requiere corrección, ¿el error es factual (API equivocada, patrón equivocado) o de criterio (enfoque equivocado, prioridad equivocada)? Los errores factuales indican contexto faltante: al agente le faltaba la información necesaria para dar la respuesta correcta. Los errores de criterio indican contexto contradictorio o ambiguo: el agente tenía la información, pero ponderó mal instrucciones en competencia. La distinción importa porque la solución es distinta: los errores factuales requieren agregar contexto (una regla o un skill nuevos), mientras que los errores de criterio requieren aclarar el contexto (resolver un conflicto entre capas existentes). Dar seguimiento a los tipos de corrección revela qué capa necesita atención.

Presión de contexto al terminar la tarea. ¿Cuánto presupuesto de contexto queda cuando la tarea termina? Si la ventana está llena al 90% antes de llegar a la mitad de la tarea, la arquitectura de contexto está cargando demasiado material irrelevante. Mi sistema de hooks incluye un monitor de presión de contexto que avisa cuando el uso supera el 70%.


Recorrido de una sesión: qué se carga y cuándo

Un recorrido concreto aclara cómo interactúan las siete capas durante una tarea real. El escenario: le pido a Claude Code que «agregue limitación de tasa al endpoint /api/ab/event» en el proyecto blakecrosley.com.

Inicio de sesión (0 s). Claude Code carga la capa 1 (CLAUDE.md, 205 líneas, ~800 tokens) y la capa 2 (los 9 archivos de reglas, ~3.200 tokens). Contexto total consumido: ~4.000 tokens (2% de la ventana de 200K). El agente ya conoce mi filosofía de código, los requisitos de seguridad, las convenciones de diseño de API y el flujo de trabajo de git, sin importar lo que le pida.

Comienza la tarea (2 s). El agente lee la tarea y la identifica como una modificación de un endpoint de FastAPI. Se dispara la capa 5 (hooks): el hook UserPromptSubmit inyecta la fecha actual y el contexto de la sesión (~200 tokens). El agente no carga el skill de SwiftUI, ni las reglas de seguridad de iOS, ni el skill de prompts de Midjourney. Esos archivos existen, pero son irrelevantes. Excluirlos ahorra ~8.000 tokens.

Lecturas de archivos (5-30 s). El agente lee app/main.py, el código del endpoint existente y el archivo de pruebas. Cada lectura consume entre 5.000 y 15.000 tokens de contexto. Después de leer tres archivos: ~30.000-50.000 tokens consumidos (15-25% de la ventana).

Activación de skills (si hace falta). Si el agente necesita patrones específicos de FastAPI, carga la capa 3 (skills/fastapi/SKILL.md, ~2.500 tokens). El skill se carga porque la tarea lo requiere, no porque la sesión haya comenzado. Si fuera una tarea solo de CSS, el skill de FastAPI nunca se cargaría.

Implementación y verificación (de 30 s a 5 min). El agente escribe código, ejecuta pruebas e informa los resultados. Al terminar la tarea, el consumo de contexto suele estar entre 60.000 y 100.000 tokens (30-50% de la ventana). El presupuesto restante deja margen para preguntas de seguimiento, correcciones o una segunda tarea en la misma sesión.

La observación clave: las capas 1 y 2 consumen el 2% de la ventana y aplican a todas las tareas. El contenido de las capas 3 a 7 se carga de forma selectiva y consume entre el 5 y el 25% solo cuando es relevante. Si los 650 archivos se cargaran al inicio de la sesión, consumirían aproximadamente 150.000-200.000 tokens y dejarían casi sin espacio para el trabajo real.


El patrón de arquitectura distribuida

Nada en el sistema de siete capas es exclusivo de los agentes de IA. Refleja patrones de software ya establecidos:

Patrón de software Equivalente en contexto
Variables de entorno CLAUDE.md central (siempre cargado, global)
Archivos de configuración Reglas (cargadas al inicio, específicas de dominio)
Bibliotecas/módulos Skills (cargados bajo demanda, autocontenidos)
Microservicios Agentes (aislados, se comunican mediante protocolos)
Manejadores de eventos Hooks (disparados por eventos del ciclo de vida)
Base de datos Archivos de estado (persistentes, consultables)
Contratos de API Esquemas de configuración (parámetros numéricos compartidos)

El paralelo no es metafórico. Las mismas fuerzas (acoplamiento, cohesión, alcance, ciclo de vida) conducen a decisiones arquitectónicas idénticas.10 La ingeniería de contexto es ingeniería de software para un sustrato donde la «memoria» es un recurso escaso y degradable en lugar de uno abundante y persistente.11

Una validación independiente de esta arquitectura proviene del proyecto obra/superpowers, que desarrolló por su cuenta una estructura multicapa similar para el contexto de Claude Code: principios centrales en un archivo global, skills de dominio cargados bajo demanda y procedimientos de verificación separados de las instrucciones de comportamiento.12 Esa convergencia sugiere que la arquitectura por capas no es una decisión de diseño idiosincrática, sino una respuesta natural a las restricciones del sustrato.


Conclusiones clave

Para ingenieros que construyen sistemas de agentes:

  • Diseña el contexto como arquitectura de software, no como documentación. Qué se carga y cuándo, qué prevalece sobre qué y qué se propaga a los subagentes determina el comportamiento del agente más que cualquier instrucción individual. Aplica la misma disciplina de separación de responsabilidades que usas en el código.

  • Separa las capas según su ciclo de vida. Las reglas universales se cargan en cada sesión. El conocimiento específico de dominio se carga bajo demanda. El estado de cada sesión es transitorio. Mezclar ciclos de vida en un solo archivo crea justo los problemas de acoplamiento que la arquitectura de software existe para resolver.

Para equipos que escalan flujos de trabajo con IA:

  • Trata la ventana de contexto como un presupuesto. Los system prompts, las lecturas de archivos y las salidas de herramientas consumen la ventana de 200K tokens. Cada instrucción persistente compite con la memoria de trabajo. Mide lo que cargas y depura lo que no justifica sus tokens.

  • Las reglas de propagación determinan la calidad multiagente. Los subagentes necesitan principios compartidos para la coherencia y estado aislado para la independencia. Propagar demasiado contexto provoca convergencia. Propagar demasiado poco provoca incoherencia.

Ejercicio: audita tu sistema de contexto. Crea esta estructura de directorios y llénala con tus instrucciones actuales:

mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/

Luego responde: ¿qué archivos se cargan en cada sesión cuando deberían cargarse bajo demanda? ¿Qué archivos bajo demanda faltan? Anota las respuestas en un registro sencillo: etiqueta cada sesión como «correcta al primer intento» o «necesitó corrección» y revisa la proporción después de 20 sesiones.


Preguntas frecuentes

¿Cómo debo estructurar los archivos de contexto para agentes de programación con IA?

Extrae el contenido específico de dominio a archivos separados cuando supere las 20-30 líneas y cuando sea irrelevante en al menos algunas sesiones. Si escribes reglas específicas de iOS y reglas específicas de web en el mismo CLAUDE.md, el agente lee ambas sin importar el proyecto en curso. Mantén en el archivo central las restricciones universales (reglas de seguridad, estándares de código, principios filosóficos). Mueve los patrones específicos de dominio (endpoints de FastAPI, convenciones de SwiftUI, consultas de base de datos) a archivos bajo demanda que se carguen solo cuando la tarea los requiera.

¿Cómo sé cuándo un skill quedó obsoleto?

Hay dos señales: el agente produce código que funciona pero no coincide con los patrones actuales del código base, o el agente hace referencia a API o patrones de una versión anterior de un framework. Agrega una fecha de última verificación a cada skill y revísala cada trimestre. Más importante aún, el ciclo de calidad (¿el código generado coincide con los patrones existentes?) detecta la desviación de un skill obsoleto sin importar su contenido.

¿Cuál es el tamaño adecuado de un presupuesto de contexto?

Para una ventana de 200K tokens, reserva el 4-6% para el system prompt y las reglas (siempre cargados), deja el 40-60% para el historial de conversación y las lecturas de archivos (el trabajo real) y presupuesta el 10-15% para skills y contexto de agentes bajo demanda. Si la presión de contexto supera el 70% antes de llegar a la mitad de la tarea, estás cargando demasiado material irrelevante. Los porcentajes concretos dependen de la complejidad de la tarea: una refactorización de varios archivos consume más contexto que corregir un error en una sola función.

¿Cómo manejo instrucciones contradictorias entre capas?

Aplica una precedencia basada en el alcance: gana la capa más específica. Los skills (alcance local) prevalecen sobre las reglas (alcance de módulo), que a su vez prevalecen sobre CLAUDE.md (alcance global). Cuando descubras un conflicto, haz explícita la resolución en lugar de confiar en que el modelo lo resuelva de forma probabilística. Agrega una nota en la capa más específica: «Esto prevalece sobre el principio general X en este contexto concreto porque Y».


Esta publicación se apoya en Gestión de la ventana de contexto (economía de tokens) y en El sistema Ralph (memoria basada en el sistema de archivos). El sistema de hooks de Claude Code implementa la capa de automatización. Para patrones de coordinación de agentes, consulta Deliberación multiagente y De boids a agentes.



  1. Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, febrero de 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Bharani Subramaniam, colega de Böckeler, define la ingeniería de contexto como “curating what the model sees so that you get a better result.” La definición es correcta. Esta publicación sostiene que la estructura con la que se organiza y entrega esa información es una disciplina arquitectónica, no un ejercicio de documentación. ↩

  2. Daniel Miessler, “How to Talk to AI,” danielmiessler.com, junio de 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler sostiene que la verdadera habilidad detrás tanto de la ingeniería de prompts como de la ingeniería de contexto es pensar con claridad: la capacidad de expresar con exactitud lo que se quiere lograr. Ese enfoque complementa esta publicación, que se centra en la disciplina estructural de organizar el contexto más que en pensar con claridad sobre él. ↩

  3. El paralelo con la arquitectura de software es deliberado. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017, parte III (Design Principles) y parte V (Architecture). Martin identifica las mismas fuerzas: acoplamiento, cohesión y separación de responsabilidades. La diferencia en los sistemas de contexto de IA es que la «memoria» es efímera y acotada, lo que añade una restricción que la arquitectura tradicional no enfrenta. ↩

  4. El conteo de 650 archivos es la medición del autor a febrero de 2026. Contexto global: ~400 archivos (reglas, skills, agentes, hooks, configuraciones, estado, documentos, traspasos). Contexto específico del proyecto (blakecrosley.com): ~250 archivos (PRD, documentos, planes, flujos de trabajo, configuraciones de i18n). Solo una fracción se carga por sesión. ↩

  5. La resolución del alcance de variables en los lenguajes de programación (local, envolvente, global, incorporado) es la analogía directa. La regla LEGB de Python define la misma jerarquía: alcance local, alcance de la función envolvente, alcance global, alcance incorporado. Consulta Python Software Foundation, “Execution Model,” sección 4.2.2, “Resolution of names.” docs.python.org/3/reference/executionmodel.html. Los skills (alcance local) prevalecen sobre las reglas (alcance de módulo), que prevalecen sobre CLAUDE.md (alcance global). La analogía falla un poco porque el seguimiento de instrucciones de un LLM es probabilístico, no determinista, pero el principio arquitectónico se mantiene. ↩

  6. Anthropic, “Models overview,” platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. Todos los modelos actuales de Claude (Opus 4.6, Sonnet 4.6, Haiku 4.5) especifican una ventana de contexto de 200K tokens, y Opus 4.6 y Sonnet 4.6 admiten 1M tokens en beta. ↩

  7. Mediciones de consumo de tokens de 50 sesiones de Claude Code que registré entre agosto de 2025 y febrero de 2026. Consulta Gestión de la ventana de contexto para conocer la metodología completa. ↩

  8. La analogía entre los presupuestos de tokens y las jerarquías de memoria sigue el marco de Hennessy, J.L. y Patterson, D.A., Computer Architecture: A Quantitative Approach, 6.ª edición, Morgan Kaufmann, 2017, capítulo 2 (Memory Hierarchy Design). El tratamiento que Hennessy y Patterson hacen de las jerarquías de caché, la localidad de referencia y el costo del acceso a memoria en distintos niveles se traslada directamente a la ingeniería de contexto: el contexto que se necesita con frecuencia (caché L1 / reglas centrales) se carga más rápido, mientras que el que se necesita rara vez (disco / skills bajo demanda) se carga solo cuando se hace referencia a él. ↩

  9. La tasa de éxito en el primer intento es una métrica aproximada basada en la evaluación subjetiva del autor sobre si la primera respuesta requirió corrección. No es un experimento controlado. La dirección de la mejora (del 60% al 80%) es consistente entre tipos de sesión, pero no debe citarse como una medición precisa. ↩

  10. James Lewis y Martin Fowler, “Microservices,” martinfowler.com, marzo de 2014. martinfowler.com/articles/microservices.html. Lewis y Fowler definen los microservicios como “a suite of small services, each running in its own process and communicating with lightweight mechanisms.” Las fuerzas que identifican (despliegue independiente, gobernanza descentralizada, contextos delimitados) se corresponden directamente con el aislamiento de agentes y la comunicación basada en protocolos de la arquitectura de contexto descrita aquí. ↩

  11. El enfoque de «contexto como arquitectura» se inspira en Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, diciembre de 2025. arxiv.org/abs/2512.05470. El artículo propone una abstracción de sistema de archivos para gestionar el contexto en sistemas de IA generativa, que trata diversos artefactos de conocimiento, la memoria y las herramientas como contexto dentro de los límites de tokens. Ese marco teórico respalda la arquitectura práctica descrita aquí. ↩

  12. obra/superpowers, github.com/obra/superpowers. El proyecto superpowers organiza el contexto del agente en instrucciones centrales, skills bajo demanda y procedimientos de verificación, una estructura que convergió con la arquitectura de siete capas descrita aquí pese a haberse desarrollado de forma independiente. Esa convergencia respalda la tesis de que el contexto por capas es una respuesta arquitectónica natural a las ventanas de contexto acotadas. ↩

Artículos relacionados

El Bucle Ralph: Cómo ejecuto agentes de IA autónomos durante la noche

Construí agentes autónomos con stop hooks, presupuestos de generación y memoria en archivos. Los fracasos y lo que produ…

12 min de lectura

Deliberación Multi-Agente: Cuando el Acuerdo Es el Error

La deliberación multi-agente detecta fallos que un solo agente pasa por alto. La arquitectura, los callejones sin salida…

22 min de lectura

El contexto es la nueva memoria

La ingeniería de contexto es la habilidad de mayor impacto en agentes: tres capas de compresión convierten una ventana d…

20 min de lectura