# 4 principios de diseño de herramientas que Claude Code aprendió tras 3 reconstrucciones > Author: Tony Lee > Published: 2026-03-03 > URL: https://tonylee.im/es-LA/blog/claude-code-4-tool-design-principles/ > Reading time: 5 minutes > Language: es-LA > Tags: ai, claude-code, ai-agent, tool-design, software-engineering ## Description El equipo de Claude Code de Anthropic reconstruyó sus herramientas tres veces. Menos herramientas hicieron que la IA rindiera mejor. Aquí van cuatro principios aprendidos a pulso. ## Content Menos herramientas, y la IA funcionó mejor. Cuando construyes un agente, el instinto más natural es pensar: "si le falta algo, dale otra herramienta". El equipo de Anthropic se pasó un año desarrollando Claude Code y descubrió justo lo contrario. Cada herramienta adicional le suma a la IA un costo cognitivo — "¿llamo a esta herramienta o no?" — y ese costo se acumula. Yo caí en la misma trampa construyendo mis propios agentes, por eso lo que compartió Thariq, desarrollador del equipo de Claude Code, me pegó fuerte. Acá va el recorrido cronológico de cómo agregaron, quitaron y rediseñaron sus herramientas. ## Una herramienta, un rol — o la IA se traba Este fue el primer problema con el que se topó el equipo de Claude Code. Necesitaban una funcionalidad para hacerle preguntas al usuario, así que la metieron dentro de la herramienta de "planificación". La implementación fue rápida, pero la IA intentaba armar un plan y hacer una pregunta al mismo tiempo. Cuando la respuesta del usuario contradecía el plan, la IA no podía resolver el conflicto. En el segundo intento, hicieron que la IA sacara las preguntas en formato Markdown. La IA se saltaba el formato o le agregaba texto de más. En el tercer intento, separaron la funcionalidad en una herramienta dedicada — `AskUserQuestion` — y ahí sí 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 agregaba frases o ignoraba la estructura - **Herramienta dedicada separada** — Las respuestas estructuradas por fin funcionaron de forma confiable - **Por mejor 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 de la historia. Yo le llamo "caducidad de herramientas (tool decay)" — el fenómeno donde una herramienta que antes era esencial se vuelve un estorbo después de una actualización del modelo. Al principio, Claude Code tenía una herramienta de lista de tareas (Todo), y el sistema mandaba recordatorios cada cinco turnos: "No olvides tu lista de tareas." Después de que el modelo mejoró, esos recordatorios resultaron contraproducentes. La IA se aferraba tercamente a su plan original incluso cuando debía adaptarse. Cuando Opus 4.5 habilitó la colaboración entre subagentes, la estructura Todo existente simplemente no permitía compartir tareas entre agentes. Terminaron reemplazándolo todo con el Task Tool. - **TodoWrite reemplazado por Task Tool** — Se habilitó compartir dependencias entre agentes - **"¿Esta herramienta todavía sirve?" requiere revisión periódica**, tan importante como agregar herramientas nuevas - **Soportar menos modelos acelera estas decisiones** - **La forma de la herramienta importa más que la cantidad** — tiene que coincidir con las capacidades del modelo ## Darle el contexto masticado a la IA la empeora A lo largo del proceso de agregar y quitar herramientas, el equipo de Claude Code descubrió un patrón más de fondo: 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 poderoso, pero la indexación se rompía según el entorno, y la IA se volvía pasiva — dependiendo solo de lo que le daban. Cuando le dieron una herramienta Grep para buscar directamente en el código, la calidad del contexto mejoró. Le agregaron 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 vez de aventar 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 puede encontrar contexto" a "IA que lo encuentra sola"** - **Capacidades ampliadas solo con archivos Skills, sin herramientas nuevas** ## Ampliar capacidades sin agregar 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. Podían haber metido toda la documentación en el prompt del sistema, pero esa pregunta solo sale de vez en cuando. Cuando información poco usada ocupa permanentemente la ventana de contexto, baja el rendimiento en la tarea principal: escribir código. Yo le 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 regresaba solo la respuesta. El número de herramientas se mantuvo igual, pero las capacidades de la IA crecieron. - **Toda la información en el prompt del sistema** — El ruido contextual bajó la calidad del código - **Solo dar enlaces a la documentación** — La IA cargaba demasiados resultados en el contexto - **Subagente dedicado + instrucciones de búsqueda** — Respuestas limpias y enfocadas - **Se resolvió cambiando la estructura, no agregando herramientas** ## No hay fórmula mágica Agregar, quitar 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. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/es-LA/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.