Intensivo Gratis 21–22.11Intensivo gratuito de 2 días en Vibecoding (21–22 nov, 16:00 MSK) · Cohorte 3 inicia 23.11Registrarse gratis →Cohorte 3 (23.11)
LanzamientoAnálisis · En radarHabr AI→ original

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
Claude Code sin magia: Habr analiza la arquitectura, el ruido de contexto y las prácticas de ingeniería
Fuente: Habr AI. Collage: Hamidun News.
Escuchar artículo
Ficha técnica y cifras clave
ParámetroDatos
Fuente originalHabr AI ↗
Editor jefe
Dato clave #1Instrucciones del sistema y reglas básicas
Dato clave #2Descripciones de skills y herramientas MCP
Dato clave #3Memoria del proyecto y contenido de CLAUDE.md

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.

Historia

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.

ZK
Zhemal Khamidun — CPO de Alpina Digital, product manager de AlpinaGPT. Crea productos de IA desde 2019. Hamidun News es un proyecto personal que creció hasta ser un agregador en producción con más de 6.000 lectores.
✦ Hands-On AI Engineering · Hamidun Academy

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.

Start 72h Free Trial →Vibe-Coding Intensive
¿Qué te parece?
Cargando comentarios…