Formación › Programar con Claude Code en 12 horas › Hora 6
Programar con Claude Code en 12 horas · hora 6 de 12
Desarrollo guiado por especificaciones
Con un agente que programa rápido, el cuello de botella pasa a ser decir bien qué quieres. Una especificación escrita antes del código lo resuelve, pero no siempre compensa. Verás la spec real que escribió Claude Code para quitar duplicados y cuándo merece la pena el método.
Al terminar sabrásPedir una especificación con comportamiento esperado, casos límite, fuera de alcance y verificación final antes de programar, y decidir cuándo el desarrollo guiado por especificaciones es excesivo.
60 minutos· 1 esquema· 6 preguntas· 2 ejercicios· entregable
Repaso
Comprueba De la hora 5: Claude escribe una prueba para el duplicado de P-106 y pasa a la primera, antes de tocar el código. ¿Qué te dice?
Correcto. Si el fallo existe, la prueba que lo reproduce tiene que fallar antes del arreglo.
No. Puede ser, pero lo normal es que la prueba no compruebe lo que crees.
No. Una prueba en verde desde el principio no demuestra nada.
Comprueba De la hora 4: al planificar el CSV, Claude ve que una fecha del repositorio está mal. ¿Qué debería hacer?
No. Mezclaría tareas y haría el cambio más difícil de revisar.
No. Callarlo es peor: lo descubrirás más tarde.
Correcto. Sin ampliar el alcance por su cuenta.
Comprueba De la hora 3: tu equipo exige que nadie edite datos/. ¿Dónde lo pones para que se cumpla?
Correcto. Se ejecuta siempre, decida lo que decida Claude.
No. Tampoco obliga.
No. CLAUDE.md es contexto, no obligación.
Vocabulario
- Spec (especificación)
- El documento que dice qué debe hacer un cambio y cómo se comprueba, antes del código.
- Caso límite
- Una situación poco habitual que el diseño debe resolver, como dos filas con el mismo id y datos distintos.
- Fuera de alcance
- Lo que el cambio no va a tocar, escrito para que nadie lo amplíe por su cuenta.
- Verificación de extremo a extremo
- La comprobación final que demuestra que el cambio funciona completo.
El ejemplo: la spec de la deduplicación
Cada sesión grabada parte del repositorio de práctica recién descargado. Si arreglaste la medianoche en la hora 5, tus números serán distintos: para repetir esta sesión tal cual, descomprime el zip otra vez en una carpeta nueva.
Antes y después Una spec antes del código
La petición
Vamos a añadir la deduplicación de paradas: si una parada aparece dos veces con el mismo id, solo debe contar una vez en el parte. Antes de programar nada, escribe SPEC.md con: el problema, el comportamiento esperado, los casos límite (incluido qué hacer si dos filas tienen el mismo id pero datos distintos), qué queda fuera de alcance y una verificación final de extremo a extremo con npm run parte. No cambies el código.La sesión real
Salida real Claude Sonnet 5.5 · 24 de octubre de 2026 · sin editar · Claude Code en modo acceptEdits sobre el repositorio de práctica
Para repetirla, en el repositorio: claude --permission-mode acceptEdits y pega la petición. Se grabó con claude -p, sin conversación: lo que aquí se deniega, a ti te lo preguntaría.
Lo que hizo: 11 acciones
Bash: git ls-files; echo ---; cat package.jsonRead: src/paradas.jsRead: src/informes/semanal.jsRead: src/cli.jsRead: datos/paradas.csvRead: README.mdRead: pruebas/parte.test.jsRead: src/fechas.jsBash: npm run parte --silent; echo ---; npm test --silent 2>&1 | tail -12Bash: npm run parte --silentWrite: SPEC.md
He escrito SPEC.md en la raíz del repositorio y no he tocado el código. Tiene los cinco apartados que pedías.
Qué cambia para el parte: en datos/paradas.csv, P-106 aparece dos veces idéntica y hoy infla L3 de 4,0 h a 6,5 h. Con la deduplicación, L3 pasa a 4,0 h y las demás líneas no cambian.
Decisión que necesito que confirmes: qué hacer cuando dos filas tienen el mismo id pero datos distintos. Propongo conservar la primera fila, avisar por stderr indicando los campos que difieren y generar el parte igualmente. La alternativa es abortar con error. Lo dejé marcado como decisión pendiente en el caso límite 1.
Fuera de alcance, pero lo vi: P-104 (23:30–01:15) cruza la medianoche y horasEntre la calcula como −22,25 h. Ese defecto ya está falseando el total de L2 en el parte actual. Lo dejé fuera de alcance para no mezclarlo con la deduplicación, pero conviene tratarlo aparte.
Verificación sin ejecutar: el entorno me denegó los permisos para ejecutar npm run parte y npm test. Los valores esperados de la verificación final (L3 = 4,0 h, L1 = 2,3 h) los calculé a mano. La propia especificación lo advierte y pide contrastarlos con la salida real antes de dar nada por bueno.
Los cambios que dejó (diff)
diff --git a/SPEC.md b/SPEC.md
new file mode 100644
index 0000000..0c52132
--- /dev/null
+++ b/SPEC.md
@@ -0,0 +1,54 @@
+# SPEC: deduplicación de paradas por id
+
+## Problema
+
+`datos/paradas.csv` es una exportación en la que una misma parada puede aparecer más de una vez. En el fichero de ejemplo, `P-106` (L3, Encajadora, 09:00–11:30) está en las líneas 7 y 8, idéntica. Hoy `leerParadas` devuelve ambas filas y `horasPorLinea` suma las dos, así que el parte infla la línea L3 con 2,5 h que no existen (6,5 h en lugar de 4,0 h).
+
+Una parada es un hecho único identificado por su `id`. Contarla dos veces falsea el parte semanal.
+
+## Comportamiento esperado
+
+1. Si varias filas comparten el mismo `id`, la parada cuenta **una sola vez** en las horas por línea y, por tanto, en el parte.
+2. Cuando las filas con el mismo `id` son idénticas en todos los campos, se colapsan en silencio.
+3. Cuando las filas con el mismo `id` tienen datos distintos (ver caso límite 1), se conserva la **primera aparición** y se avisa por `stderr`. El parte sale igualmente por `stdout`.
+4. La deduplicación conserva el orden de la primera aparición y no modifica el resto de filas.
+5. La deduplicación va entre la lectura del CSV y el cálculo de horas, de modo que `horasPorLinea` y `parteSemanal` reciben ya paradas únicas. El formato del parte no cambia.
+
+## Casos límite
+
+1. **Mismo `id`, datos distintos** (p. ej. `P-106` con fin 11:30 en una fila y 12:00 en otra). No hay forma de saber cuál es la correcta, así que no se suman ni se elige en silencio:
+ - se conserva la primera fila;
+ - se escribe en `stderr` un aviso por id en conflicto, con los campos que difieren (`Aviso: P-106 aparece con datos distintos (fin: 11:30 / 12:00); se usa la primera fila`);
+ - el proceso termina con código 0 y el parte se genera.
+
+ *Decisión a confirmar:* la alternativa es abortar con error. Se propone avisar y continuar porque un parte semanal con aviso es más útil que ningún parte, y el aviso deja la discrepancia a la vista.
+2. **Duplicados idénticos más de dos veces** (tres o más filas iguales): cuentan una vez.
+3. **Mismo `id` en fechas distintas**: es el mismo caso que el 1 (datos distintos). El `id` manda; no se interpreta como dos paradas.
+4. **Mismos datos pero `id` distinto**: son paradas distintas y ambas cuentan. Solo el `id` define la identidad.
+5. **Espacios alrededor del `id`** (`" P-106"`): se comparan sin espacios iniciales ni finales. Las mayúsculas y minúsculas **sí** se distinguen (`p-106` ≠ `P-106`).
+6. **`id` vacío o ausente**: no se puede deduplicar, así que esa fila se conserva tal cual y nunca se agrupa con otras filas sin `id`.
+7. **CSV sin duplicados**: la salida es idéntica a la actual, byte a byte.
+8. **Fila duplicada que cae en otra línea de producción** (mismo `id`, `linea` distinta): es un caso 1; se conserva la primera y el aviso menciona el campo `linea`.
+
+## Fuera de alcance
+
+- Corregir el cálculo de paradas que cruzan la medianoche. `P-104` (23:30–01:15) da hoy −22,25 h porque `horasEntre` asume el mismo día. Es un defecto independiente que ya afecta al total de L2 y se trata aparte.
+- Validar el CSV (campos que faltan, horas mal formadas, filas vacías).
+- Duplicados "difusos" (misma parada con ids distintos, ids con otro formato).
+- Cambiar el formato del parte, la semana ISO o la detección de la semana (`paradas[0].fecha`).
+- Modificar `datos/paradas.csv`. Los datos de entrada no se tocan.
+- Un modo para elegir la fila "ganadora" (última, la de más duración, etc.) o un fichero de informe de conflictos.
+
+## Verificación final de extremo a extremo
+
+Con el `datos/paradas.csv` actual y sin tocarlo:
+
+1. `npm test` pasa entero, incluidas las pruebas nuevas de deduplicación (duplicado idéntico, conflicto con datos distintos, `id` vacío, `id` con espacios, sin duplicados).
+2. `npm run parte` imprime el parte con **L3 = 4,0 h** (antes 6,5 h) y no emite ningún aviso en `stderr`, porque el duplicado de `P-106` es idéntico.
+3. L1 se queda en 2,3 h (2,25 h, redondeo a un decimal) y L2 no cambia respecto a la ejecución previa. Ninguna de las dos tiene duplicados, y L2 sigue arrastrando el defecto de `P-104` descrito en "Fuera de alcance".
+4. Comparación antes/después: la única línea que cambia en la salida de `npm run parte` es la de L3.
+5. Prueba de conflicto: con una copia temporal del CSV (fuera del repositorio) donde la segunda fila de `P-106` tenga `fin` 12:00, `node src/cli.js <copia>` muestra el aviso en `stderr`, termina con código 0 y cuenta L3 = 4,0 h (primera fila).
+
+## Nota sobre los valores esperados
+
+Los importes de L1, L2 y L3 se han calculado a mano a partir del CSV y del código actual. No se ha ejecutado `npm run parte` al escribir esta especificación, así que hay que contrastarlos con la salida real antes de dar la verificación por buena.Qué ha pasado
Una spec de las que ahorran trabajo:
- Una decisión, marcada como tal: propone conservar la primera fila y avisar, pero lo deja como decisión a confirmar, con la alternativa (parar con error). No decide por ti lo que no le corresponde.
- Casos límite que nadie había pedido: tres o más duplicados,
idvacío, espacios alrededor delidy mayúsculas. - Fuera de alcance explícito: la parada de medianoche, para no mezclar tareas.
- Honestidad sobre lo no comprobado: no pudo ejecutar
npm run parte(en ese modo no tenía permiso para comandos) y avisa de que los valores esperados están calculados a mano y hay que contrastarlos.
Comprobado contra los datos de práctica: sin el duplicado, L3 pasa de 6,5 a 4,0 horas (1,5 de P-103 y 2,5 de P-106), y L1 suma 2,25 horas, que el parte redondea a 2,3. Los cálculos a mano eran correctos.
Qué es el desarrollo guiado por especificaciones
La idea es sencilla: la especificación va delante del código. Primero se escribe qué debe pasar y cómo se comprueba; después, el agente programa contra esa especificación; al final, una verificación demuestra que se cumple.
La guía de buenas prácticas de Claude Code propone una variante muy práctica: dejar que Claude te entreviste («entrevístame con detalle sobre técnica, interfaz, casos límite y riesgos; después escribe SPEC.md») y ejecutar la spec en una sesión nueva, con el contexto limpio y centrado en implementarla. Según la guía, las specs más útiles nombran los ficheros e interfaces, dicen qué queda fuera de alcance y terminan con una verificación de extremo a extremo.
Cuándo compensa (y cuándo no)
Birgitta Böckeler, de Thoughtworks, analizó las herramientas de SDD (Kiro, spec-kit y Tessl) y distingue tres niveles: escribir la spec antes del código, mantenerla después como referencia, o tratarla como la fuente de la que sale el código. También recoge sus problemas: demasiado proceso para cambios pequeños, muchos ficheros que revisar y agentes que a veces ignoran lo que dice la spec.
La conclusión práctica:
- Compensa: cambios con decisiones de diseño, varios ficheros, varias personas, o algo que habrá que mantener.
- Sobra: una errata, un ajuste de una línea, un experimento que vas a tirar.
Practica
Clasifica ¿Spec primero o directamente?
- La deduplicación de paradas, con una decisión sobre filas en conflictoHay una decisión de diseño y casos límite que conviene acordar antes.
- Corregir una errata en el título del parteUna spec para una línea es puro proceso.
- Una exportación del parte que usarán tres departamentosVarias personas y un formato que habrá que mantener.
- Probar si una idea de cálculo funciona, para tirarla despuésEs un experimento: la spec llegará si la idea se queda.
Ordena Ordena el flujo con spec
- Revisar la spec y decidir lo que deja abiertoComo la política de filas en conflicto.
- Ejecutar la verificación de extremo a extremoLa prueba de que el cambio cumple la spec.
- Pedir a Claude que te entreviste sobre el cambioSaca a la luz lo que no habías pensado.
- Que escriba SPEC.md con alcance, casos límite y verificación finalEl documento que guiará la implementación.
- Abrir una sesión nueva e implementar contra la specContexto limpio, centrado en ejecutar.
Comprueba lo que has aprendido
Comprueba La spec real dejó «decisión a confirmar» sobre las filas en conflicto. ¿Por qué es lo correcto?
Correcto. Avisar y seguir o parar con error depende de cómo usáis el parte.
No. Puede proponerlas, como hizo, siempre que quede claro qué está decidido y qué no.
No. Propuso una solución técnica concreta; lo que no hizo fue decidir por ti.
Comprueba ¿Para qué sirve el apartado «fuera de alcance»?
Correcto. Ni la persona ni el agente.
No. No es una excusa: es un límite.
No. Puede apuntarlo, pero su función es limitar este cambio.
Comprueba ¿Cuándo es excesivo el desarrollo guiado por especificaciones?
Correcto. La spec sería más trabajo que el propio cambio.
No. Un agente capaz programa rápido, y por eso decir bien qué quieres importa más.
No. Ahí es justo cuando más compensa.
Entregable Tu primera spec
Elige un cambio con alguna decisión de diseño en el repositorio de práctica o en tu proyecto. Pide a Claude que te entreviste y escriba SPEC.md con comportamiento esperado, casos límite, fuera de alcance y verificación final. Pega aquí la spec, las decisiones que tomaste tú y el resultado de la verificación tras implementarla.
Está bien si: la spec tiene al menos tres casos límite, un apartado de fuera de alcance y una verificación que se puede ejecutar; marcas qué decidiste tú; y la verificación pasó tras implementar. Tiempo: unos 40 minutos; si no te da, entrega solo la spec revisada.
Lo esencial
- La especificación va delante: qué debe pasar y cómo se comprueba, antes del código.
- Una buena spec marca lo que queda por decidir, en vez de decidir por ti.
- Casos límite, fuera de alcance y verificación final son lo que más valor aporta.
- Compensa en cambios con decisiones o que habrá que mantener; sobra en lo trivial.
Fuentes y para seguir
- Buenas prácticas de Claude Code: deja que Claude te entreviste (se abre en otra pestaña) (documentación oficial, consultada el 24/10/2026).
- Understanding Spec-Driven Development: Kiro, spec-kit and Tessl (se abre en otra pestaña) (Birgitta Böckeler, martinfowler.com, en inglés).
- Spec Kit (se abre en otra pestaña) (GitHub).
- En MaestrIA: la guía de desarrollo guiado por especificaciones y las plantillas de SDD del kit.
Lección revisada el 24/10/2026 con la documentación oficial enlazada en sus fuentes. Revisamos los cursos cada trimestre.