Redactar especificaciones de funcionalidades

Esta es una técnica operativa recomendada, no un procedimiento universal de redacción manual o aprobación documental. El PE puede aportar una conversación, ejemplo o corrección demostrada en vez de un documento pulido. El agente analiza y mantiene la intención mientras implementa; las personas inspeccionan resultados funcionales y deciden cuestiones empresariales importantes. Identificadores, encabezados, condiciones y archivos por funcionalidad son técnicas opcionales del proyecto. Las normas empresariales pueden exigir aprobaciones propias para trabajos de riesgo.

La especificación conserva comportamiento previsto para implementar, cambiar y verificar de forma independiente. Los agentes pueden redactarlo y mantenerlo junto con incrementos funcionales; las personas inspeccionan resultados en lugar de firmar documentos.

Responsable: Product Engineer. Participantes: partes interesadas para decisiones empresariales importantes; arquitecto o UX para sus asuntos. Entradas: conversaciones, ejemplos, correcciones, intención actual y límites técnicos aprobados. Salidas: contexto legible mantenido, incrementos funcionales y decisiones pendientes visibles. No se requiere aprobación documental universal ni archivo manual pulido.

El Product Engineer puede expresar resultados mediante IA conversacional, conversaciones, ejemplos o una corrección demostrada. Los agentes exploran flujos, roles y fallos, preguntan por reglas pendientes y mantienen contexto legible mientras implementan. El PE cuestiona supuestos inventados mediante comportamiento real y lleva políticas importantes a las personas responsables.

El registro mantenido es distinto de una transcripción y del código observado. Debe versionarse para cambios posteriores y verificación independiente. Las personas no necesitan aprobar cada línea antes de construir un incremento útil; el agente no debe cambiar la intención solo para hacer desaparecer un defecto.

1. Aportar intención y límites. Dar objetivos, ejemplos, comportamiento actual y restricciones sin exponer datos sensibles.
2. Pedir análisis. El agente identifica actores, flujos, supuestos y preguntas abiertas.
3. Resolver decisiones importantes. Las personas responsables deciden políticas materiales; otras incógnitas quedan explícitas.
4. Capturar contexto mientras se construye. El agente puede redactar Markdown legible e implementar un incremento útil a la vez. Los identificadores y estructuras son opcionales.
5. Inspeccionar el producto. Probar resultados y cuestionar comportamientos ausentes, supuestos inventados y reglas contradictorias.
6. Preservar intención. Versionar el registro mantenido; un commit no es aceptación empresarial.
7. Iterar y verificar de forma independiente. Los agentes actualizan contexto cuando cambian resultados; otro verificador contrasta intención y producto.

Declaración inicial de una parte interesada:

«Los revisores deberían poder rechazar solicitudes».

Un asistente conversacional podría preguntar si se exige un motivo, si cualquier revisor puede rechazar cualquier solicitud, si se permite revisar solicitudes propias y si quien solicita puede ver la decisión.

Cuando la parte interesada decide las reglas, el Product Engineer registra comportamiento observable como:

«Un revisor autorizado solo puede rechazar una solicitud pendiente después de introducir un motivo no vacío. La decisión registra al revisor y la hora, y quien solicita puede ver el resultado y el motivo de su propia solicitud. Una persona no puede revisar su propia solicitud».

Este ejemplo demuestra análisis y aclaración, no políticas decididas por IA. La especificación puede entonces definir condiciones separadas para un motivo vacío, una acción no autorizada, la revisión propia y la visibilidad para quien solicita.

1. Elegir un límite coherente de funcionalidad. Una funcionalidad debe representar un comportamiento significativo del usuario o del sistema. Evite una única especificación gigante del producto cuando resulte difícil mantenerla, pero no fragmente un flujo simple en un archivo separado para cada campo o botón.

2. Declarar propósito y actores. Explique quién necesita la funcionalidad, qué resultado apoya, quién puede utilizarla y cuáles son las exclusiones importantes. Haga referencia a objetivos de proyecto más amplios cuando resulte útil.

3. Describir el comportamiento esperado. Redacte el flujo principal en términos de resultados observables y no de una estructura de código imaginada. Especifique entradas, validaciones, cambios de estado, mensajes de respuesta y salidas cuando corresponda.

4. Identificar reglas y excepciones. Incluya permisos, elegibilidad, límites, casos de rechazo o fallo y comportamiento cuando los datos o las dependencias externas no estén disponibles. Si una excepción cambia sustancialmente la aceptación, pertenece a la especificación.

5. Añadir condiciones de aceptación. Redacte comprobaciones que puedan evaluarse mediante observación o pruebas. Incluya condiciones representativas positivas y negativas. Evite afirmaciones como «funciona perfectamente» o «tiene una interfaz intuitiva» sin un contexto concreto.

6. Resolver y registrar la incertidumbre. Marque las preguntas pendientes importantes y obtenga decisiones de partes interesadas autorizadas. No convierta la conjetura de un agente en una regla empresarial aceptada. Si el trabajo avanza mientras una cuestión no crítica sigue abierta, identifique la suposición como provisional.

7. Revisar la coherencia. Compruebe la especificación frente a funcionalidades relacionadas, restricciones técnicas y de seguridad aprobadas, terminología y comportamiento existente. Haga referencias cruzadas a reglas compartidas en lugar de reformularlas de manera incompatible.

8. Mantenerla durante las iteraciones. Registre la especificación en el repositorio como parte del conjunto duradero del proyecto. Cuando las partes interesadas cambien el comportamiento aceptado, actualice el texto correspondiente y las condiciones de aceptación antes de los cambios de implementación o junto con ellos. Mantenga el historial en el control de versiones en lugar de crear copias paralelas confusas.

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.

Vago: «Los revisores deben tener una forma fácil de rechazar solicitudes».

Mejor: «Un revisor autorizado puede rechazar una solicitud pendiente solo después de introducir un motivo. La solicitud pasa a Rechazada, registra al revisor y el momento de la decisión, y muestra el motivo al solicitante. Un usuario sin permiso de revisión no puede realizar la acción».

Este ejemplo no prescribe una interfaz específica. Especifica un comportamiento significativo que puede implementarse y verificarse.

Un identificador y un título estables; propósito; alcance y exclusiones; actores y permisos; precondiciones; comportamiento principal; reglas empresariales; excepciones; condiciones de aceptación; dependencias; referencias cruzadas; y decisiones sin resolver. Es una estructura inicial, no una instrucción de rellenar secciones que no aporten valor.

El contexto es útil cuando describe intención con claridad suficiente para implementar y derivar comprobaciones independientes observables, manteniendo decisiones importantes pendientes asignadas a responsables. Los agentes actualizan el registro durante el trabajo. Las personas inspeccionan y aceptan resultados funcionales; la revisión del texto o aprobación de especificaciones no es requisito universal. Siguen las aprobaciones empresariales de riesgo aplicables. Mantener el registro previsto bajo control de versiones cuando evolucionen resultados.

Escribir código de implementación disfrazado de requisitos; repetir reglas empresariales que ya están documentadas con autoridad en otro lugar; especificar en exceso los detalles estéticos; dejar completamente implícito el comportamiento de permisos o errores; y permitir que el código en funcionamiento se convierta en la única declaración fiable del comportamiento esperado.