Un mínimo conceptual, no el árbol del sitio
Este es el ejemplo conceptual mínimo, no una afirmación sobre el sitio real.
project/
├── AGENTS.md
├── agent_instructions/
│ ├── [project-defined].md
│ └── [other-project-defined].md
├── specifications/
│ └── [project-defined specification documents]
└── ...
La entrada raíz descubre instrucciones Markdown permanentes. Nombres, cantidad, directorios fuente, herramientas y granularidad son decisiones del proyecto. El ciclo de especificaciones usa los tres directorios siguientes. Un único archivo maestro mantenido por el agente sigue siendo una opción exploratoria, no una obligación.
Ciclo de especificaciones: specifications/requests/ contiene solicitudes humanas pendientes; specifications/archive/ conserva solicitudes humanas implementadas como registros históricos; specifications/current/ contiene descripciones mantenidas por el agente del comportamiento actualmente requerido. Archivar las solicitudes implementadas sin reescribir su contenido histórico y actualizar las especificaciones vigentes. Los mensajes y conversaciones pueden autorizar desarrollo sin archivo formal; mantener el registro vigente con independencia del formato de solicitud.
Gestionar las especificaciones
SHAPE separa las solicitudes de cambio redactadas por personas de las especificaciones del estado actual mantenidas por agentes. Las solicitudes formales pueden esperar hasta que se autorice su implementación. Las solicitudes implementadas se archivan, mientras que las especificaciones del estado actual reflejan continuamente la funcionalidad requerida del producto.
specifications/requests/— Solicitudes humanas pendientes de implementación.specifications/archive/— Solicitudes humanas implementadas que se conservan para la trazabilidad.specifications/current/— Especificaciones de la funcionalidad requerida actual, organizadas lógicamente y mantenidas por agentes.
Las instrucciones conversacionales no necesitan guardarse en requests/ antes de
implementarse: pueden dirigir al agente de inmediato. El paso ilustrado por requests/ es
opcional para las conversaciones. Consulte Especificaciones
para conocer su mantenimiento.
La instrucción mínima de descubrimiento
# AGENTS.md
Read and observe all Markdown (`.md`) files in `agent_instructions/` before starting work and throughout implementation.
La entrada dirige a todos los archivos Markdown sin enumerarlos. Cada archivo declara su propósito al principio. STACK.md, DESIGN.md, ARCHITECTURE.md, LIBRARIES.md y OBJECTIVES.md son ejemplos, no obligaciones. La entrada real del sitio es más extensa; véase el recorrido real.
Qué pertenece a cada lugar y quién decide
| Categoría | Contenido y exclusiones | Decisiones y trabajo del agente | Motivo y alcance |
|---|---|---|---|
AGENTS.md raíz | Entrada de descubrimiento; no catálogo detallado universal | Su responsable controla cambios; los agentes leen | Contexto permanente localizable |
agent_instructions/ | Reglas/contexto permanentes autodescriptivos; no comportamiento de funcionalidades | Responsables por materia gobiernan estándares; agentes leen y cambian solo con autoridad | Separación sin nombres obligatorios |
| Conocimiento del producto | Intención, flujos, permisos, excepciones, resultados; no mera observación del código | Personas deciden intención importante; agentes la mantienen al implementar | Continuidad y comprobación independiente con agrupación flexible |
| Implementación/pruebas | Producto y comprobaciones ordinarias; no autoridad para inventar políticas | PE dirige implementación aprobada; otro contexto verifica intención | Arquitectura y herramientas elegidas por proyecto |
| Recursos empresariales | Plataformas, bibliotecas, UI/diseño, identidad e integración; no copias innecesarias | Responsables empresariales autorizados gobiernan cambios y acceso | Reutilización y restricciones también fuera del repositorio |
La prosa no crea autoridad
Un agente no obtiene derechos por escribir que los tiene. Las directivas protegidas del marco o empresa requieren decisiones de sus responsables autorizados; el contexto del proyecto evoluciona dentro de su alcance concedido. Mantener intención difiere de cambiar reglas de ingeniería que la limitan. Si se desconoce precedencia o propiedad, confirmar con el responsable del repositorio, sin inventar una jerarquía universal. Markdown orienta; permisos, revisiones y controles aplican límites. Véanse gobierno de instrucciones y límites de ejecución.