El problema que nadie te cuenta sobre trabajar con agentes de IA
Todos hablan de lo que los agentes pueden hacer. Nadie habla de lo que necesitan para hacerlo bien.
Hoy fue un día intenso: construí una landing page completa para un cliente, rediseñé las cards de propiedades de otro, lancé un rediseño de plataforma para un tercero — y en el proceso me di cuenta de algo que cambia todo.
Mi agente de IA era brillante en un proyecto y mediocre en otro. No por el modelo. Por el contexto.
Qué pasó exactamente
Llevo semanas trabajando con un agente de IA como mi ingeniero principal. La velocidad es absurda — hoy en una sola sesión:
- Cliente 1: Landing page de ventas, 7 páginas de producto estilo Airbnb, sistema de booking interactivo con pasarela de pagos, emails transaccionales. Desde cero hasta deploy.
- Cliente 2: Rediseño de cards de producto y página de detalle con layout moderno. Patrón copiado del cliente 1 y adaptado.
- Cliente 3: Rediseño completo de landing, pipeline Kanban, sistema NPS, task manager con 500+ tareas.
Pero al pasar de un proyecto a otro, notaba algo: en los proyectos con buenas instrucciones para el agente, el trabajo fluía. En los que no las tenían, cada sesión empezaba con "déjame entender qué es esto".
La lección: estructura mata talento (también en agentes)
Un agente de IA sin contexto es como un empleado nuevo sin onboarding. Puede ser el más capaz del mundo, pero si no sabe:
- Qué es el proyecto (propósito, stack, URLs)
- Dónde quedó (estado actual, qué está en progreso, qué está bloqueado)
- Qué reglas seguir (convenciones de código, voz de marca, restricciones)
...va a perder tiempo descubriendo cosas que ya se sabían.
Lo que hice hoy para resolver esto
Reorganicé todo mi workspace de 21 proyectos con una estructura que permite delegar trabajo real a agentes:
Workspace/
├── comando/ ← Backlog maestro, plan semanal, decisiones
├── marca-personal/ ← Brand voice, ofertas, contenido
├── equipo/ ← Reportes diarios del equipo
├── proyectos/
│ ├── internos/ ← 14 productos propios
│ └── clientes/ ← 7 proyectos de clientes
└── herramientas/ ← Tools y scripts
Cada proyecto nuevo arranca con una plantilla estándar:
- Instrucciones del agente — Contexto del proyecto (qué es, stack, reglas)
- Estado actual — En progreso, siguiente paso, bloqueadores
- README — Cómo correr el proyecto
Y a nivel central, un backlog que me deja ver el estado de los 21 proyectos en 30 segundos.
Por qué esto importa más de lo que parece
El trabajo agéntico no es "pedirle cosas a la IA". Es diseñar sistemas donde la IA puede operar de forma autónoma.
Eso requiere:
- Contexto persistente — El agente necesita saber en qué proyecto está y cuáles son las reglas
- Estado explícito — Qué se hizo, qué falta, qué está bloqueado
- Estructura predecible — Si cada proyecto tiene la misma forma, el agente no pierde tiempo navegando
Hoy repliqué un patrón de diseño (cards estilo Airbnb) de un cliente a otro en minutos. No porque el agente sea mágico — porque ambos proyectos tenían contexto claro y el patrón estaba documentado.
El takeaway
Antes de pedirle más a tu agente de IA, dale mejor contexto.
20 líneas de instrucciones claras valen más que 20 prompts explicando lo mismo. Un archivo de estado actualizado elimina la pregunta "¿dónde quedamos?". Un backlog centralizado te da visión de CEO sin micromanagement.
El orden no es burocracia. Es la infraestructura que permite que la inteligencia artificial trabaje como inteligencia real.
Nuevo skill en el radar: Understand Anything
Hoy también documentamos y creamos la página de una herramienta que vamos a instalar mañana: Understand Anything.
Qué es
Es un plugin de Claude Code que transforma cualquier codebase en un grafo de conocimiento interactivo. En lugar de leer cientos de archivos para entender un proyecto, el plugin analiza la arquitectura, extrae relaciones entre componentes y te presenta todo en un dashboard visual navegable.
Por qué nos interesa
Conecta directamente con lo que aprendimos hoy sobre contexto. Si el problema principal es que el agente necesita entender el proyecto para trabajar bien, Understand Anything automatiza esa comprensión:
- Genera explicaciones en lenguaje natural de cada parte del código
- Crea tours guiados ordenados por dependencia para onboarding
- Analiza impacto de cambios antes de tocar algo
- Búsqueda semántica — busca "autenticación" y encuentra
auth,login,session
Cómo lo vamos a documentar
La idea es instalar el skill mañana y documentar paso a paso:
- Instalación — Cómo se agrega a Claude Code
- Primera ejecución — Qué genera con un repo real (este mismo sitio)
- Valor real vs. promesa — ¿Realmente ahorra tiempo? ¿En qué casos sí y en cuáles no?
- Integración con el flujo de trabajo — Cómo encaja con nuestra estructura de proyectos
Todo quedará documentado en el diario para que sea un caso de estudio práctico, no una reseña genérica.
Recursos
- Understand Anything: Ver herramienta
- Si quieres aprender a trabajar con agentes de IA como empleados reales: Mi Primer Empleado AI
- Si quieres ver cómo opera mi agente CMO en el día a día: Conoce a Claudia
- Mejores prácticas para trabajar con agentes de código: Guía completa
- Más entradas del diario: Diario