DOMINAR / GUÍA 04
Specs y ADRs: escribir para que el futuro te entienda.
Cómo se escribe un criterio verificable, cuándo un ADR merece existir y cuándo no — con ejemplos buenos y malos lado a lado.
Los ficheros de la memoria estructural tienen teoría propia. Esta guía es el manual de estilo para escribirlos bien — porque un spec mal escrito arrastra a todo el run.
Un criterio verificables… o una opinión
La diferencia se ve lado a lado:
- Opinión (mal): «la migración no debe romper nada» — ¿cómo lo compruebas? ¿Quién decide qué es “nada”?
- Criterio (bien):
[ ] suite billing en verde · [ ] webhook idempotente (replay de eventos)— un comando, un veredicto, sin matices.
Regla: si no puedes verificarlo con un comando, no es un criterio. Es una esperanza. Las esperanzas van a Supuestos, donde se ven.
El ciclo de vida de un spec
- BORRADOR — nace en el paso ⑥ del intake. No vale nada.
- Validado — tú lo apruebas en el paso ⑦. Se convierte en el contrato de la fase.
- ABIERTA/CERRADA — la fase corre; al cerrar, release graba la evidencia. Un criterio sin número deja la fase ABIERTA.
- PENDIENTE — la siguiente fase (f2) queda a la espera: la próxima tarea empieza ahí.
Y f0, la fase cero, es la foto del presente: lo que hay HOY, medido. Sin f0, «sin romper nada» no tiene contra qué compararse.
Cuándo un ADR merece existir
Sí — decisión con calado: elegir la pasarela de pagos (ADR-0004). Condiciona meses de trabajo y nadie quiere re-decidirla por accidente. Contiene: la decisión, el contexto, las opciones consideradas y las consecuencias.
No — rutina: «hoy usamos el botón azul del skill-ui». Eso no condiciona nada: es una convención, y ya vive en el sistema de diseño.
Tampoco — lo ya decidido: el architect de f2 no abre un ADR de pasarela: existe. Reutilizar ADR-0004 es la respuesta correcta; abrir ADR duplicado es ruido que contamina la memoria.
Congelado, no eterno
Un ADR no se edita. Si una decisión caduca — digamos que la pasarela cambia dentro de dos años — se escribe un ADR nuevo que la sustituye y explica el porqué. Las decisiones tienen edad, no se retocan: cualquiera puede leer CÓMO cambió la opinión del sistema y cuándo.
El cuaderno: lecciones accionables
Una lección buena es corta y técnica + resultado:
«adapter Stripe: reintentos con JobLock» — qué técnica, aplicada dónde, con qué resultado.
Una lección mala es un diario en prosa («hoy tuvimos problemas con los pagos…»). La primera la consulta el builder antes de repetir un error caro; la segunda nadie la encuentra. Y cuando una lección vale más allá del proyecto, se promociona a la biblioteca del owner como patrón — con su procedencia.