Context Layer en Claude Code: el contexto distribuido del codebase
La Context Layer es la capa fina y eficiente en tokens que vive sobre tu codebase y le dice al agente qué habla con qué, qué contratos no se pueden romper, qué decisiones arquitectónicas respetar y dónde están los ejemplos canónicos. Es la versión sistematizada del conocimiento que un ingeniero senior tiene en la cabeza tras dos años en el proyecto. Cuando existe, un junior con un prompt mediocre produce resultados de senior; cuando no, ni un senior con prompts cuidadosos logra consistencia.
El problema que resuelve: en un codebase grande, le pides a Claude Code agregar una feature flag y termina tocando 150 archivos, olvidando el repo paralelo de flags y rompiendo producción aunque el código compile. No es fallo del modelo: es la consecuencia previsible de un codebase sin Context Layer.
Los cuatro componentes
La Context Layer es un sistema de cuatro piezas interconectadas dentro del repositorio:
- Nodos (
CLAUDE.mddistribuidos): no uno por directorio, uno por frontera semántica. Cada nodo documenta una porción del código: su responsabilidad, los contratos que cuida, sus ejemplos canónicos, qué skills y hooks aplican y qué nodos vecinos existen. - Skills: capacidades modulares invocables on-demand (workflows, checklists, plantillas) que no conviene cargar siempre.
- Hooks: validaciones obligatorias que el runtime garantiza. El cinturón de seguridad para invariants que no pueden depender del criterio del modelo.
- Ejemplos concretos: archivos reales del codebase referenciados como plantilla canónica. Cien líneas de código bien escrito comunican más que mil de prosa.
El nodo: la pieza fundacional
Cuando Claude Code edita un archivo, carga la jerarquía de nodos hasta ese punto, y solo esos. El resto del codebase queda fuera del contexto. Es como un GPS para el agente: en cada cruce recibe exactamente la indicación que necesita para el siguiente tramo, sin la información del resto de la ciudad.
Dónde van los nodos: fronteras semánticas
La tentación es poner un CLAUDE.md en cada carpeta. No lo hagas: terminas con cincuenta nodos triviales que aportan ruido. Los nodos van en tres tipos de lugar:
- Cambios de responsabilidad: donde el código deja de hacer una cosa y empieza otra (API vs frontend, auth vs pagos).
- Contratos críticos: donde dos partes tienen una promesa que no se puede romper sin coordinación (un endpoint que consume una app móvil más lenta, un schema que leen tres servicios).
- Especialización con contexto dedicado: zonas con su propio idioma técnico (un módulo de cálculo, un sistema legacy, algo crítico para compliance).
La regla operativa: "si elimino este nodo, ¿el agente podría seguir trabajando bien aquí?". Si la respuesta es sí, el nodo es ruido. Si es no, justifica su existencia.
Nota técnica: Claude Code lee
CLAUDE.md, noAGENTS.md. Si tu repo usaAGENTS.mdpara otros agentes, haz que elCLAUDE.mdlo importe con la línea@AGENTS.mdpara compartir instrucciones.
Preguntas frecuentes
¿Qué es la Context Layer en Claude Code?
Es una capa fina sobre el codebase, hecha de archivos CLAUDE.md distribuidos, skills, hooks y ejemplos, que le dice al agente qué responsabilidades, contratos y convenciones aplican a cada zona del código. Sistematiza el conocimiento que un ingeniero senior acumula en años, para que el agente produzca resultados consistentes.
¿Dónde se colocan los archivos CLAUDE.md en la Context Layer?
En fronteras semánticas, no en cada carpeta: donde cambia la responsabilidad del código, donde hay un contrato crítico entre partes, o donde una zona necesita contexto especializado. Si un directorio no es ninguno de los tres, hereda del nodo superior y no necesita el suyo.
¿Por qué Claude Code rompe cosas en codebases grandes?
Porque sin una Context Layer, el agente no conoce los contratos implícitos, las dependencias no documentadas ni las decisiones arquitectónicas. Toca archivos que no debía y olvida sincronizaciones críticas. La Context Layer le entrega ese conocimiento justo en la zona que está editando.
¿Qué componentes forman la Context Layer?
Cuatro: nodos (CLAUDE.md distribuidos por frontera semántica), skills invocables on-demand, hooks que validan invariants críticos, y ejemplos concretos del codebase usados como plantilla canónica.
Recursos relacionados
- Ingeniería de contexto y Long Context Failure.
- CLAUDE.md y su jerarquía · skills · hooks.
- Guía completa para dominar Claude Code.
Tu siguiente paso
Las reglas de contexto están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).