Coroid utiliza desarrollo basado en especificaciones: la especificación acompaña a una tarea desde la planificación hasta las pruebas y la revisión, de modo que cada etapa trabaje a partir de la misma definición de éxito.
En lugar de partir de una frase y decidir los detalles mientras se escribe el código, Coroid convierte la solicitud en alcance explícito, exclusiones y criterios de aceptación. Ese documento se convierte en la fuente de verdad para el plan, la implementación, las pruebas y la revisión final.
¿Qué es el desarrollo basado en especificaciones?
El desarrollo basado en especificaciones es una forma de crear software a partir de una descripción acordada y verificable del resultado. La especificación indica qué cambiará, qué no cambiará, qué restricciones aplican y cómo un revisor puede determinar si el trabajo tuvo éxito.
Separa dos decisiones que suelen confundirse fácilmente:
- La especificación define qué significa el éxito.
- El plan de implementación define cómo lograrlo.
Esa separación permite corregir el alcance antes de que exista el código, sin prescribir una implementación demasiado pronto. En Coroid, también puedes activar el flujo de trabajo opcional SDLC cuando quieras aprobar la intención y la especificación antes de comenzar la planificación.
Cómo funciona el flujo de trabajo en Coroid
- Describe el resultado. Indica a Coroid el resultado que necesitas, el contexto relevante y cualquier restricción o objetivo no deseado.
- Revisa la especificación. Comprueba el alcance, las exclusiones y los criterios de aceptación en la pestaña Especificación de la Tarea.
- Aprobar el plan. El arquitecto convierte el resultado acordado en pasos ordenados de implementación.
- Construir y verificar. Los agentes de desarrollo y control de calidad utilizan los mismos criterios para implementar el cambio y demostrar cada comportamiento prometido.
- Revisa el pull request. El cambio entregado lleva el plan, los resultados de las pruebas, los hallazgos y las pruebas de nuevo a la especificación original.
El resultado es la trazabilidad desde la intención del producto hasta el código y las pruebas que ve un revisor humano. Consulta Cómo una tarea se convierte en un pull request para conocer la ruta de ejecución completa.
¿Por qué este paso adicional?
Una instrucción como "añadir caché a la búsqueda de usuarios" tiene al menos cuatro implementaciones razonables y ninguna definición de finalización. Un agente elegirá una. Que sea la tuya es cuestión de suerte.
La especificación hace esa elección explícita antes de comenzar la implementación, en el momento en que es más barato cambiar de opinión.
También proporciona algo contra lo que verificar. Sin criterios de aceptación, la pregunta "¿funcionó esto?" se reduce a "¿siguen pasando las pruebas?", lo cual es una pregunta mucho más débil.
Qué contiene una especificación
| Parte | Qué responde |
|---|---|
| Alcance | Qué cambiará |
| Fuera de alcance | Qué se omitirá deliberadamente para que el cambio no se expanda sin control |
| Criterios de aceptación | Cómo cualquiera puede saber si funcionó |
| Contexto | Restricciones, convenciones y decisiones previas que aplican |
Puedes leerlo y editarlo en la pestaña Especificación de la Tarea antes de que comience la ejecución. Para la descripción del trabajo y el contexto de apoyo que alimentan este proceso, consulta Describir lo que necesitas.
Ejemplo práctico: desde el resumen hasta la especificación verificable
Supongamos que el resumen original es:
Add caching to the user lookup so repeated requests are faster.Eso indica el resultado deseado, pero deja decisiones importantes sin resolver. Una especificación útil convierte esas decisiones en límites y comprobaciones:
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.Ahora el plan puede elegir una implementación, el control de calidad puede convertir los criterios en pruebas y el revisor puede comparar el pull request con el comportamiento prometido.
Qué hace que los criterios de aceptación sean buenos
Deben ser verificables por alguien que no estuvo en la conversación.
Débil:
Caching works correctly and performance is improved.Fuerte:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.La segunda versión indica al agente de desarrollo qué construir, al agente de control de calidad qué probar y a ti qué comprobar en el pull request. La primera deja abiertas todas esas decisiones.
Las líneas de alcance son tan importantes como los criterios
La causa más común de un pull request demasiado grande no es que un agente sobrepase sus instrucciones, sino una especificación que nunca indicó dónde terminaban dichas instrucciones.
Si no desea que se refactorice el módulo circundante mientras se realiza la tarea, indíquelo. La instrucción «No modificar los puntos de llamada» es válida y útil.
Errores comunes en las especificaciones
| Error | Enfoque recomendado |
|---|---|
| Describir la implementación en lugar del resultado esperado | Indique el comportamiento y las restricciones, y deje que el plan determine la implementación. |
| Usar términos como «rápido», «seguro» o «funciona correctamente» | Reemplácelos por umbrales observables, comportamientos o pruebas concretas. |
| Omitir los elementos que no forman parte del alcance | Indique los nombres del código, las interfaces o los comportamientos que deben permanecer sin cambios. |
| Combinar resultados no relacionados | Divida el trabajo para que cada tarea genere un único pull request apto para revisión. |
| Copiar un ticket sin verificar las premisas subyacentes | Añada el contexto y las decisiones que el repositorio no puede reflejar. |
Cuando no esté de acuerdo con la especificación
Edítela. La especificación es un documento dinámico hasta que comience la ejecución; corregirla resulta mucho más económico que modificar el código derivado de ella.
Si la especificación revela que el trabajo consta de dos partes distintas, divídalo en dos tareas. Cada tarea debe generar un único pull request que una persona pueda revisar en una sola sesión.
Próximos pasos
Para cualquier cambio que supere el tamaño de una modificación menor, la especificación se convierte en un plan. Consulte Tareas, planes, sprints y columnas, donde se explica cómo se divide y aprueba el trabajo antes de escribir código.
Preguntas frecuentes
¿Es una especificación lo mismo que un diseño técnico?
No. Una especificación define el resultado y los límites requeridos. Un diseño técnico o plan de implementación describe la arquitectura y los pasos para alcanzar ese resultado.
¿Necesita cada cambio una especificación detallada?
No. Un cambio pequeño y sin ambigüedades puede requerir solo unas pocas líneas de alcance y criterios de aceptación. La especificación debe eliminar incertidumbres relevantes, no añadir trámites innecesarios.
¿Quién debe aprobar la especificación?
La persona responsable del resultado debe confirmar que el alcance y los criterios coinciden con las necesidades del equipo. Los responsables técnicos, de seguridad o de cumplimiento pueden participar cuando sus restricciones afecten al éxito del proyecto.
¿Puede modificarse una especificación después de iniciar el trabajo?
Sí, pero la modificación debe generar una nueva versión y provocar la revisión del plan y el trabajo dependientes. Los cambios de alcance silenciosos rompen la cadena de evidencia entre la solicitud y el pull request entregado.