Claude Code sin magia: Habr analiza la arquitectura, el ruido de contexto y las prácticas de ingeniería
Habr ha traducido y comentado un extenso texto práctico sobre Claude Code, escrito tras seis meses de uso real. La idea central: los problemas suelen estar no en los prompts, sino en la arquitectura del agente, con un contexto ruidoso, descripciones de herramientas costosas, verificación débil y un CLAUDE.md sobrecargado. El material explica además cómo diseñar skills, hooks y subagents para que el agente no se desmorone en tareas largas.
Procesado por IA desde Habr AI; editado por Hamidun News
Habr ha publicado la traducción de un extenso texto práctico sobre Claude Code, basado en medio año de trabajo intensivo con el agente. No es un repaso de funciones, sino un análisis de por qué una herramienta de IA para desarrollo empieza a fallar cuando se le da demasiado contexto, demasiadas reglas y demasiada libertad a la vez.
Dónde se pierde el contexto
La idea principal del artículo es sencilla: Claude Code falla no porque el modelo "no sea lo bastante listo", sino porque el entorno de ingeniería que lo rodea está mal diseñado. El autor describe el agente como un ciclo de recopilación de contexto, acción y verificación del resultado. Si se sobrecarga aunque sea una sola capa de ese ciclo, la calidad cae en picado: un CLAUDE.md largo mete ruido, decenas de herramientas dificultan la elección, y la ausencia de una comprobación rápida convierte cada cambio en una lotería. En ese régimen, el desarrollador se pone a retocar prompts sin fin, aunque el problema esté más a fondo.
El artículo analiza aparte el coste del contexto. Formalmente, Claude Code tiene una ventana grande, pero una parte considerable de los tokens se gasta antes de empezar a trabajar: en instrucciones del sistema, descriptores de skills, descripciones de herramientas MCP, estado de LSP, memoria y el CLAUDE.md del proyecto. El autor aporta un cálculo revelador: un servidor MCP típico puede ocupar miles de tokens solo en esquemas de herramientas, y varios servidores conectados se comen fácilmente una parte notable de la ventana disponible. Si se suman salidas largas de tests, grep y logs, el historial útil de la conversación empieza a desplazarse por sí solo.
- Instrucciones del sistema y reglas básicas
- Descripciones de skills y herramientas MCP
- Memoria del proyecto y contenido de CLAUDE.md
- Resultados de llamadas a shell, tests y búsquedas
- Un historial de sesión comprimido, pero ya no siempre preciso
De ahí se desprende una conclusión práctica: el conocimiento que se usa poco no debe vivir en un contexto cargado de forma permanente. Para cambiar de tarea conviene limpiar la sesión con más frecuencia; para continuar en la misma línea, usar compresión controlada. Otro consejo del artículo es pedir al agente, antes de una nueva sesión, que genere un HANDOFF.md con el progreso, los callejones sin salida y el estado de la verificación. Es más barato y fiable que confiar en que la compactación automática conserve las decisiones de arquitectura realmente importantes.
Skills, hooks y agentes
El segundo bloque importante trata de la separación de roles. El autor propone no mezclar en un mismo saco MCP, tools, skills, hooks, plugins y subagents. La lógica es esta: la herramienta aporta una capacidad nueva, el skill define un flujo de trabajo, el hook incorpora una comprobación automática obligatoria y el subagent traslada una tarea concreta a un contexto aislado. Es una precisión útil, porque muchos equipos intentan curar cualquier fallo con un prompt nuevo o una herramienta más, cuando el problema puede resolverse en un nivel completamente distinto.
El artículo explica también cómo debe ser un buen skill. Tiene un descriptor corto y preciso, un disparador de uso claro, y entradas, salidas y condición de parada bien definidas. Todo lo pesado, como ejemplos, runbooks y archivos auxiliares, debe cargarse bajo demanda y no estar en el SKILL.md principal. Para acciones con efectos secundarios, el autor aconseja desactivar de forma explícita el lanzamiento automático por parte del modelo. La idea es que el agente vea primero un índice y una ruta, y cargue los detalles solo cuando de verdad los necesite.
En este análisis, los subagents no se presentan como una forma de "acelerar todo en paralelo", sino como un medio de aislamiento. La exploración del código, las revisiones, la ejecución de tests y otras operaciones ruidosas conviene enviarlas a hilos hijos con permisos limitados, un modelo distinto y un formato de respuesta fijo. Los hooks, en cambio, deben atrapar lo determinista lo antes posible: lanzar una comprobación rápida tras editar un archivo, bloquear cambios peligrosos, inyectar contexto técnico al inicio de la sesión. Cuanto antes detecte el sistema un error, menos tokens, tiempo y ediciones innecesarias se irán a la basura.
Caché, verificación y contrato
Una de las partes más interesantes del texto explica hasta qué punto la arquitectura de Claude Code depende del prompt caching. El autor escribe que un prefijo de prompt estable no solo ahorra dinero, sino que reduce la fricción con los límites de uso. De ahí salen varias reglas poco obvias: no insertar datos dinámicos en el prompt del sistema, no alterar el orden de las herramientas, no cambiar de modelo a mitad de una sesión larga sin necesidad y, si es posible, aplazar la carga completa de los esquemas de herramientas poco usadas. Incluso el Plan Mode, señala el artículo, es mejor implementarlo sin cambiar todo el conjunto de herramientas, para no romper la caché.
El énfasis final recae en la verificación y en el papel de CLAUDE.md. El autor define este archivo no como una base de conocimiento, sino como un contrato entre el proyecto y el agente: cómo compilar, cómo probar, qué límites no se pueden cruzar, qué hay que conservar al comprimir y qué prohibiciones rigen siempre. En CLAUDE.md no hay que meter referencias de API ni introducciones largas; solo deben vivir ahí las reglas críticas en cada sesión. Otro consejo es pedir al agente, tras cada error recurrente, que actualice su contrato para que los fallos típicos no vuelvan.
«Si no puedes explicar cómo saber que
Claude ha hecho lo correcto, es probable que la tarea no sea adecuada para una ejecución totalmente automática».
Qué significa esto
Este material importa a más gente que a los usuarios de Claude Code. En el fondo, es una guía para la madurez de cualquier agente de IA para desarrollo: menos magia, más aislamiento, verificación explícita y control del contexto. Cuanto más pasen los equipos de un "chatbot para código" a un ingeniero semiautónomo, más valor tendrán estas prácticas frente a otra colección de prompts.
- 21 nov 2026Un desarrollador encargó a Claude instalar 900 aplicaciones y creó un limpiador gratuito para Mac
- 21 nov 2026Apple prepara un agente de IA y complica el acceso a los de terceros: el permiso ahora requiere 14 pasos, no 4
- 21 nov 2026Qwen3-0.6B afinada en un Mac mini: los errores en las respuestas bajaron de 9 a 3 de cada 30
- 21 nov 2026El programador dejó de ser despachador de agentes de IA: Multica se hace cargo de los traspasos rutinarios
Preguntas frecuentes sobre la noticia
Dónde se pierde el contexto?
La idea principal del artículo es sencilla: Claude Code falla no porque el modelo "no sea lo bastante listo", sino porque el entorno de ingeniería que lo rodea está mal diseñado. El autor describe el agente como un ciclo de recopilación de contexto, acción y verificación del resultado.
¿Qué se sabe sobre Skills, hooks y agentes?
El segundo bloque importante trata de la separación de roles. El autor propone no mezclar en un mismo saco MCP, tools, skills, hooks, plugins y subagents. La lógica es esta: la herramienta aporta una capacidad nueva, el skill define un flujo de trabajo, el hook incorpora una comprobación automática obligatoria y el subagent traslada una tarea concreta a un contexto aislado.
¿Qué se sabe sobre Caché, verificación y contrato?
Una de las partes más interesantes del texto explica hasta qué punto la arquitectura de Claude Code depende del prompt caching. El autor escribe que un prefijo de prompt estable no solo ahorra dinero, sino que reduce la fricción con los límites de uso.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
Lo esencial de la IA — una vez por semana
Siete historias que de verdad importaron, elegidas a mano. Sin ruido ni notas de prensa.
¡Listo! Revisa tu correo para la confirmación.