Pensar como un Agent: la filosofia de diseno de herramientas del equipo de Claude Code

Thariq es ingeniero en Anthropic y uno de los constructores principales de Claude Code. A finales de febrero publico un extenso hilo en X donde compartio cinco casos reales sobre el diseno de herramientas para agents durante la construccion de Claude Code — no se trata de un marco teorico, sino de experiencia adquirida en primera linea. El articulo obtuvo 3.51 millones de visualizaciones, 209 respuestas y 9,691 likes, generando una gran cantidad de discusiones de alta calidad.

Para presentar la pregunta central de todo el articulo, Thariq utilizo una excelente analogia: imagine que se enfrenta a un problema matematico dificil, que herramientas necesita.

Papel y lapiz es la configuracion minima, pero estara limitado al calculo manual. Una calculadora es mejor, pero necesita saber como usar las funciones avanzadas. Una computadora es lo mas poderoso, pero necesita saber programar.

La eleccion de herramientas depende de las capacidades del usuario. Darle una computadora a alguien que no sabe programar es peor que darle una calculadora. Darle una calculadora a un programador limita su potencial.

Con los agents sucede lo mismo. La pregunta no es "cual herramienta es la mas poderosa", sino "cual herramienta se ajusta mejor a las capacidades actuales del modelo". Lo que comparte este articulo es precisamente la experiencia del equipo de Claude Code tropezando mientras buscaba ese punto de equilibrio.

A continuacion presento cuatro temas progresivos que he destilado del texto original y de las discusiones de la comunidad.

---

Menos es mas — la contraintuicion sobre la cantidad de herramientas

La intuicion nos dice que cuantas mas herramientas tenga un agent, mas capaz sera. Pero la experiencia del equipo de Claude Code es exactamente la opuesta.

Claude Code actualmente tiene solo alrededor de 20 herramientas, y el equipo revisa constantemente si realmente necesita todas. El umbral para agregar una nueva herramienta es alto, porque significa darle al modelo una opcion mas que considerar — cada herramienta adicional agrega una "carga cognitiva" mas al proceso de toma de decisiones del modelo.

Este hallazgo genero una fuerte resonancia en la comunidad. leon.M compartio su experiencia practica:

La investigacion CodeAct de Apple proporciono respaldo cuantitativo a esta opinion: una unica primitiva de ejecucion de codigo (code execution primitive) supera a conjuntos complejos de herramientas especializadas en hasta un 20% en tareas complejas. Menos, efectivamente, puede ser mas.

Las tres iteraciones de la herramienta AskUserQuestion son el mejor ejemplo de este principio. El equipo de Claude Code queria mejorar la capacidad de Claude para hacer preguntas al usuario — aunque Claude podia preguntar directamente en texto plano, responder esas preguntas se sentia demasiado laborioso. Como reducir la friccion.

Primer intento: agregarle un parametro a ExitPlanTool para que al generar un plan incluyera un conjunto de preguntas. Resultado — Claude se confundio. Pedirle que generara un plan y al mismo tiempo preguntas sobre el plan creaba un conflicto: que pasa si la respuesta del usuario contradice el plan.

Segundo intento: modificar las instrucciones de salida para que Claude usara un formato markdown especifico para preguntar, y luego el frontend parseara y formateara. Resultado — inestable. Claude agregaba oraciones adicionales, omitia opciones o simplemente usaba un formato completamente diferente.

Tercer intento: crear una herramienta independiente llamada AskUserQuestion. Claude puede invocarla en cualquier momento; al hacerlo, aparece una ventana emergente con la pregunta que bloquea el ciclo del agent hasta que el usuario responda. Funciono.

Thariq escribio una frase muy interesante en el texto original:

Claude parece disfrutar invocando esta herramienta, y descubrimos que la calidad de su salida es muy buena. Incluso una herramienta perfectamente disenada no funcionara si Claude no entiende como invocarla.

phuong hizo una pregunta perspicaz: "'Claude parece disfrutar invocando esta herramienta' es la frase mas interesante y menos explicada aqui. Como detectan la 'afinidad' del modelo hacia una herramienta — leyendo transcripts o mediante metricas internas de frecuencia de invocacion? Si esta heuristica pudiera ser mas especifica, cambiaria la forma en que todos disenan herramientas para agents."

La pregunta no obtuvo respuesta, pero apunta a una intuicion importante: el criterio de exito del diseno de herramientas no es "que un humano lo considere razonable", sino "que el modelo entienda como usarla y quiera usarla".

Emeka complemento con una leccion directa desde la perspectiva del desarrollo de herramientas empresariales: "Una vez intente controlar cada posible entrada y salida al construir herramientas para un agent, y el resultado fue que el modelo simplemente... las ignoro. Ahorre esfuerzo de ingenieria y confie en que el modelo puede manejar la ambiguedad."

---

Las herramientas se vuelven obsoletas — el efecto cadena tras la mejora de capacidades

Si "menos es mas" es una leccion sobre la dimension espacial, "las herramientas se vuelven obsoletas" es una leccion sobre la dimension temporal.

Las herramientas que una vez ayudaron al modelo pueden convertirse en limitaciones a medida que el modelo progresa.

Cuando Claude Code se lanzo inicialmente, el equipo se dio cuenta de que el modelo necesitaba una lista de tareas pendientes para mantener el rumbo — podia escribir elementos al inicio y luego ir marcandolos como completados. Para esto le proporcionaron a Claude la herramienta TodoWrite. Pero aun asi, Claude frecuentemente olvidaba lo que debia hacer.

La solucion del equipo fue insertar un recordatorio del sistema cada 5 turnos de conversacion, indicandole a Claude cuales eran sus objetivos.

Pero con las mejoras del modelo, el problema se invirtio: el modelo ya no necesitaba que le recordaran la lista de tareas pendientes; por el contrario, sentia esos recordatorios como una restriccion. Ser recordado repetidamente de la lista de tareas hacia que Claude sintiera que debia seguirla estrictamente, en lugar de ajustar de manera flexible segun las necesidades. Al mismo tiempo, Opus 4.5 mejoro significativamente en el uso de sub-agents, pero como deberian coordinarse los sub-agents para compartir una lista de tareas pendientes.

Asi que el equipo reemplazo TodoWrite con Task Tool. La diferencia entre ambos es fundamental: los Todos servian para mantener al modelo en el camino correcto — como un jefe supervisando la lista de tareas de un empleado; los Tasks, en cambio, se enfocan mas en facilitar la comunicacion entre agents — como un tablero de colaboracion de equipo. Los Tasks soportan dependencias, comparten actualizaciones entre sub-agents, y el modelo puede modificarlos y eliminarlos.

De TodoWrite a recordatorios cada 5 turnos a Task Tool, fueron tres redisenos. No porque los disenos anteriores fueran "incorrectos", sino porque el modelo habia crecido.

El comentario de modi resume este fenomeno con precision:

Esto tambien da lugar a una controversia interesante. Danny Cosson considero que AskUserQuestion "en realidad es un mal diseno" — fuerza el modelo elegante de entrada de texto/salida de texto de Claude Code dentro de un patron de interaccion especifico, practicamente sin beneficios.

Pero la refutacion de @Toong fue muy convincente: el valor de AskUserQuestion radica en dos puntos — iniciativa (indica explicitamente al modelo que tiene derecho a preguntar) y gestion de estado (distingue claramente la salida de texto estandar del estado de bloqueo de "esperando intervencion del usuario").

La misma herramienta, dos evaluaciones diametralmente opuestas. Esto demuestra precisamente lo que Thariq dijo al final: el diseno de herramientas es un arte, no una ciencia. Depende del modelo que se utilice, del objetivo del agent y del entorno en el que opera.

---

Dejar que el Agent encuentre sus propias respuestas — de "alimentar" a "busqueda autonoma"

Esta es la parte del articulo que considero de mayor valor practico.

Claude Code inicialmente utilizaba una base de datos vectorial RAG para buscar contexto para Claude. RAG era potente y rapido, pero tenia dos problemas: primero, requeria indexacion y configuracion, lo cual podia ser fragil en diferentes entornos; segundo, y mas fundamental — este enfoque proporcionaba contexto a Claude, en lugar de dejarlo buscarlo por si mismo.

El equipo realizo un cambio clave: si Claude puede buscar en la web, por que no puede buscar en su base de codigo. Al proporcionarle a Claude la herramienta Grep, le permitieron buscar archivos y construir contexto por su cuenta.

El comentario de Beacon fue directo al grano:

En el transcurso de un ano, Claude paso de ser casi incapaz de construir contexto de forma autonoma a poder realizar busquedas anidadas a traves de multiples capas de archivos, encontrando con precision el contexto necesario. La clave de esta evolucion no fue darle mas informacion a Claude, sino mejores capacidades de busqueda.

Cuando Claude Code introdujo Agent Skills, el equipo propuso formalmente el concepto de divulgacion progresiva (Progressive Disclosure): permitir que el agent descubra gradualmente el contexto relevante a traves de la exploracion.

La implementacion concreta es elegante: Claude puede leer archivos de skill, y estos archivos a su vez pueden referenciar otros archivos que el modelo puede leer recursivamente. Un uso comun de los skills es agregar mas capacidades de busqueda a Claude — por ejemplo, proporcionarle instrucciones sobre como usar una API o consultar una base de datos.

Brian Wagner compartio su practica de tres capas, completamente alineada con el enfoque de Claude Code:

SKILL.md se mantiene conciso (unas 100 lineas), el contexto pesado se coloca en archivos que Claude descubre solo cuando lo necesita. Yo lo llamo la tercera capa. Ustedes lo llaman divulgacion progresiva. La esencia es la misma.

PrimeLine incluso construyo un sistema cuantificado de tres capas: configuracion JSON (aprox. 500 tokens) > resumen de esquema (aprox. 300 tokens) > markdown completo (aprox. 3K tokens). Un enrutador de contexto decide que capa cargar segun las palabras clave de la tarea.

La logica central de esta estrategia por capas es: el contexto es un recurso limitado con rendimientos marginales decrecientes. Entregar toda la informacion al agent de una sola vez no solo desperdicia tokens, sino que diluye la informacion verdaderamente importante. Proporcionarla bajo demanda, dejando que el agent decida cuando necesita detalles mas profundos — esa es la solucion escalable.

El sub-agent Claude Code Guide es otra aplicacion ingeniosa de la divulgacion progresiva. El equipo noto que Claude no sabia lo suficiente sobre como usar el propio Claude Code — si usted le preguntaba como agregar un MCP o que hacia cierto comando slash, no podia responder.

Podrian haber metido toda la informacion en el prompt del sistema, pero los usuarios rara vez hacen este tipo de preguntas, y hacerlo habria aumentado la erosion del contexto, interfiriendo con el trabajo principal de Claude Code: escribir codigo.

Primero intentaron darle a Claude un enlace a la documentacion para que buscara por si mismo — funciono, pero Claude cargaba una gran cantidad de resultados en el contexto para encontrar la respuesta correcta. La solucion final fue construir un sub-agent dedicado: Claude Code Guide. Este sub-agent tiene instrucciones detalladas de busqueda y sabe como buscar eficientemente en la documentacion y que contenido devolver. Sin agregar ninguna herramienta nueva, se expandio el espacio de accion de Claude.

Lance Martin, en su articulo sobre patrones de diseno de agents, propuso una perspectiva complementaria: en lugar de definir docenas de herramientas para un agent, es mejor darle una computadora y dejar que use codigo para orquestar herramientas. La abstraccion central de Claude Code es el CLI — el agent vive en su computadora y completa tareas complejas a traves de primitivas basicas como bash y el sistema de archivos. Unas pocas herramientas atomicas (como la herramienta bash) son mas flexibles y consumen menos tokens que un conjunto extenso de herramientas.

---

Empatia con el modelo — pensar como un Agent

Los tres temas anteriores — menos es mas, las herramientas se vuelven obsoletas, dejar que el agent encuentre sus propias respuestas — comparten una meta-metodologia comun. Thariq lo senalo al inicio del articulo: ver el mundo como un agent.

No es un conjunto de reglas, sino una forma de pensar. David Zhang le dio un nombre:

Empatia con el modelo — no es disenar herramientas "razonables" desde la perspectiva humana, sino pensar desde la perspectiva del modelo: que es lo que realmente ve, como lo entendera, como lo usara.

Terminally Drifting destilo en tres pasos la misma leccion que todo equipo de agents termina aprendiendo:

1. Disenar herramientas para humanos
2. El modelo las usa como un mapache con permisos de administrador
3. Redisenar para la economia de tokens y efectos secundarios predecibles

"Pensar como un agent" es ese avance clave.

Vish compartio su momento de revelacion: "Estabamos construyendo interfaces de herramientas que tenian sentido para los humanos, y luego no entendiamos por que el agent siempre tomaba decisiones extranas. Una vez que se invierte el modelo mental y se piensa en lo que el modelo realmente ve en la definicion de la herramienta, todo cambia."

Emeka dijo lo mismo desde la perspectiva del desarrollo de herramientas empresariales: "Todo esta configurado por defecto con el modelo mental humano — schemas, nombres de campos, flujos, todo optimizado para la lectura humana. Pero para un agent, ese es el marco equivocado."

Esta "inversion del modelo mental" suena simple, pero requiere practica constante. Es necesario leer cuidadosamente la salida del agent — no para ver que hizo bien, sino para entender por que tomo ciertas decisiones, donde dudo, donde tomo un camino equivocado. Estos "comportamientos anomalos" a menudo no son bugs del modelo, sino bugs del diseno de herramientas.

En las discusiones de la comunidad tambien surgieron varias perspectivas complementarias dignas de reflexion.

OAIR senalo un punto ciego: todas estas iteraciones de herramientas asumen que el agent no tiene estado — cada sesion comienza desde cero. Y si la "herramienta" mas importante no esta en el espacio de accion, sino en la memoria persistente sobre como funciona esta base de codigo? Claude Code respondio parcialmente a esta cuestion mas adelante con los archivos CLAUDE.md y el sistema de memoria, pero la gestion de estado persistente sigue siendo un desafio abierto en el diseno de agents.

Clinker propuso otro principio de diseno: optimizar la recuperabilidad (recoverability) en lugar de la capacidad bruta — precondiciones explicitas en las herramientas, estado observable y reintentos de bajo costo suelen ser mas efectivos que simplemente agregar mas herramientas rapido. Esto esta en linea con la filosofia de ingenieria de software de "hacer que el sistema sea tolerante a fallos en lugar de infalible".

El resumen de Paradigm Collapse fue el mas incisivo:

El diseno del Action Space es fundamentalmente diseno de poder — los permisos que usted le otorga a la IA determinan el rol que asume. Es exactamente igual que gestionar un equipo: usted cree que el cuello de botella es la capacidad de las personas, pero en realidad el cuello de botella son los limites de permisos que usted ha trazado.

---

Reflexiones finales

Volviendo a las palabras finales de Thariq:

Experimente mas, lea sus salidas, pruebe nuevos enfoques. Observe como un agent.

Como usuario intensivo de Claude Code, la mayor impresion que me dejo este articulo es: esas funcionalidades que parecen "naturales" tienen detras innumerables iteraciones de "esto no funciona, probemos otra cosa". AskUserQuestion se intento tres veces, TodoWrite se rediseno tres veces, RAG fue reemplazado por Grep. Cada mejora no surgio porque se les ocurrio una solucion mas inteligente, sino porque observaron cuidadosamente el comportamiento real del modelo.

El subtitulo de este articulo es "Seeing like an Agent" — ver el mundo como un agent. Pero viendolo desde otro angulo, esta es en realidad la esencia de toda buena practica de ingenieria: no disenar sistemas desde su propia perspectiva, sino desde la perspectiva del usuario. Solo que esta vez, el usuario es un modelo de IA.

En el futuro, cada desarrollador que construya agents probablemente necesitara dominar lo que David Zhang llama "empatia con el modelo". No es ninguna capacidad misteriosa; su nucleo se reduce a tres cosas: observar el comportamiento real del modelo, leer sus salidas y luego ajustar el diseno en funcion de lo que se observa.

Observe como un agent.

---

Lecturas complementarias: