Proyecto de referencia: Solicitudes internas de servicio

Este proyecto de referencia es ficticio. Demuestra el marco SHAPE mediante una aplicación interna para enviar y revisar solicitudes de servicio. El escenario es deliberadamente lo bastante pequeño para que siga siendo visible la relación entre la intención empresarial, las especificaciones, la implementación y la verificación.

El ejemplo no prescribe tecnologías empresariales, diseño de UI, arquitectura de base de datos ni modelo de despliegue. Los proyectos reales deben seguir sus propios estándares aprobados.

Actualmente, los empleados envían solicitudes internas de servicio mediante mensajes inconsistentes. El equipo receptor tiene dificultades para determinar quién es responsable de una solicitud, si la información está completa y si se ha comunicado una decisión. La organización quiere un flujo básico en el que puedan enviarse solicitudes y ser aprobadas o rechazadas explícitamente por revisores autorizados.

La primera versión debe hacer comprensible el estado de una solicitud para su solicitante y para el revisor asignado. No intenta automatizar el cumplimiento de las solicitudes, los acuerdos de nivel de servicio, las compras ni la infraestructura de notificaciones de producción.

Objetivo: Proporcionar un único recorrido trazable para enviar y decidir solicitudes internas de servicio.

Usuarios previstos: Empleados como solicitantes; personal designado como revisores; un rol administrativo responsable de mantener las asignaciones de revisores, si corresponde.

Dentro del alcance: Crear y enviar solicitudes, validar la información obligatoria, mostrar el estado de las solicitudes, revisar las solicitudes enviadas, aprobar o rechazar con decisiones registradas, restringir acciones según los roles y permitir que un solicitante consulte el resultado.

Fuera del alcance: Cumplimiento de solicitudes aprobadas, compromisos financieros, optimización automática de asignaciones, acceso de clientes externos, paneles de análisis y procedimientos de publicación en producción.

Estados empresariales iniciales: Borrador, Enviada, Aprobada, Rechazada. Sus significados y las transiciones permitidas se mantienen en la especificación de funcionalidad.

El Product Engineer entrevista a varios solicitantes y revisores. Los solicitantes quieren confirmación de que su envío existe y un resultado claro. Los revisores necesitan información completa y un registro fiable de la decisión. El Product Engineer identifica preguntas sin resolver: ¿Quién puede revisar solicitudes? ¿Pueden los revisores decidir sobre sus propios envíos? ¿Es obligatorio indicar un motivo de rechazo? ¿Quién puede editar una solicitud enviada?

El responsable del negocio confirma las decisiones para la primera versión: los revisores son asignados por un rol aprobado; los solicitantes no pueden revisar sus propios envíos; el rechazo requiere un motivo; y las solicitudes enviadas no pueden editarse en esta primera versión. Estas decisiones se convierten en contenido de la especificación en lugar de ser suposiciones discrecionales del agente de programación.

Orientación de UX: El diseñador define los recorridos principales de usuario: crear y enviar una solicitud; consultar su estado; revisar y decidir una solicitud enviada. Se apoya en patrones de interacción aprobados y prevé inspeccionar los flujos en funcionamiento más adelante.

Fundamentos técnicos: El arquitecto evalúa la plataforma aprobada por la organización, los repositorios iniciales, las bibliotecas, los componentes y el modelo de permisos. Define los límites, los flujos de datos, las integraciones, la separación de responsabilidades y la estructura del repositorio, y coordina las restricciones aplicadas de ejecución de los agentes con los responsables de los entornos. La orientación específica del proyecto está disponible mediante agent_instructions/ y un AGENTS.md mínimo en la raíz.

Trabajo de especificación: El Product Engineer produce la siguiente especificación ilustrativa de funcionalidad.

ID: SPEC-001
Título: Enviar y revisar una solicitud interna de servicio
Propósito: Permitir a un empleado enviar una solicitud de servicio y recibir una decisión trazable de un revisor autorizado.

Actores: Solicitante; Revisor.

Comportamiento:

1. Un solicitante puede crear una solicitud en Borrador con título, categoría y descripción.
2. Una solicitud solo puede pasar de Borrador a Enviada cuando los tres campos están presentes y son válidos según las reglas de campos acordadas.
3. El solicitante puede ver el estado actual de las solicitudes que ha creado.
4. Un revisor puede ver solicitudes Enviadas asignadas a su ámbito de revisión.
5. Un revisor autorizado puede aprobar una solicitud Enviada, registrando su identidad y el momento de la decisión.
6. Un revisor autorizado puede rechazar una solicitud Enviada solo después de proporcionar un motivo de rechazo no vacío; el resultado registra al revisor y el momento de la decisión.
7. Los solicitantes no pueden aprobar ni rechazar sus propios envíos, aunque dispongan de permisos de revisión para otros casos.
8. Una vez Enviada, una solicitud no puede editarse en la versión inicial.
9. Un solicitante puede ver la decisión y el motivo de rechazo, cuando corresponda, de su propia solicitud.

Condiciones de aceptación:

• AC-01 No puede enviarse una solicitud en Borrador si faltan el título, la categoría o la descripción.
• AC-02 El envío correcto cambia la solicitud a Enviada y hace visible su estado para el solicitante.
• AC-03 Solo un revisor autorizado puede aprobar o rechazar una solicitud Enviada asignada.
• AC-04 Un revisor no puede aprobar ni rechazar su propia solicitud.
• AC-05 Se impide rechazar sin motivo; un rechazo válido registra el motivo, el revisor y el momento de la decisión.
• AC-06 Una solicitud Enviada no puede editarse.
• AC-07 Un solicitante puede ver la decisión sobre su propia solicitud, pero no los datos privados de otro solicitante salvo autorización separada.

Dependencias y preguntas sin resolver: La política de asignación de revisores se define mediante el modelo de acceso de la organización. Cualquier notificación adicional a la consulta del estado de la solicitud queda fuera del alcance de la versión inicial.

Este fragmento establece un comportamiento observable, pero un proyecto real también debe definir las restricciones de campos, políticas de tratamiento de datos e integraciones necesarias conforme a su arquitectura aprobada.

Durante el trabajo paralelo de fundamentos, el arquitecto examina las implicaciones técnicas importantes de los requisitos emergentes, elige recursos empresariales aprobados, aclara límites de sistemas y coordina permisos de ejecución apropiados con los responsables pertinentes. El Product Engineer mantiene las especificaciones iniciales y garantiza que el agente de programación encuentre las instrucciones del proyecto. El diseñador de UX establece la orientación esencial de interacción.

Estas actividades producen suficiente contexto compartido y preparación técnica para comenzar una implementación significativa. Las excepciones importantes siguen las políticas empresariales existentes. El marco SHAPE no exige una revisión formal adicional de preparación arquitectónica antes de la etapa 3; las dos revisiones planificadas de software implementado por el arquitecto ocurren en las etapas 4 y 7.

El Product Engineer pide al agente de programación que implemente SPEC-001 con las instrucciones, bibliotecas y patrones aprobados del proyecto. Ejercita casos representativos de creación de borradores, envío y flujos normales de aprobación y rechazo, confirma que el flujo central funciona e identifica correcciones habituales para el agente.

La implementación inicial parece lista para la revisión del arquitecto, pero el Product Engineer no ha probado el rechazo con un motivo vacío. Esa vía negativa sigue siendo defectuosa: la aplicación permite rechazar una solicitud sin motivo, en contra de AC-05. La omisión no se considera comportamiento aceptable ni se utiliza para cambiar la especificación.

El arquitecto comprueba la implementación antes de una revisión extensa de las partes interesadas. La revisión identifica un problema importante: la autorización del revisor solo se comprueba en la interfaz de usuario. Esto es insuficiente porque ocultar un control no aplica permisos sobre la acción subyacente. El Product Engineer dirige la corrección utilizando el enfoque de autorización aprobado de la empresa. El arquitecto confirma que la acción pertinente está protegida antes de continuar con la revisión del cliente.

Los solicitantes y revisores ejercitan los flujos principales. Un revisor pide añadir un comentario al aprobar una solicitud. El responsable del negocio decide que los comentarios de aprobación son útiles, pero opcionales. El Product Engineer actualiza SPEC-001 y sus condiciones de aceptación y, después, indica al agente de programación que implemente el cambio acordado. La especificación actualizada, y no solo la conversación durante la demostración, se convierte en el registro duradero.

Un agente o contexto de verificación separado lee la especificación actual registrada, incluidas las condiciones de aceptación añadidas o refinadas durante la revisión de las partes interesadas. Deriva de forma independiente comprobaciones positivas y negativas representativas y ejercita el comportamiento disponible. Como las pruebas se basan en la especificación y no en decisiones anteriores del agente de implementación, el verificador ejercita el caso de rechazo sin motivo que no cubrieron las comprobaciones iniciales del Product Engineer.

El resultado incluye estos ejemplos:

El Product Engineer asigna el fallo AC-05 al agente de implementación, confirma que el requisito no ha cambiado e indica una corrección. El verificador independiente repite la comprobación del motivo vacío y confirma que ahora se impide rechazar sin motivo, mientras que un rechazo válido sigue funcionando y registra los detalles esperados.

La comprobación de privacidad bloqueada AC-07 no cuenta como superada. Antes de declarar completa la verificación, el equipo proporciona identidades de prueba adecuadas y la repite o registra explícitamente una limitación pendiente para su tratamiento según las políticas de aceptación y riesgo de la organización. El ejemplo no debe afirmar que todas las comprobaciones se superaron si alguna sigue bloqueada.

El arquitecto revisa la implementación modificada, confirma la resolución del hallazgo de autorización de la etapa 4, considera el informe de verificación independiente y evalúa las implicaciones técnicas del nuevo comentario opcional de aprobación. Registra la preparación técnica para las UAT, sujeta a las políticas normales de la organización.

La revisión también reconoce el hallazgo AC-05 sobre el motivo de rechazo, corregido y comprobado de nuevo de forma independiente. Las UAT reciben un informe que distingue los fallos resueltos de cualquier limitación pendiente de la comprobación de privacidad AC-07.

Las partes interesadas del negocio prueban los flujos de envío y revisión y toman la decisión de aceptación bajo el procedimiento normal de UAT de la organización. Cualquier defecto nuevo o cambio acordado vuelve al ciclo de especificación e implementación. Este ejemplo termina en las UAT; los procesos empresariales de publicación y operación no están incluidos en el ciclo de desarrollo SHAPE.

Una vez en uso el producto, las partes interesadas solicitan que un solicitante pueda retirar una solicitud Enviada antes de que el revisor decida sobre ella. El Product Engineer añade el siguiente comportamiento acordado al conjunto de especificaciones:

Cambio: Un solicitante puede retirar su propia solicitud Enviada. La retirada cambia el estado de la solicitud a Retirada, registra quién la retiró y cuándo, e impide su aprobación o rechazo posteriores. Los revisores no pueden retirar solicitudes en nombre de los solicitantes salvo que se tome explícitamente una decisión de autorización separada.

El agente implementa la mejora dentro de los estándares existentes del proyecto. Las pruebas independientes comprueban la retirada autorizada, la denegación de retirada a otros usuarios y el rechazo de una decisión de revisión tardía sobre una solicitud retirada. El arquitecto revisa el cambio si su impacto en seguridad y flujo de trabajo cumple los umbrales de la organización. Después, las partes interesadas del negocio realizan las UAT. El Product Engineer mantiene la responsabilidad de mantener la funcionalidad y las especificaciones relacionadas.

El proyecto ilustra la distinción de SHAPE entre descubrimiento conversacional y especificaciones mantenidas; entre una interfaz funcional y permisos aplicados; entre la implementación del agente de programación y la verificación independiente; entre la aprobación del arquitecto y la aceptación empresarial; y entre el primer ciclo de un producto y el trabajo posterior de mejora.

También muestra por qué las especificaciones duraderas importan después de la publicación: la mejora de retirada debe tener en cuenta el comportamiento y las transiciones de estado ya establecidos en el producto original.