Especificación-primero-desarrollo
DDD para nombrar cosas, BDD para especificarlas, el cambio más pequeño para satisfacerlas, evidencia para probarlo. Independiente del stack.
1. Piensa antes de codificar
- Declara suposiciones. Si la solicitud no es clara o tiene varias lecturas, nómbralas y pregunta. Nunca elijas en silencio.
- Si existe un enfoque más simple, dilo y rechaza el otro.
- Lee el código que toca la tarea. Enumera todo lo que el cambio debe alcanzar (llamantes, pruebas, fixtures, configuraciones, exportaciones) y lo que podría romper (datos destruidos o expuestos, llamantes que dejan de funcionar). Eso es el alcance; las funcionalidades extra no están. Nombra los extras omitidos en una línea.
- Antes de la primera escritura, crea una rama desde main con un nombre que se ajuste al trabajo (p. ej.,
feat/<funcionalidad>,fix/<error>). El trabajo de solo lectura no necesita rama.
2. Modela el dominio (DDD)
Antes del código, escribe en unas pocas líneas:
- Contexto delimitado y su lenguaje ubicuo: los términos que usan los expertos del dominio. Reutiliza los términos existentes del código base; añade nuevos solo cuando sea necesario.
- Agregado y sus invariantes: lo que siempre debe ser verdadero.
- Los nombres en código, pruebas y mensajes usan estos términos. Rechaza nombres genéricos (
handle,process,manager,utils). - La lógica de dominio es pura sobre datos planos. E/S (BD, red, reloj, aleatoriedad) se sitúa detrás de un puerto en el borde, inyectado.
Guárdalo en docs/specs/<funcionalidad>.md.
Omite esto para cambios triviales que no añadan ningún concepto de dominio.
3. Especifica el comportamiento (BDD)
Escribe escenarios Dado/Cuando/Entonces en lenguaje de dominio, uno por comportamiento, incluyendo los casos extremos y de fallo. Cada uno describe comportamiento observable, no implementación. Obtén la aprobación del usuario para escenarios no obvios; son el contrato. Guárdalos en docs/features/<funcionalidad>.feature.
4. Planifica
Para trabajo de múltiples pasos, escribe un plan breve en docs/plans/<funcionalidad>.md: cada paso con su verificación. Al continuar desde una especificación existente, igualmente escribe el plan primero. Luego detente y pide al usuario que lo revise; nunca ejecutes hasta que lo aprueben. Toma la primera opción que funcione completamente:
- ¿Necesita existir? Si no, omítelo.
- ¿Ya está en este código base? Úsalo como lo hace el código circundante.
- ¿Es función de la biblioteca estándar o de la plataforma? Úsala.
- ¿Dependencia instalada? Úsala. Nunca añadas una para unas pocas líneas.
- ¿Una línea que un lector entiende de un vistazo? Úsala.
- De lo contrario, el mínimo código que funcione.
5. Ejecuta
Orquestación
Cuando estés a punto de ejecutar tareas, con o sin especificación o plan, verifica si encajan: varios elementos separables (p. ej., 3+ correcciones), pasos independientes o pasos de dificultad claramente diferente. Si es así, lee orchestration.md (junto a este archivo) y pregunta sus dos opciones (mediante AskUserQuestion) antes de la primera edición: en el mismo turno que la revisión del plan si escribes un plan, si no, de inmediato. Siempre pregunta; ninguna otra aprobación (plan, especificación, "ok") cuenta como elección. Si las tareas no encajan, hazlo en línea.
Rojo, verde, refactorizar, por escenario
- Convierte un escenario en una prueba fallida. Ejecútala; véla fallar por la razón correcta.
- Escribe el menor código que pase. Ejecútalo.
- Refactoriza solo lo que este cambio haya vuelto desordenado.
- Corrección de errores: reproduce con un escenario fallido primero, busca en todos los llamantes de la función, corrige la causa raíz una vez en el código compartido.
6. Mantén el diff quirúrgico
- Toca solo lo que debas. Coincide con el estilo existente; no mejores el código adyacente. Cada línea cambiada se remonta a la solicitud.
- Elimina solo los huérfanos que tu cambio creó; menciona otro código muerto, no lo elimines.
- Sin abstracción, envoltorio, opción, configuración ni código "para más tarde" que nadie pidió. Eliminar es mejor que añadir.
- El código que mueves conserva su manejo de errores y validación.
- Comenta solo el porqué, en una línea. Un límite conocido recibe
shortcut: <el límite>, <cuándo actualizar>. - Nunca recortes: validación en límites de confianza, manejo de errores que evite pérdida de datos, seguridad, accesibilidad, nada de lo que el usuario pidió.
7. Verifica antes de declarar terminado
Ejecuta las pruebas y cualquier compilación o verificación de tipos. Lee la salida. Informa resultados reales; si algo falló o no se ejecutó, dilo. Nada de "debería funcionar".
8. Responde
Termina con una o dos líneas: lo que omitiste o no revisaste, y cualquier riesgo que el usuario deba conocer.