4 principios de diseño de herramientas que Claude Code aprendió tras 3 reconstrucciones

Menos herramientas, y la IA funcionó mejor. Al construir un agente, el instinto más natural es pensar: «si le falta alguna función, dale otra herramienta más.» El equipo de Anthropic pasó un año desarrollando Claude Code y descubrió justo lo contrario. Cada herramienta adicional incrementa la carga cognitiva de la IA — «¿debería llamar a esta herramienta o no?» — y ese coste se acumula.

Yo caí en la misma trampa construyendo mis propios agentes, por eso la experiencia que compartió Thariq, desarrollador del equipo de Claude Code, me caló tan hondo. Aquí va el recorrido cronológico de cómo añadieron, eliminaron y rediseñaron sus herramientas.

Una herramienta, un rol — o la IA se bloquea

Este fue el primer problema con el que se topó el equipo de Claude Code. Necesitaban una funcionalidad para hacer preguntas al usuario, así que la integraron en la herramienta de «planificación». La implementación fue rápida, pero la IA intentaba formular un plan y una pregunta a la vez. Cuando la respuesta del usuario contradecía el plan, la IA no sabía resolverlo.

En el segundo intento, hicieron que la IA emitiera las preguntas en formato Markdown. La IA ignoraba constantemente el formato o añadía texto de más. En el tercer intento, separaron la funcionalidad en una herramienta dedicada — AskUserQuestion — y por fin todo se estabilizó. Una herramienta, un rol. Suena obvio, pero no lo entiendes de verdad hasta que te quemas.

• Plan + pregunta combinados — La IA llamaba a la misma herramienta dos veces por error
• Salida en formato Markdown — La IA añadía frases o ignoraba la estructura
• Herramienta dedicada separada — Las respuestas estructuradas finalmente funcionaron de forma fiable
• Por muy bueno que sea el diseño, si la IA no quiere llamar a la herramienta, no sirve de nada

Las herramientas tienen fecha de caducidad

Separar bien las herramientas no es el final. Yo lo llamaría «caducidad de herramientas (tool decay)» — el fenómeno por el cual una herramienta que antes era esencial se convierte en un lastre tras una actualización del modelo.

Al principio, Claude Code tenía una herramienta de lista de tareas (Todo), y el sistema enviaba recordatorios cada cinco turnos: «No olvides tu lista de tareas.» Tras mejorar el modelo, esos recordatorios resultaron contraproducentes. La IA se aferraba obstinadamente a su plan original incluso cuando debía adaptarse. Cuando Opus 4.5 hizo posible la colaboración entre subagentes, la estructura Todo existente simplemente no permitía compartir tareas entre agentes.

Acabaron sustituyéndolo todo por el Task Tool.

• TodoWrite reemplazado por Task Tool — Se habilitó el intercambio de dependencias entre agentes
• «¿Esta herramienta sigue siendo válida?» requiere revisión periódica, tan importante como añadir herramientas nuevas
• Dar soporte a menos modelos acelera estas decisiones
• La forma de la herramienta importa más que la cantidad — debe coincidir con las capacidades del modelo

Darle el contexto masticado a la IA la hace peor

A lo largo del proceso de añadir y eliminar herramientas, el equipo de Claude Code descubrió un patrón más fundamental: dejar que la IA encuentre la información por sí misma funciona mejor que inyectársela.

Al principio, usaban una base de datos vectorial RAG para precargar el contexto. Era rápido y potente, pero la indexación se rompía según el entorno, y la IA se volvía pasiva — dependiendo solo de lo que se le proporcionaba. Cuando le dieron una herramienta Grep para buscar directamente en el código, la calidad del contexto mejoró. Añadieron archivos Skills encima, creando una estructura donde la IA podía explorar recursivamente los archivos referenciados dentro de otros archivos.

Esto es lo que yo llamaría divulgación progresiva (progressive disclosure) — en lugar de volcarlo todo de golpe, la IA descubre lo que necesita por su cuenta.

• RAG — Alta dependencia del entorno, la IA consume contexto de forma pasiva
• Grep + Skills — La IA explora activamente múltiples capas de archivos
• En un año, de «IA que no sabe encontrar contexto» a «IA que lo encuentra sola»
• Capacidades ampliadas solo con archivos Skills, sin herramientas nuevas

Ampliar capacidades sin añadir herramientas

Este patrón de divulgación progresiva demostró su valor en otro caso. Los usuarios preguntaban cómo usar Claude Code y no sabía responder. Podrían haber metido toda la documentación en el prompt del sistema, pero esa pregunta solo surge de vez en cuando. Cuando información poco usada ocupa permanentemente la ventana de contexto, degrada el rendimiento en la tarea principal: escribir código. Yo lo llamo ruido contextual (context rot).

La solución fue un subagente dedicado. Cuando llegaba una pregunta sobre el uso, un agente guía buscaba en la documentación y devolvía solo la respuesta. El número de herramientas seguía igual, pero las capacidades de la IA crecieron.

• Toda la información en el prompt del sistema — El ruido contextual degradó la calidad del código
• Solo proporcionar enlaces a la documentación — La IA cargaba demasiados resultados en el contexto
• Subagente dedicado + instrucciones de búsqueda — Respuestas limpias y enfocadas
• Resuelto cambiando la estructura, no añadiendo herramientas

No hay fórmula mágica

Añadir, eliminar y rediseñar herramientas — no existe una fórmula universal para este proceso. Cuando los modelos cambian, las herramientas deben cambiar también. La estructura óptima de ayer puede ser el cuello de botella de mañana.

Una cosa que el equipo de Anthropic repitió a lo largo del año: leer la salida de la IA, experimentar y volver a corregir. Al final, quienes construyen los mejores agentes son quienes saben ponerse en el lugar de la IA.