La mayoría de desarrolladores que usan Claude Code lo tratan como un autocompletado muy listo. Escriben un prompt, reciben código y siguen con la siguiente tarea.
Ese uso ya aporta valor, pero no es donde aparece el salto grande. El salto llega cuando empiezas a construir herramientas para el agente: piezas que amplían lo que puede hacer, no solo instrucciones para que escriba código por ti.
Llevo tiempo pensando en esto, sobre todo después de leer el artículo de ingeniería de Anthropic sobre cómo escribir herramientas efectivas para agentes. Diseñar herramientas para agentes de IA obliga a replantear una parte importante del diseño de interfaces. Ya no estás escribiendo una API para un desarrollador humano. Estás escribiendo una interfaz para un sistema no determinista que lee documentación, toma decisiones y a veces se confunde.
Los agentes no usan herramientas como tú
Cuando construyo una API REST o una gema de Ruby, pienso en una persona que leerá la documentación, entenderá el modelo de datos y escribirá el código de integración. Esa persona mantiene estado en la cabeza. Recuerda qué hizo tres llamadas antes.
Un agente de IA no trabaja así. Opera dentro de una ventana de contexto, y cada token que lee es un token menos disponible para razonar. Anthropic lo explica con un ejemplo sencillo: buscar un contacto en una libreta de direcciones. Un programa tradicional itera por las entradas de forma eficiente. Un agente, en cambio, tiene que leer cada entrada token a token, consumiendo contexto con datos irrelevantes.
Si tu herramienta devuelve una respuesta JSON de 500 líneas cuando el agente solo necesita tres campos, estás desperdiciando su recurso más escaso: la atención.
MCP cambió el mapa
El Model Context Protocol, que Anthropic abrió a finales de 2024, se ha convertido en el estándar para conectar agentes de IA con herramientas externas. Después llegaron adopciones en ChatGPT, Gemini y otros entornos. Ya no es solo una pieza del ecosistema de Anthropic. Es una forma común de conectar agentes con sistemas reales.
En Claude Code, los servidores MCP son la manera de dar acceso al agente a bases de datos, APIs, herramientas internas y flujos personalizados. Hay dos transportes principales:
- Servidores HTTP, normalmente para servicios remotos o en la nube.
- Servidores
stdio, pensados para procesos locales que necesitan acceso directo al sistema.
Existen servidores MCP para GitHub, PostgreSQL, sistemas de archivos y cientos de integraciones más. Pero lo interesante para un equipo de producto es otra cosa: puedes construir los tuyos.
Un ejemplo concreto: un blog en Rails puede exponer un pequeño MCP server con herramientas como create_article, publish_article, list_categories y search_articles. Con solo unas cuantas rutas, Claude Code deja de ser un asistente que redacta texto y se convierte en un asistente editorial completo: crea el artículo, asigna la categoría, fija la fecha de publicación y actualiza el contenido sin abrir un panel de administración.
Ese es el cambio de mentalidad. No le pides al agente que "me escriba el código para publicar esto". Le das una herramienta segura para publicar, con límites claros, y dejas que la use dentro de un flujo conversacional.
Menos herramientas, herramientas más inteligentes
Una de las lecciones menos intuitivas al trabajar con agentes es que más herramientas no significa mejor sistema. Anthropic recomienda construir menos herramientas, pero más pensadas, centradas en flujos de alto impacto en lugar de envolver cada endpoint de una API existente.
Tiene sentido si lo miras desde el punto de vista del agente. Cada herramienta que expones amplía el espacio de decisión. Si le das 50 herramientas pequeñas, tiene que decidir qué combinación usar y en qué orden. Si le das 10 herramientas bien diseñadas que cubren flujos completos, puede resolver más tareas en menos pasos y con menos oportunidades de equivocarse.
También lo he visto en trabajo real. El primer impulso suele ser crear herramientas granulares: una para listar usuarios, otra para leer un usuario concreto, otra para actualizar un campo. Pero consolidar esas piezas en operaciones de más nivel, como find_and_update_user o generate_user_report, suele mejorar mucho el comportamiento del agente.
Es el mismo principio que en Rails cuando empujamos complejidad hacia modelos u objetos de dominio: el consumidor no debería tener que orquestar detalles internos si el sistema puede ofrecer una operación más cercana a la intención real.
La descripción de la herramienta es la interfaz
Este punto se subestima muchísimo. La descripción que das a una herramienta no es solo documentación. Es la interfaz principal que el agente usa para decidir cuándo y cómo llamarla.
La recomendación práctica es escribir descripciones como se las explicarías a una persona nueva del equipo. Haz explícitas las suposiciones implícitas. Usa nombres de parámetros inequívocos, como user_id en lugar de user. Explica qué hace la herramienta, cuándo conviene usarla y qué devuelve.
Pequeños cambios en la descripción pueden tener efectos enormes. Añadir una frase como "usa esta herramienta cuando necesites comprobar si un despliegue puede continuar con seguridad" puede reducir mucho los usos incorrectos de una herramienta de deploy.
Un patrón útil para describir herramientas:
- Qué hace. Una frase clara sobre el propósito.
- Cuándo usarla. Escenarios concretos donde es la opción correcta.
- Qué devuelve. La forma y el significado de la respuesta.
- Qué no hace. Límites explícitos para evitar usos erróneos.
Si una descripción deja huecos, el agente los rellenará. A veces acertará. A veces no.
CLAUDE.md es el manual de instrucciones del proyecto
Si usas Claude Code y todavía no tienes un archivo CLAUDE.md en la raíz del proyecto, estás dejando valor sobre la mesa.
Ese archivo funciona como un briefing que Claude lee cada vez que empieza a trabajar en el repositorio. Evita que el agente tenga que redescubrir comandos de desarrollo, runners de test, patrones de arquitectura y convenciones internas en cada sesión.
En un proyecto Rails, un buen CLAUDE.md puede incluir:
- Comandos de desarrollo:
bin/dev,bin/rails test,bin/rubocop. - Estructura del sitio o de la aplicación.
- Enfoque de autenticación y autorización.
- Relaciones importantes entre modelos.
- Detalles de infraestructura.
- Reglas del equipo: dónde vive la lógica de negocio, cómo se nombran los jobs, qué tipo de tests se esperan.
No tiene que ser largo. Un documento de 60 u 80 líneas puede ahorrar mucho tiempo y hacer que la salida del agente sea más consistente.
Piensa en él como un documento de onboarding para un desarrollador extremadamente rápido, pero olvidadizo, que se incorpora al equipo desde cero cada mañana.
Comandos, skills y flujos repetibles
Además de MCP, Claude Code permite definir comandos y skills mediante directorios como .claude/commands/ y .claude/skills/. En la práctica, son plantillas de prompt en Markdown que puedes invocar durante una sesión.
La virtud de este enfoque es su sencillez. Escribes un archivo Markdown con instrucciones naturales, lo colocas en el directorio adecuado y el agente gana una capacidad nueva.
Por ejemplo, si tu equipo tiene una forma muy concreta de generar migraciones, puedes crear un archivo .claude/commands/generate-migration.md que describa ese estándar: cómo nombrar la migración, qué revisar antes de tocar el esquema, qué tests actualizar y qué errores evitar.
Las skills añaden una capa más: metadatos en frontmatter que ayudan a Claude a decidir cuándo invocarlas automáticamente. Así puedes crear capacidades que se activan por contexto. El agente reconoce que una skill es relevante y la usa sin que tengas que llamarla de forma explícita.
De nuevo, la clave no es escribir pasos mecánicos para todo. La clave es capturar criterio repetible: qué significa hacerlo bien en este proyecto.
Diseña pensando en tokens
Cada respuesta de una herramienta consume tokens. Eso cuesta dinero, pero sobre todo consume espacio de contexto. Algunas reglas prácticas:
Devuelve solo lo necesario. Si tu herramienta obtiene datos de usuario pero la tarea actual solo necesita nombre y email, considera ofrecer un parámetro como response_format para elegir entre una respuesta breve y una detallada.
Usa identificadores significativos. Devuelve jorge-alvarez cuando sea posible, no a1b2c3d4-e5f6-7890-abcd-ef1234567890. Si el agente tiene que referenciar esa entidad después, un slug legible es menos propenso a errores que un UUID que debe copiar perfectamente.
Pon límites sensatos a la paginación. No devuelvas 10.000 registros si lo normal es necesitar los primeros 20. Anthropic sugiere limitar respuestas grandes a tamaños que no devoren el contexto de Claude Code.
Haz que los errores sean accionables. En lugar de devolver solo Error 422, devuelve algo como: The user email is already taken. Try searching for the existing user with find_user(email: "..."). Un buen error le da al agente el siguiente paso.
Estas decisiones parecen pequeñas, pero son el equivalente a buen diseño de API para humanos. Solo que aquí el consumidor lee, razona y decide bajo restricciones distintas.
El bucle de evaluación
Otra lección importante del enfoque de Anthropic es la seriedad con la que tratan la evaluación. No construyen una herramienta y la dan por buena. Generan escenarios realistas, los ejecutan de forma programática, miden más que la precisión, y repiten.
No hace falta montar un laboratorio complejo para aplicar esa idea. Puedes empezar con una versión ligera:
- Construye una herramienta.
- Úsala con Claude Code en tareas reales de tu semana.
- Observa cuándo el agente elige la herramienta incorrecta.
- Revisa cuándo pasa parámetros inválidos.
- Apunta cuándo pide aclaraciones que no debería necesitar.
Cada fallo es una señal de diseño. Quizá la descripción es ambigua. Quizá el nombre de un parámetro invita al error. Quizá la herramienta devuelve demasiados datos. Quizá el flujo debería estar encapsulado en una operación de más nivel.
Incluso una hoja de cálculo con una docena de prompts de prueba y una tasa de éxito aproximada enseña más sobre interacción agente-herramienta que muchas discusiones abstractas.
La imagen completa
Estamos pasando de una etapa en la que la IA ayudaba a completar código a otra en la que agentes de IA orquestan flujos completos de desarrollo. En ese mundo, los equipos que sepan construir buenas herramientas para agentes tendrán ventaja.
No porque esas herramientas sean necesariamente difíciles de programar. Un MCP server útil puede ser pequeño. Un CLAUDE.md efectivo puede caber en una pantalla. Un comando bien escrito puede ser solo un Markdown.
La dificultad está en el criterio de diseño. Hay que cambiar la empatía de producto: ya no diseñas solo para un desarrollador humano que lee documentación, sino para un agente que lee descripciones, toma decisiones a partir de ellas y necesita límites claros para no perderse.
La buena noticia es que si ya te importan el diseño limpio de APIs, la documentación útil y las abstracciones cuidadas, tienes gran parte del camino recorrido. El cambio está en adaptar esas mismas virtudes a un consumidor distinto.
Empieza pequeño. Elige un flujo repetitivo de tu trabajo diario, construye un MCP server, un comando o una skill para él, y observa cómo lo usa Claude Code. Itera desde ahí.
Así es como muchos equipos van a descubrir que la verdadera productividad con agentes no consiste en escribir prompts cada vez más largos. Consiste en construir mejores superficies de trabajo para que el agente pueda operar con criterio.
