Los archivos de instrucciones dirigidos a agentes de programación basados en inteligencia artificial necesitan una revisión continua, no una expansión sin fin. Cada vez que el modelo comete un error se añade una regla; cada vez que cambia una herramienta se agrega una solución alternativa, mientras las instrucciones de modelos anteriores permanecen después de la aparición de modelos más nuevos. El resultado puede ser un archivo que combine una guía de configuración para desarrolladores, una guía de estilo, un registro de resolución de problemas y un conjunto de antiguas técnicas de redacción de prompts.
Según el artículo, esta acumulación puede hacer que el agente de programación sea menos eficaz. Los modelos modernos son cada vez más capaces de explorar repositorios, reconocer marcos de trabajo comunes, seguir los patrones existentes y gestionar errores habituales. Sin embargo, no conocen las decisiones específicas del equipo, las restricciones ocultas ni la experiencia operativa acumulada en su interior. Por eso, el objetivo no es hacer que el archivo de instrucciones sea lo más corto posible, sino conservar el conjunto mínimo de información de alta señal que realmente cambia el resultado.
Trata el contexto como un recurso limitado
El archivo de instrucciones se añade al contexto disponible para el modelo en cada solicitud a la que se aplica, y sus líneas compiten por la atención del modelo con la tarea del desarrollador, el código relevante, las salidas de las herramientas, el historial de la conversación y otras instrucciones. Que la ventana de contexto sea amplia no significa que cada símbolo adicional carezca de coste.
La pregunta práctica no es: ¿qué se le puede contar al modelo sobre el repositorio? Sino: ¿qué necesita saber el modelo y no puede descubrir, inferir o recuperar de forma fiable? El artículo recomienda centrarse en información específica, influyente y difícil de inferir.
¿Qué debería permanecer en el archivo?
La información de mayor valor incluye hechos no evidentes sobre el sistema, como los límites de propiedad entre componentes del repositorio, que una carpeta antigua siga utilizándose en producción o que determinados archivos sean generados y no deban modificarse manualmente. Es útil aclarar que una interfaz concreta es propietaria del contrato HTTP público, o que las reglas de negocio pertenecen a una capa determinada, en lugar de dejar que el modelo infiera esos límites a partir de los nombres de las carpetas.
También debería documentarse la ruta fiable más corta para compilar y verificar, limitándose a los comandos que se hayan probado. Entre los ejemplos del artículo se encuentran ejecutar dotnet restore App.slnx antes de la primera compilación, después utilizar dotnet build App.slnx --no-restore, ejecutar pruebas específicas al cambiar las interfaces de programación o la herramienta de verificación de archivos generados después de modificar los contratos. Deben aclararse los requisitos especiales, como que las pruebas de integración necesitan Docker y no deben ejecutarse en paralelo, porque un comando incorrecto que se repite con confianza es peor que la ausencia del comando.
También es útil registrar las decisiones locales que el código no puede resolver de manera coherente: el marco de pruebas adoptado, la preferencia por Minimal APIs frente a los controladores, el patrón Result<T> para gestionar errores de dominio esperados o el uso de TimeProvider en lugar de invocar directamente el reloj del sistema. No son reglas generales de programación, sino decisiones específicas de la base de código y, por tanto, son adecuadas para el archivo de instrucciones.
En cuanto a las restricciones estrictas, conviene reservar palabras como «siempre», «nunca» y «debe» para las reglas que realmente sean absolutas, como preservar el contrato JSON público, no incluir datos de clientes en los registros, hacer que las migraciones de la base de datos sean compatibles con la versión anterior o impedir la modificación de archivos del entorno de producción sin una tarea de despliegue explícita. También se pueden señalar las fuentes de verdad en lugar de copiar su contenido, como los archivos de directrices de diseño de interfaces, los archivos de especificación de versiones del entorno de ejecución, la documentación de despliegue y las decisiones de arquitectura.
¿Qué se puede eliminar o trasladar?
El artículo recomienda eliminar consejos generales como escribir código limpio, seguir las mejores prácticas, utilizar nombres significativos y gestionar adecuadamente los errores. Estas frases no resuelven una decisión práctica, mientras que una regla local específica resulta más útil; por ejemplo, asociar los errores de validación con la respuesta 400, los recursos inexistentes con la respuesta 404 y los conflictos de concurrencia con la respuesta 409 mediante las herramientas ProblemDetails existentes.
Por lo general, los archivos no necesitan un inventario completo de las carpetas, porque el modelo puede leer rápidamente la estructura del repositorio. Tampoco es necesario repetir las reglas de formato que imponen las herramientas; basta con mencionar el comando de verificación adecuado, como dotnet format --verify-no-changes. Debe evitarse copiar por completo el README, las guías de arquitectura y las guías de contribución, para que no aumente el coste de mantenimiento ni aparezcan contradicciones entre documentos.
El artículo también advierte sobre los antiguos «mitos de los prompts», como pedir al modelo que respire profundamente, que actúe como un ingeniero sénior o que lea cada archivo antes de realizar cualquier cambio. Estas frases no aportan conocimiento sobre el proyecto y pueden provocar una exploración innecesaria. Es mejor describir el resultado, las restricciones y la verificación requerida: realizar el cambio más pequeño que aborde la causa raíz, conservar el comportamiento público y ejecutar las pruebas específicas.
Las soluciones temporales deben eliminarse después de corregir el problema que las motivó. De lo contrario, el agente seguirá evitando una ruta que ya no está rota. Las instrucciones también deberían redactarse para una categoría de modelos, no para una versión concreta; las instrucciones que se dividen en rutas específicas para cada modelo se vuelven frágiles a medida que cambian los modelos y su comportamiento.
Elegir el ámbito de las instrucciones y revisarlas
No toda directriz es adecuada para el archivo general del repositorio. GitHub Copilot admite instrucciones generales en .github/copilot-instructions.md, archivos específicos de rutas en .github/instructions/ e instrucciones para agentes como AGENTS.md. Cuando existen ambos, el archivo de instrucciones general se utiliza junto con el archivo específico de la ruta coincidente.
La arquitectura del sistema, los comandos compartidos y las restricciones generales deben colocarse en el ámbito general, mientras que las reglas de los marcos de trabajo, los patrones de pruebas y los archivos generados específicos de una parte concreta deben trasladarse a un archivo de ruta. Las explicaciones detalladas, el historial de decisiones y los procedimientos poco frecuentes deberían conservarse en documentación vinculada. Así, una regla relativa a las pruebas de componentes de React no consume la atención del modelo durante una tarea relacionada con la migración de una base de datos.
El artículo propone revisar cada directriz según cuatro resultados: conservarla si es correcta, influyente y difícil de inferir; eliminarla si el modelo la conoce, una herramienta la impone o se ha vuelto ambigua u obsoleta; trasladarla si es útil pero corresponde a otra ruta u otro documento; y verificarla si se refiere a un comando, una solución temporal o una versión que puede haber cambiado.
Los momentos adecuados para revisar incluyen adoptar un modelo más capaz, cambiar el sistema de compilación, reorganizar el repositorio u observar que los agentes ignoran las instrucciones o las aplican de forma incorrecta. Después se prueba el archivo más pequeño en una tarea concreta, se registran los fallos reales, se añaden las mínimas instrucciones que eviten que se repitan y se vuelve a probar en otra tarea.
Parte del mantenimiento del proyecto
El artículo propone revisar los cambios en los archivos de instrucciones dentro de las solicitudes de extracción habituales, preguntar a los revisores si la regla es reutilizable o si solo resuelve una tarea concreta, y asignar un responsable para los comandos operativos y los requisitos del entorno. También deben eliminarse las soluciones temporales en la misma solicitud de extracción que aborda la causa del problema, y los comandos deben volver a comprobarse después de actualizar los paquetes del SDK, los marcos de trabajo, las herramientas de pruebas o la ruta de compilación.
No se debe medir la calidad del archivo por el número de líneas. Un archivo de 30 líneas que contenga instrucciones erróneas puede ser peor que uno de 100 líneas que describa los límites de un repositorio multiproyecto y proporcione información que el modelo no pueda inferir. El mejor criterio es que el archivo permita a un modelo capaz comenzar a trabajar rápidamente, proporcionándole lo que solo el equipo conoce: qué es el sistema, cuáles son los límites importantes, las decisiones locales, cómo construirlo y verificarlo, qué no debe romperse y dónde encontrar los detalles más profundos.