Mantener accesibles las instrucciones permanentes
Los agentes de programación necesitan más que una especificación de funcionalidad. Necesitan saber cómo espera el proyecto que trabajen y qué decisiones aprobadas deben respetar. Esas expectativas pueden referirse a prácticas de ingeniería, tecnología aprobada, arquitectura, reutilización de componentes, objetivos de producto, documentación, accesibilidad u otras restricciones específicas de la aplicación.
El marco SHAPE recomienda reunir los documentos Markdown de instrucciones permanentes y contexto en agent_instructions/. Este directorio es extensible. Los proyectos pueden crear tantos archivos Markdown de alcance apropiado como necesiten, con nombres descriptivos; el marco no exige una lista fija de nombres de archivo.
Un punto de entrada mínimo
Un archivo AGENTS.md en la raíz proporciona un punto de entrada fácil de descubrir para los agentes de programación. Su instrucción esencial es:
Lea y respete todos los archivos Markdown (
.md) deagent_instructions/antes de comenzar el trabajo y durante toda la implementación.
Este archivo raíz no necesita enumerar todos los archivos. Añadir un documento de instrucciones no debería exigir mantener una segunda lista en el punto de entrada.
Dejar que cada archivo se explique por sí mismo
Todo archivo Markdown situado en agent_instructions/ debe comenzar con una línea o un encabezado que declare el propósito del documento. Por ejemplo, una organización podría proporcionar un archivo que defina las tecnologías aprobadas, un documento de arquitectura del proyecto, una guía del sistema de diseño o una declaración de objetivos empresariales. Son ejemplos, no nombres obligatorios ni una jerarquía prescrita.
Un archivo que explica su propio propósito facilita que tanto las personas como los agentes determinen qué reglas contiene y reduce la probabilidad de que un documento nuevo se ignore simplemente porque su nombre no se añadió a un índice central.
Distinguir instrucciones de especificaciones
Las instrucciones permanentes describen cómo debe trabajar el agente y qué restricciones duraderas se aplican. Las especificaciones de funcionalidades describen el comportamiento que debe ofrecer la aplicación. Por tanto, las especificaciones de funcionalidades pertenecen al área specs/ separada, y no deben mezclarse con agent_instructions/ solo porque ambas utilicen Markdown.
Autoridad, cambios y conflictos
Las organizaciones deben decidir quién puede aprobar cambios en las instrucciones controladas y los estándares compartidos. Un agente no debe reescribir silenciosamente las reglas que gobiernan su trabajo ni atribuirse autoridad para anularlas. Cuando los documentos entren en conflicto de forma importante, el Product Engineer y el responsable correspondiente deben resolverlo en lugar de permitir que el agente elija la instrucción más fácil.
Los archivos de instrucciones deben ser lo bastante concisos para seguir siendo utilizables, coherentes entre sí y sincronizados con las decisiones aprobadas. Los proyectos pueden añadir restricciones específicas del dominio sin alterar la convención de descubrimiento.
Lo que estos archivos no hacen
Las instrucciones pueden indicar a un agente que no obtenga secretos ni utilice servicios no autorizados, pero no pueden impedir acciones no autorizadas si el entorno de ejecución concede esas capacidades. Los permisos y las restricciones de acceso deben estar en controles aplicados técnicamente.