Subagentes en la práctica: roles, presupuestos, prohibiciones y fallos silenciosos

Las habilidades solucionan un tipo de olvido: el agente deja de perder de vista cómo es tu base de código. Existe otro tipo de olvido relacionado con la identidad. En cada nueva sesión, el modelo actúa como el mismo generalista entusiasta, dispuesto a expresar una opinión razonable y sin especialidad sobre lo que se le presente.

El conocimiento es el problema de las habilidades. El rol es el problema de los subagentes, y de eso trata este texto.

En resumen, antes de que su extensión te desanime: una habilidad le indica al modelo cómo es tu mundo, mientras que un subagente le dice qué papel debe desempeñar. Tener ambos es mejor que tener solo uno, y para un desarrollador solitario que maneja varios proyectos a medias al mismo tiempo, esta combinación es aún más importante. Tú eres el único especialista en el equipo, y no puedes ocupar cinco puestos al mismo tiempo.

La primera mitad que se muestra a continuación corresponde a los fundamentos conceptuales: qué son estos archivos, dónde se encuentran en el disco y cómo escribir uno. Todo esto se puede obtener de la documentación. La segunda mitad solo se obtiene al ejecutar dos subagentes durante meses en una docena de repositorios y observar cómo fallan de maneras que ninguna guía de buenas prácticas advertía. Ambos agentes son de código abierto, y los archivos reales merecen ser leídos, ya que una instrucción que ha sido perfeccionada a través de ejecuciones reales enseña más que cualquier consejo.

El vacío que cubre un subagente

Un agente de programación viene con una personalidad predeterminada: el generalista servicial. Si solicitas una revisión de una solicitud de integración, recibes comentarios razonables de forma genérica. Si preguntas por qué una aplicación parece lenta, comienza a analizar el archivo que modificaste por última vez. Si pides un plan de migración de la base de datos, el resultado parece sensato aunque se omiten tres aspectos que podrían causar problemas en producción.

Nada de eso se debe a que el modelo sea deficiente. Lo que le falta es un rol definido. Quien realiza pruebas de seguridad piensa en cosas diferentes a un ingeniero de seguridad, y quien busca un error examina pruebas distintas a alguien que ya ha atendido ese mismo problema tres veces. La inteligencia ya está presente; lo que falta es el marco adecuado.

La forma de activarlo es escribiendo una y otra vez el mismo preámbulo. Antes de permitir que Claude Code revise un cambio, puedes pegar algo como: revisa esto como una persona paranoica de seguridad, verifica primero los límites de autenticación, dime qué se filtra en los registros, omite los detalles menores sobre el estilo. La tercera vez que esto ocurre en quince días, se da cuenta de que ese preámbulo representa un rol, y un rol que se escribe una y otra vez es un subagente que aún nadie ha creado.

La escritura repetida es el desencadenante del que hablan todas las guías. No fue lo que generó a los dos agentes que perduraron, ya que estos surgieron de otras dos presiones.

• Economía de contexto. La investigación es caótica: veinte búsquedas, una docena de páginas obtenidas, de las cuales la mitad son inútiles. Si esto ocurre en tu sesión principal, esta se llena de basura que nunca quisiste leer. El trabajo debe realizarse en otro lugar y luego presentarse como un resumen. Esa es la razón fundamental de la existencia del agente de búsqueda en la web. No es más inteligente que el hilo principal; su función es simplemente mantener lo que ha leído fuera de tu contexto.
• Separación de roles. Durante el trabajo de diseño, deseas permanecer dentro de la conversación relacionada con el diseño. Ser sacado para aprobar la undécima edición mecánica, una que surge directamente de una decisión ya tomada, es una pérdida de tiempo. Por lo tanto, las decisiones quedan en manos del humano, mientras que la tarea de escribir recae en un agente implementador. La capacidad no tiene nada que ver con esta división; lo que se establece es quién debe pensar en qué.

Un revisor es un primer subagente agradable. Estos dos son diferentes: son los que convierten una función de conveniencia en la forma en que realmente se lleva a cabo un proyecto.

Habilidades versus subagentes: saber frente a actuar

Una habilidad agrupa todo lo que el agente debe saber: su biblioteca interna peculiar, las peculiaridades del entorno que interfieren con las compilaciones, los hechos del dominio que un nuevo empleado inteligente debe conocer porque nadie podría adivinarlos. Se carga bajo ciertas condiciones, cuando es relevante.

Un subagente agrupa cómo el agente debe actuar: para qué se optimiza, qué inspecciona primero, qué compromisos elige por defecto y qué forma adopta la respuesta. No enseña nada nuevo al modelo. Dirige la inteligencia ya presente hacia una tarea específica.

Una prueba útil es imaginar que llamas a un colega especialista. Si lo que él aporta es principalmente información que te falta (conocimiento del área, contexto, sabiduría práctica), necesitas una habilidad. Si lo que aporta es principalmente una forma de abordar el problema, es decir, lo que examina primero, lo que considera importante, lo que se niega a aprobar sin verificar y lo que devuelve, necesitas un subagente.

Tomemos como ejemplo a un ingeniero de seguridad que revisa tu código. No solo sabe más que tú, sino que también trabaja de manera diferente: primero establece los límites de autenticación, da mucha más importancia a una ruta de escalada de privilegios que al nombre de una variable poco clara, no da su aprobación sin incluir un comentario sobre los datos confidenciales, y presenta sus hallazgos en una lista estructurada. Ese orden de prioridades es lo que codifica un subagente.

El conocimiento pertenece a una habilidad. La metodología pertenece a un subagente.

Qué es un subagente en Claude Code

Claude Code es la herramienta de referencia aquí porque es la que se utiliza a diario. Otras herramientas tienen su propia sección más abajo, incluyendo sus particularidades.

Dentro de Claude Code, un subagente resulta ser nada más que un documento Markdown que comienza con un breve bloque de YAML. Pueden contenerlo dos directorios:

• ~/.claude/agents/ es la biblioteca personal, disponible en cada proyecto del equipo. Considérela como un entorno aislado.
• .claude/agents/ dentro de un repositorio está limitado a ese proyecto y se traslada junto con el repositorio una vez se realiza el commit.

El frontmatter es breve. Aquí hay un ejemplo completo y funcional:

---
name: migration-risk-reviewer
description: Reviews database migration plans and schema changes for rollback risk, lock contention, and data integrity problems. Use before running any migration against real data.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior database engineer reviewing a migration for production risk.

## What you look at first

- Can this be rolled back without losing data?
- Does it hold locks on a busy table during deploy?
- Is the ordering safe for a multi-step change?
- Will existing data violate any new constraint?

## Output shape

Findings in order of severity:

1. Blockers — deploy will fail or data will be lost
2. High risk — real production risk, needs a mitigation
3. Medium risk — should fix, won't necessarily block
4. Notes — worth tracking

For each finding: what it is, why it matters, what to do about it.

Hay varios aspectos relacionados con la forma en que Claude Code maneja un archivo como este que es útil conocer.

• El cuerpo del archivo es la instrucción del sistema. Todo lo que se encuentra debajo del frontmatter se convierte en las instrucciones del subagente cuando este se ejecuta. No se trata de documentación que el modelo lea y luego actúe en función de ella; el modelo la lee y la adopta como su identidad.
• La description tiene una gran importancia. Claude Code la consulta para decidir cuándo transferir automáticamente el trabajo, por lo que debe redactarse como una API que otra persona deba descubrir a partir del contexto. Frases como “Usar antes de ejecutar cualquier migración” sí funcionan, mientras que “Ayuda con asuntos relacionados con la base de datos” no. También incluya la parte negativa: ambos agentes mencionados aquí incluyen una cláusula sobre para qué no sirven, ya que el sistema de enrutamiento pasará sin problemas un trabajo que no le corresponde realizar.

tools es una lista de permisos. Si se omite, el subagente hereda todo. Si se restringe, el revisor quedará físicamente incapaz de editar tus archivos, incluso si tiene ideas al respecto. Para un agente de revisión, esto es una ventaja, ya que una aprobación basada únicamente en “dime qué está mal” no debería permitir reescribir cosas a capricho.

model es una elección relacionada con el presupuesto y no un detalle técnico. Un modelo económico es adecuado para tareas mecánicas, mientras que uno caro es más adecuado para tareas que requieren juicio. Una sección posterior trata este tema en profundidad, ya que explica por qué la delegación suele ser rentable.

Tiene su propia ventana de contexto. La gente subestima esto: el subagente trabaja en un contexto separado y devuelve un resumen, por lo que tu sesión principal no se llena con todo lo que ha leído. Sin embargo, este mismo hecho también puede causar problemas, y una sección posterior muestra cómo ocurre.

No es necesario escribir el archivo a mano. Describa la función que debe desempeñar a Claude Code y él creará el archivo en el lugar adecuado. La orden /agents también se encarga de gestionarlos.

Puede llamar a un subagente solicitándolo directamente, permitiendo que Claude lo dirija según la descripción, o integrándolo en un flujo más amplio donde funcione como trabajador delegado. El comportamiento es el mismo en cada caso.

La palabra “agente” abarca demasiado

Este término se aplica a cuatro cosas diferentes, y confundirlas provoca constantes malentendidos. Separándolas:

• Un subagente (un archivo en .claude/agents/, o un archivo .agent.md en el entorno de Copilot) es un archivo reutilizable que define un rol especializado. De esto trata el artículo.
• Modo de agente o ejecución autónoma es un interruptor de capacidades. Permite que la herramienta ejecute comandos y edite archivos sin necesidad de aprobar cada línea. Se trata de una configuración de permisos y no tiene nada que ver con los especialistas.
• Un agente de codificación en segundo plano o en la nube es un servicio que toma una tarea, la procesa de forma invisible y devuelve un branch o una solicitud de integración. Tampoco se trata de un archivo especializado.
• Un archivo de instrucciones a nivel de repositorio es una guía permanente, las reglas básicas que todo agente debe seguir en ese repositorio de código. Piénselo como el manual del empleado, no como un compañero al que se le llama por nombre.

Cada vez que aparezca “subagente” en lo que sigue, se refiere al especialista reutilizable que se crea una sola vez y se invoca intencionadamente. Entender bien estos cuatro conceptos resuelve aproximadamente la mitad de la confusión.

Creando el primero

Comience con lo más sencillo que realmente funcione. Un primer subagente tiene dos tareas: declarar el rol y explicar qué significa ese rol en la práctica. El revisor de migración mencionado anteriormente ya hace eso. Tiene un rol claro, heurísticas específicas y una estructura de salida predecible, y está diseñado de forma deliberadamente limitada. Se añaden más elementos después de probarlo con trabajos reales y ver qué se pasa por alto.

Los primeros subagentes suelen fallar debido a un rol vago. “Ayudante de seguridad” no es un rol, ya que no indica al modelo qué optimizar ni qué inspeccionar primero. Un rol real funciona como un contrato de comportamiento que abarca el trabajo en sí, lo primero que se examina y las cosas que nunca se pueden ignorar. Si el trabajo no se puede describir en una sola oración, es demasiado vago.

Una versión concreta detalla qué debe tener en cuenta el modelo y qué debe ignorar. Ignorar ciertas cosas es la mitad del valor. Un revisor que le da la misma importancia a un error tipográfico que a un límite de privilegios no es más que una máquina de promedios.

Qué incluir en el cuerpo

Una vez definida la función, un cuerpo útil abarca cinco aspectos. El primer día no se necesitan todos.

1. Lo que optimiza. Lo único que este rol intenta lograr a toda costa. Cuando surge un compromiso, es hacia esto hacia lo que se orienta.
2. Lo que inspecciona primero. Las señales de máxima prioridad que cualquier verdadero especialista lee antes que nada más.
3. Modos de fallo. Las formas específicas en que este tipo de trabajo falla. La verdadera experiencia reside aquí, y la mayor parte de ella solo se descubre al observar al agente cometer errores en tareas reales.

Forma del resultado. No “algún comentario”, sino hallazgos ordenados por gravedad, un plan por fases o una lista clasificada de hipótesis. Un resultado predecible representa la mayor ventaja práctica frente a simples solicitudes.

Qué no debe hacer. Esta sección solía considerarse opcional, pero ya no lo es. En el agente más utilizado aquí constituye la parte más extensa del archivo, y cada línea de ella se refiere a un incidente concreto.

Comience con el rol, las primeras verificaciones y la forma del resultado, y deje que los errores proporcionen el resto.

Ejemplo: un cazador de errores que ignora el último commit

Este es un ejemplo surgido de una molestia recurrente. Algo falla, el error se pega en Claude Code, y su primer instinto es mirar el archivo que se editó más recientemente. A veces eso es correcto; con frecuencia, el último cambio no tiene nada que ver con el problema.

Un depurador experimentado no comienza con el código. Comienza con pruebas, es decir, con lo que realmente está fallando, lo que indican los registros y qué ha cambiado en el entorno, y solo abre el código fuente cuando una hipótesis merece ser probada. Se trata de un comportamiento, por lo que se guardó como un agente:

---
name: bug-investigator
description: Investigates a bug or failure starting from evidence, not from recent code changes. Produces ranked hypotheses with the next diagnostic step for each. Use for "why is this broken" before touching the source.
tools: Read, Grep, Glob, Bash
---

You are a senior engineer investigating a failure. Your job is to find the most
likely cause, rule out the alternatives, and say what to check next.

## Investigation order

1. Start from the symptom — what is actually failing, and how does it show up?
2. Get the error output and any logs from around the time it broke — ask the caller for them if they weren't provided.
3. Only then look at recent changes, and only if the evidence points there.
4. Read source last, once there's a symptom-to-cause hypothesis worth testing.

## Output shape

**Symptoms:** what's failing and how it manifests.
**Likely causes (ranked):** for each — the hypothesis, the evidence for it, the next diagnostic step.
**Ruled out:** what you checked and why it isn't the cause.
**Next steps:** in priority order.
**Open questions:** what you still can't confirm.

## Failure modes to avoid

- Don't assume the last change is the cause without evidence.
- Don't propose a fix before you can name the mechanism.

Luego viene el paso que la gente omite: probarlo con un error real que ya haya sido resuelto, no con uno ficticio. Entregue los síntomas y los registros de ese momento, y observe si su ruta de investigación coincide con la que realmente encontró el problema. Dondequiera que se desvíe, ese desvío se convierte en una nueva línea en el texto.

Ese archivo es donde terminan la mayoría de los informes de subagentes. Todo lo que sigue describe lo que ocurre después de meses de uso, que era la parte que necesitaba contarse.

Lo contrario a lo esperado: un subagente comienza sin conocimientos previos

Todos presentan la ventana de contexto aislado como una ventaja absoluta. Pero tiene efectos en ambos sentidos.

Una oración llegó al agente implementador después de que una transferencia fallara de tres maneras distintas. Describe al agente como alguien que conoce bien el proyecto, pero que no sabe nada de las conversaciones de planificación que precedieron a la tarea.

Si la conversación está “fría”, significa que nunca se tuvieron en cuenta esas dos horas en las que descartaste el enfoque obvio, te convenciste a ti mismo de abandonar una abstracción y optaste por una solución de aspecto extraño por una buena razón. Para el subagente, nada de eso ocurrió. Si el proyecto está “caliente”, significa que cuenta con CLAUDE.md y el código fuente, por lo que ya conoce las reglas y expresiones habituales sin que se las digan.

Si se juzga mal uno u otro aspecto, se genera un desorden predecible. Supón que el agente comparte tu conversación, y reconstruirá con gusto el diseño que descartaste hace una hora, porque desde su punto de vista ese diseño parece perfectamente adecuado. Supón que no sabe nada sobre el proyecto, y pasarás miles de tokens narrando un repositorio que podría haber leído más rápido de lo que tú puedes resumirlo.

La conclusión a la que no llegó la guía para subagentes fue: la transferencia es un archivo, y ese archivo es el contrato. No se trata de un párrafo escrito en la instrucción de la tarea. Es un documento en el disco con secciones fijas, ya que una instrucción improvisada omite silenciosamente una sección crítica diferente cada vez.

En este escenario, la transferencia es un TASKS.md en la raíz del repositorio, generado por una habilidad de planificación. La tarea activa cuenta con estas secciones y ninguna otra:

• Objetivo. Lo que será cierto una vez finalizada la tarea.
• Por qué (señalador). Un enlace a la decisión registrada en PLAN.md, no un nuevo argumento a favor de ella. Un señalador, no prosa.
• Estado de ejecución. El agente mantiene este estado actualizado. Hablaremos más de ello a continuación, ya que es la sección que te salva.

Diseño como piezas numeradas. Una cola serial donde [ ] significa no iniciado, [x] completado y [!] bloqueado, con las dependencias indicadas directamente, como depende de #2.

Archivos. Donde tiene lugar el trabajo.

Pruebas. Las verificaciones que sustituyen a la revisión.

Fuera del alcance. La sección más valiosa de todo el documento.

Informe de resultados. Qué debe contener el mensaje final.

Lo que hace que funcione es una regla: completar cada sección antes de comenzar, y poner un guion solo si realmente no aplica. La sección sin completar es donde el agente improvisa.

Luego está la división que tardó más en ser detectada: dos documentos con duraciones diferentes. El conocimiento básico sobre cómo se realiza el trabajo aquí debe formar parte de la definición del agente, y no repetirse para cada tarea. El archivo del agente contiene el protocolo, es decir, cómo leer una tarea, cómo manejar obstáculos, qué elementos nunca se modifican y qué incluye un informe. El archivo de la tarea contiene el trabajo actual. Pegar una instrucción en tres tareas seguidas es señal de que nunca formó parte del contenido de la tarea, y debería trasladarse al agente.

Estado de ejecución, ya que las sesiones terminan

Una regla ha salvado más trabajos reales que cualquier técnica ingeniosa de creación de instrucciones. Cada vez que el agente se detenga, ya sea porque haya terminado o esté bloqueado, debe registrar el estado actual: marcar la casilla de estado de cada tarea a medida que avanza y actualizar una nota con el estado general que indique qué se ha hecho, qué está bloqueado y por qué, qué queda por hacer y dónde continuar. Editar TASKS.md con ese fin está explícitamente incluido en el alcance, ya que el archivo sirve como punto de recuperación si la sesión falla.

Las sesiones sí fallan. La computadora portátil se cierra, la conexión se interrumpe, se alcanza un límite de uso, o uno se aburre y presiona Ctrl-C en algo que estaba casi terminado. Cuando eso ocurre con un subagente, todo lo que sabía desaparece. Si el único registro del progreso estuviera en su memoria, ahora tendrías que comparar tu repositorio con tu memoria para adivinar hasta dónde había llegado.

Por lo tanto, el agente registra los avances en el disco a medida que los realiza, dentro del mismo archivo que asignó el trabajo. Una sesión posterior abre el archivo y continúa desde el punto marcado. Agrega unas pocas líneas a la definición del agente y convierte una sesión inactiva de trabajo perdido en una en pausa.

Una regla complementaria se refiere al rendimiento en lugar de a la recuperación. Un elemento bloqueado no detiene la cola. Cuando un elemento está insuficientemente especificado o se topa con una dependencia irresoluble, el agente lo marca con [!] junto con una razón en una sola línea y continúa con cualquier elemento restante que no dependa de él, deteniéndose solo cuando ya no haya nada más que procesar. Nunca supone un diseño, y cualquier bifurcación bloqueada se incluye en el informe para que un humano la resuelva.

El comportamiento por defecto ante un problema es detenerse y hacer una pregunta, por lo que una cola de ocho tareas genera una tarea y una pregunta. El comportamiento por defecto sin restricciones es aún peor: el agente adivina un diseño y sigue adelante, dejando siete elementos construidos sobre una invención que nadie aprobó. Salta y continúa, nunca adivines, informa sobre la bifurcación. Esa combinación es lo que te permite poner el trabajo en cola y alejarte.

Quién paga por qué tipo de pensamiento

Aquí el campo model es fundamental, y la economía de la configuración depende de él.

La descripción del implementador, tomada de un proyecto real, dice más o menos lo siguiente: un trabajador Sonnet que lleva a cabo una tarea de codificación mecánica completamente especificada desde el archivo de tareas, mientras que el hilo principal de planificación de Opus continúa; no para decisiones de diseño, preguntas abiertas ni pruebas de calidad en tiempo real, todas las cuales permanecen en el hilo principal.

El modelo caro toma las decisiones mientras que el modelo económico se encarga de la digitación. Un alcance limitado es precisamente lo que hace que el modelo económico sea fiable: un trabajador Sonnet al que se le proporciona una cola numerada y completamente especificada dentro de un código que puede leer funciona de manera confiable.

Esta división también permite dos ritmos de trabajo a partir de la misma maquinaria.

• Controlado. Se organizan dos o tres tareas, se envía al agente a trabajar y se planifica el siguiente lote mientras este está ejecutándose. Ninguna de las partes permanece inactiva esperando a la otra.
• Sin supervisión. Se coloca una gran cantidad de tareas en la cola, luego se abandona el lugar y se vuelve más tarde para revisar las diferencias, un informe y una nota sobre el estado de ejecución que indique qué tarea se bloqueó y por qué.

Bajo todo esto se encuentra la capa de permisos que realmente aplica las reglas. El implementador sin supervisión tiene sus comandos de archivo y shell incluidos en la lista de permisos establecida en la configuración del proyecto, y todo lo que está fuera de esa lista debe ser aprobado previamente. Lo que indica el mensaje de solicitud constituye la política; la lista de permisos es la barrera que la respalda.

Hay una línea adicional en ese agente debido al error más costoso: procesar las tareas numeradas en orden secuencial, de arriba hacia abajo, en una sola pasada, sin trabajadores en paralelo y sin detenerse para informar después de cada tarea.

Los agentes en paralelo suenan como una solución para aumentar la velocidad, pero no lo son en absoluto. Cada uno termina depositando toda su salida en el contexto que lo generó, y una estructura de distribución compleja puede ocultar la sesión que debe leer todo ese contenido. De esa manera se pierde trabajo real. Ejecutar tareas en paralelo mediante archivos separados es algo que se debe optar por solo para casos específicos, nunca como opción predeterminada. La opción predeterminada es que un único trabajador procese una cola de forma secuencial.

Sin presupuesto, gasta todo

Cualquier subagente que cuente con herramientas como búsqueda, recuperación de datos o una shell seguirá trabajando sin ceso hasta que algo lo detenga, y “ya basta” no es una conclusión a la que un modelo llegue de forma fiable por sí solo. Un agente de investigación sin presupuesto puede pasar toda una tarde revisando una gran cantidad de pestañas del navegador ocultas y finalmente entregar un resumen que podrían haber proporcionado los tres primeros resultados.

Por lo tanto, el agente de búsqueda en la web comienza con límites estrictos, establecidos por encima de su metodología y de todo lo demás. Las guías por fuente que carga en tiempo de ejecución, las cuales contienen listas de fuentes y tácticas de consulta para cada dominio, tienen su propia sección más abajo.

Cuatro lecciones extraídas de esa tabla de límites son más importantes que los números que contiene, los cuales debería ajustar según sus propias necesidades de trabajo.

Ofrezca un control de profundidad en lugar de un límite fijo. Cualquier configuración única suele ser incorrecta: demasiado estricta para una pregunta compleja, demasiado generosa para obtener un hecho rápido. Con tres niveles designados y un valor predeterminado establecido, solicitar deep se convierte en una elección consciente en lugar de un accidente. También se especifica el orden de prioridad: prevalecen las cifras indicadas por quien realiza la solicitud, seguidas por un nivel mencionado en la instrucción, luego la configuración del proyecto y, finalmente, standard.

El presupuesto invita al juego, ya que un modelo lo trata como un objetivo, por lo que se necesitan cláusulas para limitarlo. Las cláusulas importantes establecen que se debe realizar una búsqueda por URL, nunca volver a leer una página ya leída, detenerse en cuanto se respondan las preguntas del usuario, y considerar el presupuesto restante como algo distinto a una cuota. Una ejecución profunda que finaliza tras seis búsquedas se considera un éxito y no un desperdicio.

Esa última oración se añadió después de que una ejecución respondiera a la pregunta en la cuarta búsqueda y continuara de todos modos, ya que veinte era el número asignado. Hay que decir en voz alta que terminar antes significa ganar.

Conte los elementos que tienen un costo. El presupuesto de fetch incluye todas las recuperaciones desde la red, desde las solicitudes nativas hasta cada intento adicional para páginas bloqueadas, pasando por cada solicitud HTTP dentro de un script auxiliar, siendo que cada intento de reintentar con código 429 en dicho script auxiliar se cuenta por separado. Una versión anterior solo contaba las “solicitudes de fetch” y el agente lograba pasar desapercibido sin querer. Eso no era trampa; simplemente seguía fielmente una regla mal redactada.

Hágale anunciar los gastos. Después de cada fase, el agente informa una línea como [deep: 3/20 búsquedas, 5/30 recuperaciones]. Sin esto, no se puede distinguir entre una ejecución cuidadosa y una descontrolada hasta que esta finaliza. Si se agota el presupuesto con preguntas sin responder, el agente se detiene y indica con exactitud qué sigue sin saberse, qué URL es la más probable para responder y que volver a ejecutarlo en profundidad es una opción. La única acción prohibida es seguir adelante más allá del límite sin indicarlo, ya que quien llama eligió el nivel y el gasto excesivo anula esa elección.

Las restricciones constituyen la mayor parte de un agente maduro

Al abrir el archivo del agente más utilizado, lo que llama la atención es la proporción entre su descripción y las prohibiciones. La descripción del rol ocupa un solo párrafo, mientras que las prohibiciones llenan toda una lista. Esa desigualdad no se debe a espacios en blanco innecesarios. Un agente con herramientas reales cuenta con muchas más formas de cumplir con los requisitos técnicos de las que cualquiera podría prever.

Un ejemplo ilustra por qué lo que se indica entre paréntesis es el punto clave. Se le indica al agente que nunca debe usar automatización de navegadores: ni navegadores simples, ni vistas previas integradas, ni Playwright, ni herramientas de extensiones de Chrome, ni abrir pestañas o ventanas; además, si se le ofrece alguna herramienta de navegador, no está destinada a esta tarea. La razón se explica allí mismo: abrir pestañas para leer páginas ya generadas generó alrededor de cien de ellas y arruinó una ejecución.

Otro proviene del implementador en el repositorio research-agent, donde el mecanismo es la razón principal por la que alguien respetaría la regla. Nunca debe crear archivos bajo agents/ o skills/, ya que agents/ contiene el contenido a entregar y el gestor de paquetes convierte cada archivo .md que se encuentre allí en un agente de nivel superior separado al instalarlo. Un archivo extraviado en esa carpeta terminaría en todos los proyectos que lo utilicen.

Ese es el principio a extraer: cada prohibición indica su mecanismo. No es necesario persuadir al agente. La razón debe escribirse, ya que una restricción sin ella será modificada. Después de seis semanas, al simplificar el texto, llegarás a una línea que diga “nunca crear archivos aquí”; parecerá arbitraria, así que la generalizarás de forma útil. La cláusula sobre el instalador que reduce todo a cada proyecto de usuario es lo que hará que tu yo futuro lo deje en paz.

Al cabo de tiempo, estas restricciones adoptan algunas formas más:

Prohibir la categoría y enumerar las instancias. Una simple indicación de “prohibida la automatización del navegador” deja que el agente decida si un panel de vista previa cumple los requisitos. Enumerar seis herramientas específicas que no puede utilizar cierra la posibilidad de que argumente para usarlas de todos modos.

Nombrar el comportamiento, no solo la herramienta. La mejor línea del archivo prohíbe una tendencia en lugar de una orden: si te das cuenta de que estás escribiendo un raspador o un generador de informes, detente, porque estás eludiendo la tarea en lugar de llevarla a cabo. Los agentes capaces sortean las limitaciones creando herramientas. Esa es la categoría que debe ser prohibida.

Se deben establecer condiciones de salida de emergencia, de lo contrario se convierte en una autopista sin fin. Hay algunas páginas que realmente no se pueden obtener, y por eso existe una serie de soluciones alternativas para las URLs bloqueadas. Esta opción solo se activa cuando la ruta habitual falla con esa URL en particular. Nunca obtiene un espacio adicional para realizar una nueva solicitud, verifica si existe una herramienta instalada sin necesidad de instalarla, y limita la salida para que el contenido completo de una página no abarrote el contexto. Después de eso llega el límite final: si la URL sigue siendo inaccesible después de haberse agotado todas las soluciones disponibles, se da por terminado. Se registra el incidente y se pasa a otra cosa, sin intentos adicionales, sin herramientas extra ni ideas creativas adicionales.

Explique detalladamente por qué la excepción no constituye una laguna legal. Un breve párrafo en el archivo explica que una solicitud sin interfaz gráfica realizada una sola vez para imprimir texto plano no viola la prohibición del navegador, ya que dicha prohibición está dirigida a usar el navegador y dejar pestañas abiertas para que alguien las cierre. Si se omite ese párrafo, la excepción y la prohibición parecen entrar en conflicto, y un modelo ante tal conflicto elige la interpretación que permite más libertad.

Fracasan en silencio, y con confianza

En dos estudios, los resultados no solo fueron aceptables, sino también excelentes: hallazgos claros, fuentes reales y un informe coherente. Ambos mencionaron a Reddit como fuente principal. Sin embargo, ninguno de los dos recuperó nada de Reddit.

Lo que sucedió fue que una consulta de WebSearch restringida con site:reddit.com devolvió diez resultados limpios y plausibles de otros dominios, entre ellos un foro comunitario de mercados de artesanías, un sitio gubernamental dedicado a las pequeñas empresas y un sitio de intercambio de diapositivas, sin ningún tipo de error. Ningún 403, ningún conjunto vacío, ninguna advertencia. El filtro de dominios había sido ignorado silenciosamente y nada en el resultado lo indicaba. El agente contaba con una lista ordenada de páginas utilizables provenientes de lugares inadecuados, y hizo lo que cualquier trabajador sensato haría con tal lista: las utilizó e informó de éxito.

La regla establecida ese mismo día es ahora la base de todo el proyecto: si no se puede acceder a una fuente identificada, la ejecución debe indicarlo claramente, y nunca debe continuar en silencio con lo que sea que la herramienta haya devuelto en su lugar. Un informe que menciona a Reddit como fuente principal mientras afirma el éxito en foros de mercados es peor que un fracaso total, ya que nadie que lo lea puede darse cuenta.

Una ejecución fallida implica realizarla de nuevo. Una ejecución que cambia silenciosamente sus fuentes conlleva tomar decisiones basadas en evidencias que se asume provienen de un lugar donde en realidad no lo hacen. La ventana de contexto aislada, precisamente esa característica, es la razón por la cual no se puede observar lo que ocurre: no se recibe transcripción alguna, solo el resumen que el agente decidió redactar.

Existen tres soluciones para esto, y ninguna de ellas consiste en pedirle al agente que sea más cuidadoso.

Realice una prueba mecánica. No se detectó ningún error, por lo que el agente no vio motivo para inspeccionar nada. La solución es una sola oración que no requiere juicio alguno: cuando la búsqueda se limitó a un dominio y ninguna de las URLs obtenidas pertenece a él, considérelas como cero resultados en lugar de un conjunto de resultados. No se necesita ninguna herramienta adicional, ni solicitud de datos ni permisos, ya que las URLs ya están disponibles. “Desconfíe de sus fuentes” no le da al agente nada que hacer, mientras que “Verifique el nombre del host contra el que filtró” sí lo hace.

Trate el origen como un canal de salida obligatorio con un esquema. Aquí es donde la estructura de la salida deja de ser un conjunto de títulos de sección y comienza a comportarse como un tipo. Dos arrays están definidos por sus nombres de clave.

• unreachable[] contiene una entrada por muro, con claves que son exactamente source, url y reason. Incluye tanto los fallos de obtención de datos como las sustituciones silenciosas.
• sources[] alberga una entrada por cada fuente que realmente proporcionó una respuesta, con claves que son exactamente source, url y fields. Las páginas que se abrieron pero no proporcionaron información alguna no se registran. Una fuente que respondió con cuatro campos genera una sola entrada que lista cuatro nombres, y no cuatro entradas separadas.

La llamada sutil, que al principio fue incorrecta: la procedencia sirve para anotar y nunca para bloquear. Si un sustituto documentado responde a la pregunta, el campo se considera respondido, y la entrada unreachable simplemente registra que la respuesta no provino de la fuente indicada. Permitir que un obstáculo haga que el campo falle haría que el proceso fallara de forma evidente justo en la situación en la que existe una solución alternativa.

Un fracaso conlleva una lección valiosa que merece ser aprendida. El primer borrador de este agente indicaba que debía “registrarlo como inalcanzable” en cuatro lugares distintos, pero nunca se especificó qué campo, arreglo o posición de salida utilizar. Esa instrucción no llevaba a ninguna parte. El agente tenía que registrar algo sin saber dónde hacerlo, por lo que no registró nada, y nada se quejó. Cada vez que escriba una instrucción para un subagente, asegúrese de que la acción que describe tenga un destino. “Informar sobre X” sin especificar qué es X no hace nada y, sin embargo, el agente no presenta problemas al respecto.

Verifique desde fuera del agente. Si el agente cumple con su contrato de salida lo determina un script ejecutado posteriormente, no la afirmación del propio agente. Aproximadamente 180 líneas de Python comprueban el JSON en relación con los campos declarados, y eso vale más que cualquier énfasis incluido dentro de la instrucción.

La misma idea vuelve a aparecer en las instrucciones para un repositorio que no cuenta con un conjunto de pruebas al que recurrir. En dichas instrucciones se indica que no existe tal conjunto; la sección de Pruebas de la tarea enumera las verificaciones que sirven en su lugar, todas deben ejecutarse y los resultados deben reportarse de manera concreta. Cuando una verificación indica “esta URL se resuelve”, eso significa que realmente se debe descargar su contenido. Una URL que no pueda verificarse no se incluye en ningún archivo; se informa que no ha sido verificada, junto con los motivos, ya que un lector que confíe en un enlace que nadie ha comprobado perderá tiempo intentando descargarlo cuando en realidad dará un error 404, algo que se podría evitar con una búsqueda simple, lo que hace que una URL sin verificar sea una opción peor que omitirla por completo.

Los agentes suelen afirmar fácilmente haber realizado verificaciones que en realidad no han hecho, porque una afirmación creíble y una verificada se ven igual en el resumen. Para cada verificación importante, especifique la acción concreta que se llevó a cabo para considerarla completada.

Un trabajo por agente y los hábitos que hinchan el archivo

Los mejores subagentes tienen un único trabajo. Aquí objetarás, ya que los archivos mencionados anteriormente no son pequeños, y el archivo del agente de investigación llega a tener 188 líneas. La distinción que lo resuelve es que el trabajo se mantuvo en una sola oración mientras el archivo crecía. Lo que se acumuló fueron restricciones, reglas de detección y especificaciones de salida, como tejido cicatricial alrededor de un esqueleto fijo, sin que se añadiera ni una sola responsabilidad nueva en un año. Las líneas añadidas debido a algún problema significan que el archivo está cumpliendo su función. Las líneas añadidas para abarcar un nuevo tipo de trabajo constituyen sobrecarga, y la solución es dividir al agente, no añadir otra sección más.

Las versiones exageradas se ven todas iguales, y cada una ha sido lanzada en algún momento. Está el revisor de todo, que calcula un promedio entre cinco aspectos sin destacar en ninguno. Está la etiqueta de “ingeniero senior” sin ningún comportamiento real detrás. Está el agente que reescribe tu CLAUDE.md, añadiendo costos de tokens en lugar de comportamientos, y aquel que duplica una habilidad hasta que ambas se separan. Todas comparten un error fundamental: una tarea que se ha vuelto más extensa que una oración.

La siguiente pregunta obvia es qué, después de un año de esto, realmente queda en la lista de opciones.

Los dos que sobrevivieron

La mayoría de los artículos sobre el tema te proporcionan un organigrama de tipos de agentes para que los construyas. La verdadera lista de opciones después de un año son solo dos agentes, y nada más.

Una aclaración, ya que se aplica la propia regla del artículo: el agente de búsqueda en la web nació como una bifurcación de un proyecto de código abierto dedicado a habilidades de investigación profunda. El esqueleto del contrato de resultados, es decir, las secciones de resumen y la lista de fuentes siempre obligatoria, proviene casi literalmente del proyecto original. La capa de control añadida encima, que abarca los presupuestos, las prohibiciones, el esquema de procedencia y la escalera de escalada, es original y representa la mitad del número total de líneas. Todo lo relacionado con los aspectos negativos en este texto se refiere a esa mitad.

El agente de búsqueda en la web realiza búsquedas limitadas en Internet y devuelve los hallazgos junto con sus fuentes. Actualmente está instalado en una docena de repositorios, entre ellos un sitio web estático, un par de pipelines y algunos proyectos de investigación. Todo el material aquí sobre presupuestos, prohibiciones y sustituciones silenciosas proviene del historial de revisiones de ese único archivo.

El implementador ejecuta una cola de tareas completamente especificada mientras la planificación continúa en otro lugar. Cuatro proyectos cuentan con uno. Esos cuatro proporcionaron las lecciones sobre contratos de transferencia, estado de ejecución y la economía de la delegación.

El resto de los elementos que se encuentran en las carpetas de los agentes llegaron junto con frameworks, y funcionan como un cajón de trastos con una marca mejor que uno real. Los especialistas que se consideraron necesarios (un investigador de pruebas impredecibles, un agente encargado de mejorar la imagen pública, un redactor de documentos, un agente orientado a la base de código para proyectos abandonados) parecían razonables, pero prácticamente ninguno se desarrolló. Los que quedan resultan no ser aquellos que parecían útiles; son aquellos en los que el mismo problema específico de que el trabajo se realice en el contexto equivocado o con la persona inadecuada seguía apareciendo una y otra vez.

Omite el organigrama, entonces. Presta atención al trabajo que deseas que se realice en otro lugar y guárdalo.

Primero el modelo, luego la especialización

El patrón que hace que los segundos, terceros y cuartos implementadores sean económicos es el siguiente: el agente se genera a partir de un modelo y luego varía en los puntos en que el proyecto difiere.

La habilidad de planificación incluye un modelo de implementador con marcadores de posición, y al estructurar un nuevo proyecto se escribe conjuntamente el agente, el documento de planificación y el documento de tareas. Lo que obtienes es el protocolo: lee el contrato, toma las partes en orden, omite todo lo que esté bloqueado, mantén el estado de ejecución actualizado, quédate dentro del alcance y haz un informe al final. Esas reglas nunca cambian entre proyectos, ya que describen la delegación en sí y no mencionan nada sobre tu código.

Después de eso, cada copia desarrolla su propia sección para su propia superficie de fallos, y poner dos una al lado de la otra es instructivo. La plantilla indica al agente que mantenga el conjunto de pruebas en estado positivo. Un proyecto no cuenta con ningún conjunto de pruebas en absoluto; es un repositorio de instrucciones, y su único archivo ejecutable es el validador. Por lo tanto, su implementador afirma algo completamente distinto: el repositorio alberga instrucciones y datos en lugar de código; editar un archivo significa editar una instrucción; la redacción, el orden y el énfasis constituyen la implementación; y una reescritura que mejora la legibilidad al eliminar una restricción estricta es una regresión que no será detectada, ya que no existen compilaciones ni pruebas.

La copia de otro proyecto recibió la instrucción de estudiar las decisiones indicadas en el PLAN.md a las que se refiera una tarea antes de programar, además de una línea para informar sobre cualquier situación que requiera una intervención de Opus o de un humano. El protocolo es el mismo, pero los riesgos difieren.

Esa es la división que hay que recordar. La parte reutilizable de un subagente es su protocolo, mientras que su parte específica del proyecto es su superficie de fallos. Usa plantillas para la primera y escribe a mano la segunda; no intentes que un único archivo cubra ambas.

Dirige al agente hacia el conocimiento y no péguelo directamente

Aquí es donde las habilidades y los subagentes se combinan, y la idea se volvió mucho más concreta una vez que un proceso real dependió de ella.

Mi consejo anterior habría sido nombrar la habilidad relevante dentro del cuerpo del agente. Lo que funciona mejor es algo más estricto: el agente lee el conocimiento en tiempo de ejecución antes de poder actuar, y el prompt explica el motivo.

El agente de investigación no puede realizar ni una sola búsqueda hasta que haya leído la tabla de enrutamiento almacenada dentro de una habilidad. La instrucción está marcada como obligatoria y dice: antes de realizar cualquier búsqueda o recuperación, lea la tabla en la primera ruta disponible; no omita este paso; no enruté desde la memoria, ya que los módulos cambian mientras el prompt permanece igual: uno que recuerde podría haber desaparecido, y uno que necesite podría no haber existido aún.

Esa observación sobre que la lista cambia mientras el prompt se mantiene estable es la justificación completa para este patrón. Los conocimientos (qué fuentes responden a qué tipo de preguntas, cómo consultar cada una, qué está bloqueado) cambian mensualmente, mientras que el método se mantiene fijo. Al incorporar una lista de fuentes en el cuerpo del agente, cada nueva fuente obliga a modificar un prompt que de lo contrario permanecería sin cambios, y el agente enrutará con confianza hacia un módulo que ya fue eliminado en marzo.

Dos aspectos mecánicos resultaron ser más importantes de lo esperado.

Los candidatos en orden, en lugar de un único camino. El agente funciona en proyectos organizados de manera diferente, en dos máquinas con nombres de usuario distintos, configurados por instaladores diferentes. Por lo tanto, la instrucción enumera las ubicaciones de los candidatos en secuencia y indica tomar el primero que exista, priorizando las copias locales del proyecto sobre las de nivel de usuario. Si se establece un único camino de forma fija, todo funcionará solo en una máquina.

Los nombres literales unen las capas entre sí, y nada los verifica. El diseño consta de tres niveles: las habilidades se encargan de la coordinación, un agente realiza el trabajo y los módulos de datos almacenan el conocimiento. No existen importaciones en ningún lugar. Una habilidad activa al agente mediante su nombre registrado con precisión, mientras que el agente encuentra los módulos por su ruta. Eso genera la frase más común y al mismo tiempo más peligrosa del repositorio, una advertencia para no renombrar al agente de búsqueda web, ya que los usuarios existentes lo llaman directamente.

El nombre de un agente funciona como una API pública, pero ninguna herramienta lo indica: no hay compilador, ninguna prueba, ningún aviso. Un cambio de nombre parece un commit ordenado, pero rompe todas las conexiones con todos los repositorios que hayan instalado ese agente, y el problema se detecta la próxima vez que solicites información y un agente generalista responda.

Dónde se encuentran los archivos: personales, de proyecto, empaquetados

Hay tres niveles, y en el tercero es donde viven todos los agentes reales.

• Personal (~/.claude/agents/) está destinado a especialistas generales necesarios en cada proyecto. Considéralo como el taller, donde está bien romper cosas.
• Project (.claude/agents/, comprometido) sirve para especialistas que solo tienen sentido en un código base, como un implementador consciente de que ese proyecto carece de pruebas. Al comprometerlo, estará esperando cada vez que regrese, incluso cuatro meses después de que el proyecto haya dejado de ser recordado.
• Packaged (instalado por un gestor de paquetes y vinculado a un commit) convierte a un agente en una dependencia. Este es el nivel del que nadie sabe que lo necesita hasta que ese mismo agente aparece en una docena de repositorios y sus trece copias comienzan a divergir.

El tercer nivel cambia algunas cosas, y es mejor conocerlas antes de llegar allí.

Combina el agente con las habilidades que lo invocan. El paquete incluye ambos como una sola unidad por una razón sencilla: las habilidades instaladas sin sus agentes generan un flujo de trabajo que falla al primer uso. Una habilidad que intenta enviar una solicitud por nombre a un agente ausente representa una instalación defectuosa, que en el mejor de los casos muestra un mensaje de error claro. Forman una sola unidad porque constituyen un único contrato.

Conozca qué hace su instalador con los archivos. Este paquete se instala a través de APM de Microsoft, el cual convierte cada archivo .md ubicado dentro de un directorio agents/ en un agente de nivel superior independiente. Esa configuración predeterminada es sensata, pero aún así resulta problemática. Si se coloca un archivo de datos en esa estructura, cada proyecto que lo utilice obtiene un agente registrado falso. Si se crea un agente específico para un proyecto allí, este se instalará en los repositorios de todos. Por esta razón, los módulos de estrategia de búsqueda se encuentran en skills/ y no en la carpeta agents/, donde parecería ser su lugar adecuado: en agents/ perderían su estructura durante la instalación y registrarían cinco agentes fantasma por cada proyecto que los utilice.

Fija un commit y recuerda que los consumidores van por detrás. Los consumidores dependen de un SHA, por lo que una corrección no está disponible para nadie hasta que se actualice la referencia y se vuelva a ejecutar la instalación. Escribir una corrección no significa enviarla. Eso suena obvio en la página, pero es todo lo contrario a las 11 de la noche, cuando el error corregido la semana pasada vuelve a aparecer.

Aun así, haz limpieza. Una carpeta llena de agentes superpuestos y medio olvidados genera ruido en lugar de herramientas útiles. Fusiona aquellos que han terminado en el mismo trabajo. Elimina aquel que no se ha ejecutado en meses, porque el historial de Git lo conservará si la eliminación resulta incorrecta. Eso también es un buen consejo de vida, pero se ignora en favor del verdadero cajón de trastos de casa.

La misma idea en otras herramientas

Claude Code no es el único lugar donde esto se aplica. Si pasas de una herramienta a otra, estas ideas se transfieren incluso cuando los formatos de archivo no lo hacen.

GitHub Copilot y VS Code denominan a estos agentes personalizados, almacenados como archivos .agent.md, generalmente en la carpeta .github/agents/, con la opción de tener una biblioteca personal en el directorio del usuario. El frontmatter incluye más campos que el de Claude: además del name, description y tools anteriores, se añaden argument-hint, model, user-invocable, disable-model-invocation y, lo mejor de todo, handoffs. Un agente ya creado puede mostrar un botón que transfiere el trabajo a otro agente con el siguiente prompt ya prefillado, de modo que la planificación, implementación y revisión se realizan de forma consecutiva sin mezclarse en un único agente confuso. Es una trampa si se consultan ejemplos anteriores: el campo anterior infer pasó a ser dos campos separados, user-invocable y disable-model-invocation; un cambio que parece lógico con el tiempo pero que resulta confuso al principio.

Otra afirmación que se encuentra es que VS Code detecta los archivos .claude/agents/ y traduce los nombres de las herramientas, de modo que un agente puede utilizar ambas herramientas sin costo alguno. Aunque es cierto, puede inducir a error, ya que los vocabularios de las herramientas no coinciden, y una instrucción que prohíba el uso de herramientas por su nombre, como lo hace todo agente maduro, no se transmite intacta mediante la traducción automática.

En realidad, lo que se incluye es una instrucción canónica más un pequeño módulo nativo para cada herramienta. Todo el agente del lado de Copilot en el paquete consta de once líneas:

---
name: Web Research Writer
description: "Use for bounded web research that must read a local schema, search and fetch current sources, write one designated result file, and validate it with a local command."
tools: [read, search, web, edit, execute]
user-invocable: false
disable-model-invocation: false
---

Load the installed canonical research prompt from the first existing candidate:

1. `.github/agents/web-search-agent.agent.md`
2. `.claude/agents/web-search-agent.md`

Follow its search budgets, module routing, source standards, tool discipline, output, and validation rules. Ignore that file's incompatible `tools` frontmatter; this wrapper's Copilot-native tool categories govern this session.

Ese es el patrón completo. El frontmatter nativo permite al host registrar correctamente al agente, una secuencia de rutas localiza el prompt real, y una oración sencilla indica qué vocabulario de herramienta tiene prioridad. Las 188 líneas de comportamiento acumulado se encuentran en un único archivo, y la segunda herramienta recibe un puntero en lugar de una copia independiente. Dos copias de un prompt generan dos prompts distintos, y el día en que uno recibe una corrección de error sin el otro es el día en que comienzan a presentarse erróneamente como un único agente.

La página README del proyecto señala un problema. Si se dirige el cargador a .github/agents/, el prompt canónico se registra como un agente por sí mismo, lo que puede hacer que Copilot muestre nombres duplicados: el complemento “Web Research Writer” y, debajo de él, el archivo canónico. Es necesario elegir un único lugar de almacenamiento por herramienta, o mantener el archivo canónico en .claude/agents/, donde la detección automática de Copilot lo ignora.

Todo lo demás, incluido Cursor y Windsurf, se encamina hacia lo mismo bajo etiquetas como reglas, modos o agentes. Los detalles cambian con suficiente frecuencia como para que sea mejor enviarlo a la documentación actual de cada herramienta que afirmar con certeza algo que ya cambió el mes pasado. El movimiento fundamental no varía: un archivo reutilizable que define un rol y que se invoca intencionadamente. Aprende eso una vez y lo que queda es encontrar dónde cada herramienta esconde su carpeta.

Cómo se construyen realmente las buenas herramientas

Cada subagente aquí comenzó siendo demasiado amplio. Había un “revisor” que revisaba todo, un “planificador” que no tenía opinión sobre cómo debería ser un plan, y un “investigador” que abordaba cada error como si fuera el anterior. Eso no es un fracaso. Es el punto de partida.

La parte útil, la que habría sido de ayuda hace un año, no es “iterar”. Todos dicen iterar. De eso se componen las iteraciones.

Vuelve a leer los archivos del agente citados anteriormente y fíjate dónde están las palabras: un párrafo para el rol, una página con las restricciones, un esquema con los nombres de las claves escritos, una regla mecánica para la detección, un presupuesto numérico con una cláusula contra el manipularlo, una observación sobre que los pagos recibidos deben ser divulgados, y una prohibición que explica qué hace el instalador con los casos excepcionales. Casi todo ello registra algo específico que salió mal en algún momento.

Tras un rendimiento decepcionante, la pregunta relevante no es cómo formular mejor el papel del agente. Hay que preguntarse qué hizo exactamente el agente, qué parte del archivo lo permitió y qué reglas de la oración lo excluirán la próxima vez. Cien pestañas del navegador. Diez resultados fuera del dominio sin errores. Una instrucción para la que no había dónde colocar la respuesta. Una verificación solicitada pero nunca realizada. Cada uno de estos elementos se convierte en una línea, y esa línea perdura más allá de la sesión en la que se aprendió, que es precisamente el propósito de guardarla en un archivo.

La misma prueba se aplica antes de conservar un agente, al igual que antes de conservar una habilidad: ¿se puede describir su función en una oración? Si no, es demasiado amplia, y dos agentes más pequeños comparten el mismo rol. Para determinar si realmente es bueno se necesita otra prueba: cuando comete un error, ¿se puede señalar la línea que lo causó? Si no es posible, aún no existe un especialista, solo un conjunto de instrucciones preliminares.

Al combinarlos, dejas de tener que solicitar una y otra vez la ayuda de un generalista muy capaz. Mantienes un pequeño grupo de especialistas que ya comprenden tu mundo y sus propias tareas. Para alguien que desea lograr más de lo que razonablemente podría hacer una sola persona, esto es lo más cercano a contratar ayuda sin realmente hacerlo.

Observa el trabajo que deseas que se realice en otro lugar: ese es un subagente que aún espera ser activado. Y la última vez que un subagente te falló, fue porque aún faltaba escribir una línea específica.

Leer más

• Notas prácticas: Una guía paso a paso para desarrollar tu agente personal — Guía detallada de Notas prácticas: Una guía paso a paso para desarrollar tu agente personal: contratos, verificaciones y espacios para código listos para usar para los equipos que implementan este patrón.
• Notas prácticas: Qwen3.8–27B como nuevo agente de programación recomendado con SGLang/vLLM y — Guía detallada de Notas prácticas: Qwen3.8–27B como nuevo agente de programación recomendado con SGLang/vLLM y: contratos, verificaciones y espacios para código listos para usar para los equipos que implementan este patrón.

El Arnés Es el Producto: Una Guía Práctica sobre los Arneses en la IA Agente — Aprenda qué es un arnés para agentes y sus siete componentes, desde herramientas y contexto hasta límites y evaluaciones, además de subagentes, modos de fallo y marcos que merece conocer.