Cuando un proyecto empieza a acumular reglas para el agente (cómo se hacen los tests, qué tablero de Jira usar, qué puertos se ocupan), la tentación es meterlo todo en el archivo principal de instrucciones. Funciona al principio, pero tiene un coste que no se ve: ese archivo viaja en cada conversación.
Qué se carga siempre y qué no
El archivo principal de instrucciones del proyecto entra en el contexto del agente al empezar cada sesión, tengas o no una tarea que lo necesite. Si ahí describes cómo hacer TDD, el agente lo carga aunque esa tarde solo estés analizando métricas o revisando una base de datos. Cada línea de ese archivo se paga, en tokens y en atención del modelo, en todas las conversaciones.
Hay otros sitios donde puede vivir la información, con otro comportamiento: los comandos solo se cargan cuando los invocas, las skills se cargan bajo demanda y las reglas específicas pueden acotarse a determinadas tareas o tipos de archivo, según la herramienta y su versión. Conviene comprobar en tu herramienta cómo se carga cada una.
La referencia con @ no ahorra tokens
Es común pensar que dividir el archivo en varios y referenciarlos con `@` reduce el consumo. Reduce el desorden, no el contexto: lo referenciado se carga igualmente junto con el archivo principal. Es una aplicación del principio DRY, útil para mantener cada decisión en un único sitio, pero no es una optimización de tokens. Si el objetivo es ahorrar, lo que hay que hacer es sacar de ahí lo que no se necesita siempre.
Un criterio sencillo
Pregúntate si la información hace falta en todas las conversaciones. La arquitectura del proyecto, las reglas que no se negocian y los comandos para levantar el entorno suelen ser universales: van en el archivo principal. El tablero de tickets solo hace falta cuando se trabajan tickets; el ritual de TDD, cuando se desarrolla o se refactoriza. Esos pueden vivir en un comando, en una skill o en una regla acotada.
Un ejemplo: si la configuración de tu tablero está en una regla propia y no en el archivo principal, solo se lee cuando trabajas con tickets. Y si tu trabajo es siempre desarrollo, ponerla en el archivo principal tampoco es un error grave.
Cuánto afinar
Optimizar el contexto es un trabajo en sí mismo: medir qué ocupa cada pieza, decidir qué modelo y qué nivel de esfuerzo usar en cada comando, y repartir las reglas. Compensa cuanto más uso haga el equipo del agente, pero no hay un diseño perfecto. Empieza por lo que más gasta y menos cuesta automatizar, y no intentes afinarlo todo a la vez.
Resumen rápido
El archivo principal se carga siempre. Referenciar con `@` ordena pero no ahorra. Mueve a comandos, skills o reglas acotadas lo que solo hace falta en algunas tareas, y afina poco a poco.