Cómo escribir instrucciones para agentes de IA (y que sigan funcionando)

En Odysi, un agente de IA hace buena parte de nuestro propio trabajo de CRM, correo y propuestas. Registra los correos, mantiene al día el historial de cada oportunidad y las tareas, redacta respuestas que luego envía una persona, prepara las llamadas y escribe el informe semanal del pipeline comercial. Es Claude, que trabaja a través del conector de nuestro CRM mediante MCP, el estándar abierto para conectar aplicaciones de IA con otros sistemas. Todo lo que hace sigue un reglamento al que llamamos el Playbook.

En unas cuatro semanas, el Playbook llegó a 266 KB repartidos en 11 documentos. Cada corrección que le dábamos al agente se convertía en más texto, y más texto lo hacía menos fiable. El 6 de octubre de 2026 lo reescribimos. Este es el resultado:

No se borró nada. Casi todo el volumen era historial, y ahora está en un único documento de archivo que el agente no lee para trabajar. El resto de esta guía es lo que aprendimos, contado para que cualquier empresa lo pueda aplicar.

Un reglamento que el agente lee en cada ejecución se degrada igual que una conversación larga y desordenada. Anthropic llama context engineering (ingeniería de contexto) al trabajo de decidir qué entra en el contexto del modelo, y explica que, cuanto más crece ese contexto, peor recuerda el modelo lo que hay en él. El estudio Context Rot de Chroma probó 18 modelos en julio de 2025 y vio que el rendimiento cae a medida que la entrada se alarga, incluso en tareas sencillas a propósito.

Las contradicciones lo empeoran. La documentación de Claude Code de Anthropic advierte de que, si dos instrucciones se contradicen, Claude puede elegir una de forma arbitraria, y recomienda que cada archivo de instrucciones no pase de 200 líneas. Nuestro Playbook tenía los dos problemas: mucho texto que no era una instrucción y reglas que no coincidían.

El coste era tangible. Una tarea programada que solo leía el documento de entrada redactó respuestas a partir de un resumen que ya no coincidía con las reglas de redacción. Cada ejecución pagaba por leer 100 KB o más de texto que no podía cambiar lo que hacía. Y cuando dos reglas chocaban, el agente elegía una sin decirlo.

La auditoría encontró seis patrones detrás del crecimiento. Seguramente reconozcas alguno en tus propios prompts, en tus archivos CLAUDE.md o en los documentos de tu agente.

1. N.º 01Resúmenes que se desfasan. El documento de entrada resumía los demás: 153 de sus 261 reglas eran copias. Cuando cambiaba un documento de detalle, el resumen no. Ejemplo: el resumen siguió con la versión antigua de una regla de redacción cuando el documento de redacción ya la había cambiado, y una ejecución que solo leía el resumen aplicó la antigua.
2. N.º 02Reglas nuevas que no quitan las viejas. Una corrección se añadía como párrafo nuevo con fecha, «(Thomas, 18 sep 2026)», sin quitar la regla a la que sustituía. Las dos versiones seguían vigentes y el agente tenía que adivinar cuál valía.
3. N.º 03Historial mezclado con reglas. El documento de prospección ocupaba 70 KB y solo una quinta parte eran reglas; el resto eran listas de tandas, investigación y fotos del momento. El de LinkedIn era en un 80% una tabla de invitaciones.
4. N.º 04Historias en lugar de reglas. Tres párrafos sobre por qué hubo que reenviar una presentación, con la lección escondida en medio. La regla cabe en una línea: «Comprueba que la copia que se envía no lleva notas del orador antes de entregarla».
5. N.º 05Datos vivos dentro de las reglas. Las listas de empresas a contactar estaban dentro de las reglas y, tras unas cuantas ediciones, se contradecían: una empresa aparecía a la vez como «descartada» y como «de vuelta en la lista».
6. N.º 06Referencias frágiles. «Ver apartado 4.2» apuntaba a apartados que se habían renumerado o ya no existían. Ahora dice «ver Respuestas, Objeciones»: el nombre de un encabezado sobrevive a una renumeración.

La mitad de esos patrones no se arreglan escribiendo mejor, sino poniendo cada tipo de información en su sitio. Un sistema con agentes tiene cinco piezas, y las instrucciones solo funcionan si las otras cuatro están en su lugar:

La separación que más importa es la de instrucciones y fichas. Las instrucciones dicen cómo trabajar; las fichas dicen qué es verdad en cada caso. Para que un agente actúe por su cuenta, cada tipo de información necesita un único sitio:

Los datos nunca van en los documentos de instrucciones ni en archivos de memoria. La fase de una oportunidad escrita en las reglas estará mal la semana que viene, y un dato guardado en la memoria de un agente es invisible para el resto del equipo. En la ficha, el agente lo encuentra con una herramienta cuando lo necesita. Anthropic lo describe como contexto justo a tiempo: el agente guarda referencias ligeras y carga los datos al ejecutarse. La memoria automática de Claude Code está pensada para aprendizajes y patrones sobre cómo trabajar, que es el uso correcto de la memoria.

La otra mitad es que el agente escriba en las fichas mientras trabaja: registra el correo, mueve la oportunidad, crea la tarea. Así la siguiente ejecución parte de los hechos y no de volver a leer toda la bandeja de entrada. En un equipo pequeño, las fichas pueden ser una hoja de cálculo o un archivo por cliente; la base de datos puede esperar. Lo que importa es que cada dato tenga un único sitio y que el agente lo mantenga al día.

Cada principio responde a uno de los patrones anteriores. Primero la regla corta, después el porqué.

1. 01Empieza por los trabajos, no por el reglamento. Haz una lista de cada trabajo recurrente del agente (una revisión matinal, una respuesta, una propuesta, un informe), qué lo dispara y cuándo está terminado. Después escribe solo lo que el agente no puede saber para cada uno. Por qué: un reglamento escrito por temas lo acumula todo; uno escrito desde los trabajos se queda en lo que el trabajo necesita.
2. 02Un solo sitio para cada regla y cada dato. En cualquier otro sitio, una referencia («ver Precios, Valor de la oportunidad»), nunca una copia. Por qué: una copia es una segunda versión esperando a desfasarse. La mayoría de nuestras 17 contradicciones eran copias que nadie actualizó.
3. 03El documento de entrada dirige; no resume. Solo tres partes: reglas firmes, una tabla de trabajos con los documentos que lee cada uno, y los Datos. Que no pase de unos 10 KB. Por qué: el documento que se carga siempre es el texto más caro y en el que más se confía, y un resumen ahí pisa al detalle sin que nadie se dé cuenta.
4. 04Cada documento empieza con una línea de «leer cuándo». Una línea que dice cuándo leerlo, y que coincide con la tabla de trabajos. Por qué: el agente carga solo las reglas que necesita su trabajo, y ninguna ejecución se salta un documento necesario porque nadie le dijo que lo leyera.
5. 05Divide por el momento del trabajo, no por temas. Por qué: el agente nunca debería necesitar tres documentos para dar un paso.
6. 06Reglas, no historias. Una línea en imperativo, con el agente como sujeto, y un «porque» solo cuando cambia cómo se aplica. Por qué: en una historia, el modelo tiene que adivinar qué frase es la regla.
7. 07Un ejemplo vale más que un párrafo. Una línea buena y, si ayuda, una línea de «No:». Por qué: los modelos copian patrones con más fiabilidad de la que aplican descripciones. En su guía de context engineering, Anthropic dice que los ejemplos son las «imágenes» que valen más que mil palabras.
8. 08No escribas lo que el modelo ya sabe. «Sé educado» o «escribe con claridad» solo añaden longitud. Escribe el criterio, los datos y las decisiones que son tuyos.
9. 09Un cambio sustituye; nunca se añade. Busca la regla que ya existe y cámbiala en la misma edición. Por qué: los párrafos con fecha apilados sobre los antiguos fueron la forma en que acabaron vigentes dos versiones de la misma regla.
10. 10Deja escrita la prioridad. La nuestra: el chat manda sobre las reglas personales, y las personales sobre los documentos del equipo. Si aun así dos documentos chocan, el agente sigue el que pide menos (no enviar, no borrar, preguntar antes) y lo dice. Por qué: sin esa regla, el agente elige en silencio.

Si quieres un agente construido así para tus propias operaciones, es lo que cubre nuestra automatización de procesos con IA.

Cuando un reglamento ya se ha estropeado, editarlo sobre la marcha no lo arregla. Hicimos la reescritura como una cadena de agentes, cada uno con un solo trabajo, para que ningún agente cambiara las reglas y a la vez juzgara sus propios cambios. Anthropic describe la misma idea como una arquitectura de subagentes: agentes centrados en una tarea que devuelven un resumen breve de lo que han hecho. Las decisiones las tomamos nosotros; el trabajo lo hicieron los agentes.

1. Paso 1Foto fija. Guardamos los 11 documentos en su versión del momento, para que todos los agentes trabajaran sobre el mismo texto.
2. Paso 2Auditoría e inventario, en paralelo. Un agente arquitecto midió cada documento (reglas frente a historias, historial y copias), puso nombre a los patrones y diseñó el destino: qué documentos, qué va en cada uno, un tamaño máximo para cada uno y el formato de las reglas. Un agente de inventario leyó cada línea y listó todas las reglas operativas, 918, cada una con su origen, cada sitio donde se repetía (348 aparecían más de una vez) y cada conflicto (17).
3. Paso 3Una especificación por escrito. Una página fijó las decisiones antes de reescribir nada: la lista de documentos, qué documento es dueño de qué reglas, el formato y cómo se resuelve cada conflicto (normalmente gana la regla más reciente). Dos decisiones nos tocaban a nosotros: publicar en vivo con una comprobación de seguridad, y archivar el historial en lugar de borrarlo.
4. Paso 4Un redactor por tema. Cinco agentes escribieron cada uno sus documentos, pasaron el historial palabra por palabra al archivo y rellenaron una tabla de correspondencias con el destino de cada una de sus reglas del inventario: se mantiene, se fusiona, se mueve, se archiva o se elimina, con el motivo.
5. Paso 5Dos comprobaciones independientes. Una comprobación de conservación buscó cada una de las 918 reglas en los documentos nuevos: no faltaba ninguna, y cuatro habían cambiado de sentido y se restauraron. Una comprobación de coherencia leyó los 14 documentos nuevos como un sistema (contradicciones, duplicados, referencias rotas, enrutado, formato), hizo 28 arreglos y listó las preguntas que necesitaban a una persona.
6. Paso 6Decidir lo que queda. Resolvimos las preguntas abiertas que podían llevar a una acción equivocada y ajustamos el tamaño máximo de cada documento a su tamaño real.
7. Paso 7Publicar y releer. Cada documento se subió por el conector del CRM, se volvió a leer y se comparó con el texto local carácter a carácter. Los 14 coincidían.
8. Paso 8Ordenar alrededor. Retiramos el antiguo documento de propuestas, conservando su historial, y las tareas programadas que citaban números de apartado ahora citan nombres de encabezado.

Lo que hace segura la reescritura son el inventario y la tabla de correspondencias. Que «se lea bien» no demuestra nada sobre lo que se ha perdido; una lista de 918 reglas, cada una con su destino, sí.

Un reglamento solo se mantiene corto si algo lo revisa con regularidad. El nuestro tiene ahora cinco costumbres:

• Un tamaño máximo por documento, de 3 KB a 22 KB. Los dos documentos que se leen en cada ejecución no pasan de 17 KB entre los dos. Si una edición se pasa, se fusionan o se ajustan reglas en esa misma edición; nunca se quita una regla para hacer sitio.
• Notas de cambios de diez líneas como mucho al final de cada documento. La undécima manda la más antigua al archivo. Una nota de cambios nunca contiene una regla.
• Una limpieza mensual el primer lunes de cada mes. Informa de contradicciones, reglas escritas dos veces, datos caducados, referencias a encabezados o documentos que ya no existen y documentos que se pasan de tamaño, y no cambia nada sin el responsable.
• Referencias por nombre de encabezado, nunca por número de apartado, en los documentos y en el prompt de cada tarea programada, para que una renumeración no las rompa.
• Una prueba con un agente nuevo. Dale a una sesión nueva solo el documento de entrada y un trabajo para hacer de principio a fin. Cada vez que dude o abra el documento equivocado hay un fallo de enrutado o de redacción.

¿Regla o caso puntual? Casi todas las reglas nuevas salen de correcciones. Un comentario solo se convierte en regla si va a volver a aplicarse:

Antes de escribir una regla, busca el tema y, si ya hay una regla, cámbiala. Decide si es del equipo (esas solo las cambia el responsable del negocio) o personal. Ponla en el documento cuya línea de «leer cuándo» cubre el momento en que hace falta, escríbela corta, quita la que sustituye, añade una nota de cambios y dile a la persona en una línea qué ha cambiado.

Lo que nunca va en las reglas: contraseñas y claves, los detalles de una tarea concreta, resultados de investigación y el estado de las oportunidades (van en las fichas), y cualquier cosa que alguien haya pedido no guardar. Una reescritura completa como la nuestra solo merece la pena cuando las limpiezas mensuales ya no dan abasto.

Esta es la forma de nuestro documento de entrada, sin nuestros datos. Cópiala y rellénala con tus trabajos y tus datos. La misma estructura sirve para un prompt de sistema, un CLAUDE.md o un archivo AGENTS.md.

# Instrucciones
Leer cuándo: siempre, antes de cualquier trabajo.

## Reglas firmes
- No envíes nunca un correo. Déjalo en borrador para que
  lo envíe una persona.
- No borres nunca una ficha. Archívala.
- Todo lo que escribas en el CRM, en inglés.
- Los datos de una empresa, oportunidad o persona van en su
  ficha, nunca en estos documentos.
- Si dos documentos se contradicen, sigue el que pide menos
  (no enviar, no borrar, preguntar) y di cuál has seguido.

## Prioridad
El chat manda sobre las reglas personales; las reglas
personales, sobre los documentos del equipo.

## Trabajos
| Trabajo            | Cuándo              | Leer                             |
| Revisión matinal   | A diario, 08:00     | pipeline                         |
| Responder          | Llega una respuesta | respuestas, redaccion            |
| Preparar llamada   | Se agenda llamada   | llamadas-y-reuniones             |
| Propuesta          | Se pide en el chat  | documentos-cliente, precios      |
| Informe semanal    | Los lunes           | informes                         |
| Cambiar una regla  | Alguien lo pide     | editar-el-playbook               |

## Datos
El único sitio donde se escriben. Los demás documentos
apuntan aquí.
- Equipo: nombres, cargos, identificadores
- Páginas de la web que enlazamos
- Enlace para reservar llamada

## Cambios (diez líneas como mucho)
- 6 oct 2026: reescrito; el historial, al archivo.

Un documento de detalle es aún más corto: una línea de «leer cuándo», las reglas bajo los encabezados donde un agente las buscaría y sus notas de cambios.

# Respuestas
Leer cuándo: llega una respuesta a uno de nuestros correos.

## Categorías
- Ahora no: anótalo en la oportunidad, crea una tarea de
  seguimiento para la fecha que dieron y no respondas
  salvo que lo pidan.

## Objeciones
- Responde a la objeción en dos frases y haz una pregunta.
  Ejemplo: "..."
  No: "..."

## Cambios (diez líneas como mucho)
- 6 oct 2026: traído del antiguo documento de propuestas.

Para que te hagas una idea del tamaño, así quedó nuestro Playbook tras la reescritura. Dos documentos se cargan siempre; el resto, según el trabajo.

• Anthropic: Effective context engineering for AI agents, 29 de septiembre de 2025 (en inglés)
• Chroma: Context Rot, cómo afecta la longitud de la entrada al rendimiento de los LLM, 14 de julio de 2025 (en inglés)
• Documentación de Claude Code: cómo recuerda Claude tu proyecto (CLAUDE.md y memoria automática, en inglés)
• AGENTS.md: un formato abierto para guiar a los agentes de programación (en inglés)
• Model Context Protocol: qué es MCP (en inglés)

Consultadas el 6 de octubre de 2026. Las cifras del Playbook son datos propios de Odysi, de la reescritura de ese mismo día.