Claude Code sin magia: Habr analiza la arquitectura, el ruido de contexto y las prácticas de ingeniería

En Habr se publicó una traducción de un gran texto práctico sobre Claude Code, basado en medio año de trabajo intensivo con el agente. No se trata de un resumen de características, sino de un análisis de por qué una herramienta de IA para desarrollo comienza a fallar cuando se le proporciona demasiado contexto, reglas y libertad simultáneamente.

Dónde se Pierde el Contexto

La idea principal del artículo es simple: Claude Code no falla porque el modelo "no sea lo suficientemente inteligente", sino porque el entorno de ingeniería que lo rodea está mal estructurado. El autor describe el agente como un ciclo de recopilación de contexto, acción y verificación de resultado. Si incluso una capa en este ciclo se sobrecarga, la calidad cae drásticamente: un CLAUDE.md largo genera ruido, docenas de herramientas complican la toma de decisiones, y la falta de verificación rápida convierte cada edición en una apuesta. En tal modo, el desarrollador comienza a ajustar interminablemente prompts, aunque el problema esté más profundo.

El costo del contexto se discute por separado. Formalmente, Claude Code tiene una ventana grande, pero una porción significativa de tokens se gasta antes de que comience el trabajo: en instrucciones del sistema, descriptores de skills, descripciones de herramientas MCP, estado LSP, memoria y CLAUDE.md del proyecto. El autor proporciona un cálculo revelador: un único servidor MCP típico puede ocupar miles de tokens solo para esquemas de herramientas, y algunos servidores conectados consumen fácilmente una porción notable de la ventana disponible. Añade a esto resultados largos de pruebas, grep y registros—y el historial de diálogo útil comienza a desplazarse por sí solo.

• Instrucciones del sistema y reglas básicas
• Descripciones de skills y herramientas MCP
• Memoria del proyecto y contenidos de CLAUDE.md
• Resultados de llamadas shell, pruebas y búsquedas
• Historial de sesión comprimido, pero no siempre preciso

De esto se deduce una conclusión práctica: el conocimiento raramente utilizado no debe vivir en un contexto constantemente cargado. Cuando cambias de tarea, es mejor usar más frecuentemente la limpieza de sesión; para continuar en una dirección—compresión gestionada. Otro consejo del artículo: pide al agente antes de una nueva sesión que recopile HANDOFF.md con progreso, callejones sin salida y estado de verificación. Esto es más barato y confiable que esperar que la compactación automática preservará verdaderas decisiones arquitectónicas importantes.

Skills, Hooks y Agentes

La segunda sección importante se dedica a la separación de funciones. El autor sugiere no mezclar MCP, herramientas, skills, hooks, plugins y subagents en un montón. La lógica es: una herramienta proporciona nueva capacidad, un skill establece el flujo de trabajo, un hook incorpora verificación automática obligatoria, y un subagent descarga una tarea separada en contexto aislado. Esta es una aclaración útil porque muchos equipos intentan arreglar cualquier fallo con un nuevo prompt u otra herramienta, cuando el problema podría resolverse en un nivel completamente diferente.

El artículo explica por separado cómo debe ser un buen skill. Tiene un descriptor corto y preciso, un disparador de uso comprensible, entradas documentadas, salidas y una condición de parada. Todo pesado—ejemplos, runbooks, archivos auxiliares—debe extraerse bajo demanda, no colgado en el SKILL.md principal. Para acciones con efectos secundarios, el autor aconseja desabilitar explícitamente la ejecución automática por el modelo. La idea es que el agente primero vea el índice y ruta, luego cargue detalles solo cuando realmente los necesite.

Los subagents en este desglose se presentan no como una forma de "acelerar todo en paralelo", sino como un medio de aislamiento. La investigación de la base de código, revisión, ejecución de pruebas y otras operaciones ruidosas se envían mejor a threads secundarios con permisos limitados, un modelo separado y formato de respuesta fijo. Los hooks, por el contrario, deben capturar cosas determinísticas lo antes posible: ejecutar una verificación rápida después de la edición de archivo, bloquear cambios peligrosos, mezclar contexto técnico al inicio de la sesión. Cuanto más temprano el sistema atrapa un error, menos tokens, tiempo y ediciones innecesarias se desperdician.

Cache, Verificación y Contrato

Una de las partes más interesantes del texto es la explicación de cuánto la arquitectura de Claude Code depende del prompt caching. El autor escribe que un prefijo de prompt estable ahorra no solo dinero sino que también reduce fricción con límites. De esto vienen varias reglas no obvias: no insertar datos dinámicos en el prompt del sistema, no barajar el orden de instrucciones, no cambiar modelos a mitad de una sesión larga sin necesidad, y cuando sea posible, aplazar la carga completa de esquemas de herramientas raras. Incluso Plan Mode, como se observa en el artículo, es más conveniente implementar sin cambiar el conjunto completo de herramientas, para evitar romper el cache.

El énfasis final se coloca en la verificación y el papel de CLAUDE.md. El autor llama a este archivo no una base de conocimiento, sino un contrato entre el proyecto y el agente: cómo recopilar, cómo probar, qué límites no pueden violarse, qué debe preservarse al comprimir, qué prohibiciones siempre se aplican. CLAUDE.md no necesita referencias de API e introducciones largas; solo las reglas que son críticas en cada sesión deben vivir allí. Un consejo separado: después de cada error repetido, pide al agente que actualice su contrato para que los errores típicos no vuelvan a ocurrir.

"Si no puedes explicar cómo saber que

Claude lo hizo correctamente, la tarea probablemente no sea adecuada para ejecución totalmente automática."

Qué Significa Esto

Este material es importante no solo para usuarios de Claude Code. Esencialmente, es una instrucción para la maduración de cualquier agente de IA para desarrollo: menos magia, más aislamiento, verificación explícita y control sobre contexto. Cuanto más activamente los equipos se mueven de "chatbot de código" a ingeniero semiautónomo, más valiosas se vuelven exactamente tales prácticas, en lugar de otra colección de prompts.