Preparar un proyecto para agentes

Esta guía explica cómo preparar un proyecto empresarial para trabajar con agentes de programación a partir de especificaciones. La preparación forma parte del Ciclo 1, etapa 2, en paralelo con la orientación de UX y la generación inicial de especificaciones de funcionalidades. El Product Engineer, el arquitecto y los responsables pertinentes de plataforma o seguridad colaboran según la materia y el riesgo.

El objetivo es proporcionar un punto de partida técnicamente sólido y accesible, evitando una ceremonia obligatoria y pesada de aprobación previa. Las aprobaciones empresariales existentes siguen aplicándose cuando una dependencia, integración, capacidad de seguridad o excepción arquitectónica las requiera.

Roles responsables: Product Engineer y Arquitecto / Ingeniero sénior; responsables empresariales de plataforma y seguridad según sea necesario. El arquitecto dirige las decisiones arquitectónicas; el Product Engineer se responsabiliza del trabajo continuo sobre el producto y de la coordinación de agentes.

Entradas: Objetivos del producto, especificaciones preliminares, estándares técnicos y de seguridad empresariales, recursos reutilizables aprobados, orientación pertinente del sistema de diseño y dependencias empresariales/técnicas identificadas.

Salidas: Un proyecto con estructura técnica e instrucciones iniciales suficientes, decisiones técnicas aprobadas, especificaciones accesibles y un entorno de ejecución de agentes de programación limitado por permisos adecuados.

1. Confirmar los límites iniciales del producto. Revisar objetivos, flujos principales, condiciones preliminares de aceptación, restricciones conocidas y decisiones importantes pendientes. Identificar cuestiones técnicas que puedan afectar materialmente a la implementación. Plantear las preguntas de política empresarial a sus responsables; no convertir conjeturas técnicas en decisiones del negocio.

2. Elegir capacidades empresariales aprobadas. Identificar qué tecnologías, proyectos iniciales, servicios compartidos, componentes existentes y bibliotecas aprobadas se ajustan al producto. Preferir recursos adecuados de la organización antes que crear implementaciones redundantes. Una dependencia nueva o una desviación arquitectónica sigue el proceso establecido de excepciones.

3. Establecer suficiente arquitectura para la próxima iteración. Definir los límites pertinentes de sistemas, responsabilidades de datos e integración, separación de componentes y convenciones de repositorio. Documentar las decisiones que necesita el agente para implementar el alcance inicial de forma coherente. Evitar diseños exhaustivos previos de detalles que puedan perfeccionarse con seguridad durante la implementación.

4. Preparar instrucciones y contexto fáciles de encontrar. Mantener mínimo el archivo raíz AGENTS.md y hacer que dirija a los agentes a todos los documentos Markdown de agent_instructions/. Cada archivo de ese directorio explica su propósito en la primera línea. Confirmar que las instrucciones sean coherentes, actuales, no contradictorias y compatibles con los estándares aprobados. Los nombres y el número de documentos siguen siendo decisiones del proyecto.

5. Mantener el comportamiento del producto en especificaciones. Mantener el comportamiento acordado en el área separada specs/. Las instrucciones permanentes establecen cómo trabajar y qué restricciones duraderas se aplican; las especificaciones describen lo que debe hacer el producto. No duplicar requisitos de funcionalidades en reglas permanentes de programación ni introducir un artefacto obligatorio adicional con nombre específico de SHAPE.

6. Establecer límites técnicos para los agentes. Garantizar que los responsables autorizados configuren el acceso a repositorios, sistemas, secretos, herramientas y redes. Las instrucciones escritas pueden guiar el comportamiento, pero no aplican permisos. El acceso debe corresponder a las necesidades mínimas adecuadas de la tarea.

7. Iniciar la implementación y perfeccionar con responsabilidad. Confirmar que el agente encuentre instrucciones y especificaciones pertinentes, use recursos aprobados y opere en el entorno autorizado. El Product Engineer inicia la implementación cuando se satisfacen los requisitos previos importantes. Consultar al arquitecto ante cuestiones, excepciones o riesgos importantes. La preparación técnica puede evolucionar con lo aprendido sin convertirse en una aprobación permanente adicional.

El alcance inicial se comprende suficientemente para un incremento; las decisiones arquitectónicas pertinentes siguen los estándares empresariales aprobados; las especificaciones son accesibles; las instrucciones permanentes del agente son fáciles de encontrar y coherentes; se aplican los controles técnicos necesarios; y el Product Engineer puede dirigir una implementación productiva sabiendo qué decisiones pendientes debe escalar.

No se requiere un certificado adicional de revisión de preparación arquitectónica de SHAPE, una auditoría fija de seis partes, un documento arquitectónico extenso, una lista obligatoria de nombres de instrucciones ni una ceremonia de entrega.

Permitir que un agente invente una excepción empresarial o arquitectónica; usar instrucciones escritas en lugar de controles técnicos de acceso; duplicar especificaciones en reglas permanentes de programación; exigir un diseño exhaustivo previo; introducir bibliotecas innecesarias; y convertir cada incremento en una solicitud de aprobación al arquitecto.