hustyladislav/escritura-para-agentes

Referencia para escribir cualquier documento que consuma un agente: una habilidad (skill), un AGENTS.md / CLAUDE.md, un documento al que se accede mediante un puntero. El empaquetado difiere; la escritura no: las mismas palancas hacen que cada uno sea predecible, ya que el agente ejecuta el mismo proceso en cada ejecución en lugar de producir la misma salida.

Cuando el documento que está escribiendo es una habilidad (skill), lea SKILL-MECHANICS.md para conocer el frontmatter, la elección de invocación y las habilidades de enrutamiento (router skills).

Punteros de contexto

Un puntero de contexto es una referencia mantenida en el contexto del agente que nombra algún material fuera del contexto y codifica la condición para acceder a él. La descripción de una habilidad es un ejemplo; una línea en AGENTS.md que nombra un documento es el mismo objeto. La redacción del puntero, no su objetivo, decide cuándo el agente accede al material, y con qué fiabilidad. Un objetivo imprescindible detrás de un puntero débilmente redactado es un error de varianza: primero afine la redacción, y solo si falla, incruste el material en línea.

Un puntero realiza dos trabajos: indicar qué es el material y enumerar las ramas que deberían activar su acceso (una rama es un caso distinto que maneja el documento, por lo que diferentes ejecuciones toman caminos distintos a través de él). Cada palabra de un puntero que se carga siempre tiene un costo en cada turno, por lo que merece una poda incluso más agresiva que el cuerpo:

• Anteponga la palabra clave: el puntero es donde realiza su trabajo de activación.
• Un disparador por rama. Los sinónimos que renombran una sola rama son una rama escrita dos veces; redúzcalos y conserve solo las ramas genuinamente distintas.
• Elimine la identidad que el cuerpo ya contiene.

Las dos cargas

Cada documento y puntero que añade consume uno de dos presupuestos:

• Carga de contexto es el costo del material que se carga siempre en la ventana del agente: una línea de AGENTS.md, una descripción de habilidad, cualquier cosa que esté en el contexto en cada turno, gastando tokens y atención, se active o no.
• Carga cognitiva es el costo para el humano: qué documentos existen y cuándo recurrir a cada uno. El humano es el índice. No es un costo que minimizar: es el precio de la agencia humana; gástelo donde importa el juicio humano, elimínelo donde no.

El material al que solo se accede mediante un puntero escapa de la carga de contexto a costa de la propia línea del puntero; el material sin ningún puntero depende enteramente de la carga cognitiva.

Jerarquía de información

Un documento se compone de dos tipos de contenido: pasos (las acciones ordenadas que realiza el agente) y referencia (definiciones, reglas, hechos consultados bajo demanda). Los dos se mezclan libremente: todos pasos (una receta), toda referencia (las reglas de una revisión, esta habilidad), o ambos. La decisión central es dónde se sitúa cada pieza en la jerarquía de información, una escalera clasificada por la inmediatez con la que el agente necesita el material:

1. Paso en el archivo es el nivel principal: lo que el agente hace, en orden.
2. Referencia en el archivo se consulta bajo demanda. A menudo es un conjunto legítimamente plano de pares (cada regla de una revisión en un mismo escalón), lo cual es una disposición correcta, no un mal olor.
3. Referencia externalizada se empuja a un archivo separado, al que se accede mediante un puntero de contexto, y se carga solo cuando el puntero se activa. Abarca desde un archivo hermano en la misma carpeta hasta referencia completamente externa que puede vivir en cualquier lugar y a la que cualquier documento puede apuntar.

Empujar muy poco hacia abajo infla la parte superior; empujar demasiado oculta material que el agente realmente necesita. Esa tensión es toda la decisión.

Divulgación progresiva es el movimiento hacia abajo en la escalera (fuera del archivo principal y detrás de un puntero) para que la parte superior siga siendo legible. No es principalmente una optimización de tokens: es cómo se protege la jerarquía. La ramificación es la prueba de divulgación más limpia: incruste lo que toda rama necesita, y empuje detrás de un puntero lo que solo algunas ramas alcanzan. Cuando un documento tiene pasos, la referencia en el archivo que debería divulgarse los entierra y convertir atenderlos en un volado: una palanca de varianza, no solo de legibilidad.

Co-ubicación es el complemento dentro del archivo: mientras la escalera decide qué tan abajo se sienta una pieza, la co-ubicación decide qué se sienta a su lado una vez allí. Mantenga la definición de un concepto, sus reglas y advertencias bajo un mismo encabezado en lugar de dispersas, para que leer una parte traiga consigo a sus vecinos. La prueba: el documento debe leerse como documentación escrita para el agente. El material agrupado se lee así; el material disperso, no. (Distinto de la duplicación: esta repite un significado en dos lugares; la dispersión fragmenta un significado en muchos).

El desparrame (sprawl) es el modo de fallo aquí: un documento simplemente demasiado largo, incluso cuando cada línea está viva y es única. La atención se diluye a lo largo del exceso, y cada línea extra es una más que mantener relevante. La cura es la escalera: divulgar referencia detrás de punteros, y dividir por rama o secuencia para que cada ruta lleve solo lo que necesita.

Pasos y criterios de finalización

Cada paso termina con un criterio de finalización, la condición que le dice al agente que el trabajo está hecho. Dos propiedades lo convierten en una palanca:

• Claridad: ¿puede el agente distinguir entre hecho y no hecho? Un límite vago ("comprensión alcanzada") invita a la finalización prematura: terminar el paso antes de que esté realmente terminado, deslizando la atención hacia estar terminado. Los pasos visibles que aún quedan por delante (los pasos posteriores a la finalización) proporcionan el tirón; la claridad del criterio es la resistencia. Defienda en orden: primero afine el límite (local y barato); solo si es irreductiblemente difuso y observa la prisa, oculte los pasos posteriores dividiendo la secuencia. Ocultar solo funciona a través de un límite de contexto real (una transferencia o un envío a un subagente; una llamada en línea deja los pasos posteriores en contexto y no borra nada).
• Exigencia: cuánto requiere. "Cada modelo modificado contabilizado" fuerza un trabajo minucioso donde "produzca una lista de cambios" no lo hace. La exigencia impulsa el trabajo de base (la investigación que el agente realiza dentro del trabajo, latente en la redacción en lugar de escrita como su propio paso), y no está ligada al paso: "cada regla aplicada" vincula un cuerpo de referencia plana igual que "cada paso hecho" vincula una secuencia, que es cómo un documento de solo referencia aún lleva una barra de exhaustividad.

Los criterios más sólidos son verificables y exhaustivos.

Cuándo dividir

Dividir un documento en dos gasta una de las dos cargas, por lo que solo debe dividir cuando el corte lo merezca:

• Por secuencia: divida una serie de pasos donde los pasos posteriores a la finalización tientan al agente a apresurar el paso actual. Mantenerlos fuera de la vista impulsa más trabajo de base en la tarea actual. Cuidado con lo inverso: fusionar secuencias expone los pasos posteriores de cada paso a lo que sigue, invitando a la finalización prematura.
• Por invocación, específico de habilidades: consulte SKILL-MECHANICS.md.

Palabras clave (leading words)

Una palabra clave es un concepto compacto que ya vive en el preentrenamiento del modelo y con el que el agente piensa mientras ejecuta el documento (lección, niebla de guerra, balas trazadoras). Repetida como un token, nunca como una oración, acumula una definición distribuida y ancla una región completa de comportamiento en la menor cantidad de tokens, al reclutar conocimientos previos que el modelo ya posee. Acuñar la suya propia funciona si la define claramente, pero una palabra inventada no recluta conocimientos previos: paga en tokens de definición lo que una palabra preentrenada da gratis; recurra primero a una palabra existente.

Ancla dos veces. En el cuerpo, ejecución: el agente alcanza el mismo comportamiento cada vez que aparece la palabra, y dentro de la referencia plana enfoca la atención en una clase de cosa a buscar. En un puntero, invocación: cuando la misma palabra vive en sus indicaciones (prompts), sus documentos y su código base, el agente vincula ese lenguaje compartido al material y lo alcanza de manera más confiable.

Busque oportunidades para refactorizar con palabras clave. Una tríada escrita en tres sitios, un puntero que gasta una oración para señalar una idea. Cada una es un pasaje que pide colapsarse en un solo token:

• "rápido, determinista, bajo overhead" → ajustado (un bucle ajustado).
• "un bucle en el que crees" → rojo, convirtiendo una compuerta difusa en un estado binario observable (el bucle se pone rojo en el error, o no).

Gana dos veces: menos tokens, y un gancho más afilado para que el agente cuelgue su pensamiento. Asuma que cada documento lleva reiteraciones que las palabras clave retiran. Vaya a encontrarlas.

La negación es el modo de fallo junto a esta palanca: dirigir mediante prohibición arrastra el comportamiento prohibido al contexto y lo hace más disponible, no menos. No piense en un elefante, y el elefante es todo lo que hay; la negación es un modificador débil que el concepto fuertemente activado desborda, por lo que la prohibición se lee a medias como una instrucción para hacer lo prohibido. Indique lo positivo: establezca el comportamiento objetivo ("escriba comentarios de una línea") para que el prohibido nunca se mencione. Una prohibición merece su lugar solo como una barrera de protección dura que no puede redactar en positivo; incluso entonces, acompáñela con el objetivo positivo para que la atención se centre en qué hacer.

Poda

• Mantenga cada significado en una única fuente de verdad: un lugar autorizado, de modo que cambiar el comportamiento sea una edición en un solo lugar. La duplicación (el mismo significado en más de un lugar) cuesta mantenimiento y tokens, e infla la prominencia de un significado en la escalera más allá de su rango real. (El inverso accidental de una palabra clave, que repite un token a propósito, nunca el significado).
• El entorno también es una fuente de verdad (scripts de package.json, archivos de configuración, la estructura de directorios, la salida de --help), y un documento que lo reitera es una caché: una copia de una búsqueda, que gana su carga solo cuando la búsqueda es costosa. Almacene en caché lo que el agente no puede encontrar mirando: la convención no escrita, la razón detrás de una elección, el detalle que ningún archivo de configuración confiesa. Deje las búsquedas de un archivo y un comando al entorno, donde no pueden quedar obsoletas.
• Verifique cada línea por relevancia: ¿sigue siendo pertinente para lo que hace el documento? Una línea pierde relevancia por nunca ser pertinente a la tarea (mera exposición, o una rama que debería divulgarse) o por quedar obsoleta a medida que cambia el comportamiento o el mundo que describe. Los documentos más cortos son más fáciles de mantener relevantes. Sin una disciplina de poda, el destino predeterminado es el sedimento: capas obsoletas que se asientan porque añadir se siente seguro y eliminar se siente arriesgado, hasta que debe perforar a través de ellas para encontrar lo que aún está vivo.
• Busque no-operaciones (no-ops) oración por oración: una instrucción que el modelo ya obedece por defecto paga carga para no decir nada. La prueba (¿cambia el comportamiento en comparación con el valor predeterminado?) depende del modelo, no del lector: dos personas que no están de acuerdo sobre una no-operación no están de acuerdo sobre el valor predeterminado, y lo resuelven ejecutando el documento, no debatiendo. Cuando una oración falla, elimine la oración completa en lugar de recortar palabras de ella. La prueba también califica las palabras clave: una palabra demasiado débil para superar el valor predeterminado (sea minucioso cuando el agente ya es más o menos minucioso) es una no-operación, y la solución es una palabra más fuerte (implacable), no una técnica diferente.