Bitácora de decisiones: el porqué que se olvida en semanas
Dentro de tres meses vas a abrir tu proyecto y preguntarte por qué lo hiciste así. Claude tampoco se va a acordar: cada conversación empieza de cero. Una bitácora de decisiones es el archivo donde queda escrito el porqué, con su fecha, lo que descartaste y cómo se deshace. Y su hermano, el catálogo de patrones, es donde los errores que se repiten reciben un nombre para no repetirlos una tercera vez.
- 01Qué esQué es una bitácora de decisiones
- 02Qué esQué lleva cada entrada
- 03Qué esEl catálogo de patrones: errores con nombre
- 04Paso a pasoCómo empezar la tuya
- 05CuidadoLo que escribes y nadie lee
- 06PromptsUn prompt para que Claude escriba la entrada
- 07CuidadoLo honesto
Qué es una bitácora de decisiones
En el mundo del software se llama registro de decisiones de arquitectura (ADR, por sus siglas en inglés). Martin Fowler lo define como un documento corto que recoge y explica una sola decisión: la decisión, el contexto en que se tomó y sus consecuencias. Sirve para que, meses o años después, alguien entienda por qué las cosas están hechas así. (Martin Fowler · ADR)
Y una regla que lo cambia todo: una decisión ya registrada no se modifica. Si cambia, se escribe otra nueva que la reemplaza y enlaza a la anterior. Así queda la historia completa, no solo la última versión.
Piensa en la bitácora de un barco. Nadie arranca la página de ayer porque el rumbo cambió: se escribe hoy el rumbo nuevo y por qué. Por eso se le puede creer.
Qué lleva cada entrada
El formato que usamos en IActn, con lo que pide cada parte:
| Parte | Qué va |
|---|---|
| Fecha y título | Cuándo y qué, en una línea |
| Contexto | Qué pasaba que obligó a decidir |
| Decisión | Qué se eligió |
| Alternativas descartadas | Qué más se miró y por qué no |
| Verificación | Cómo se comprobó que funciona |
| Reversibilidad | Cómo se deshace si sale mal |
| Alertas | Qué vigilar, o qué haría replantearla |
Fowler pide casi lo mismo: las alternativas serias con sus pros y contras, las consecuencias, qué tan seguro estabas al decidir y qué cambio haría volver a revisarla. Y lo más importante, según él: que sea corta, normalmente una página.
El catálogo de patrones: errores con nombre
La bitácora guarda decisiones. El catálogo guarda errores que se repiten. Google lo explica en su libro de ingeniería de fiabilidad: si no tienes una forma escrita de aprender de los incidentes, pueden repetirse sin fin. Su herramienta es el informe posterior (postmortem): qué pasó, qué impacto tuvo, qué se hizo, las causas y qué se hará para que no vuelva. Y sin buscar culpables: si hay miedo a que te señalen, los problemas no salen a la luz. (Google SRE · postmortems)
Nuestro catálogo es la versión corta de eso: cuando un control o una revisión nos engaña, el error recibe un nombre, su caso real y un «qué hacer en su lugar», y cada vez que se repite se apunta otra vez. Sin el caso, la regla se olvida; sin el «qué hacer», no se puede aplicar.
Nuestro ejemplo real: el catálogo de IActn tiene 132 patrones al 01-10-2026. Un control los revisa: si un patrón ya pasó dos veces y sigue solo escrito, sin un control que lo frene, lo marca en rojo. Hoy hay 7 así. Un error que se repite no pide otra nota: pide un gate.
Cómo empezar la tuya
- Crea un archivo de texto en la carpeta del proyecto. Nosotros lo llamamos
NOTEBOOK.md. Fowler recomienda guardar los registros junto al código, en texto simple, para que se lean y se comparen como cualquier otro archivo. - Una entrada por decisión que no sea obvia. Elegir un proveedor, cambiar una regla, descartar una herramienta. No cada tarea: una bitácora que lo registra todo no la lee nadie.
- Escribe lo importante primero. Fowler recomienda la «pirámide invertida» de las noticias: la decisión arriba, los detalles abajo.
- Nunca edites una entrada vieja. Si te equivocaste, añade una corrección con la fecha de hoy.
- Dile a Claude que la lea. Una línea en tu CLAUDE.md: «antes de cambiar la configuración, lee NOTEBOOK.md».
Nos pasó: el 30-09-2026 descubrimos que tres entradas llevaban en el título una fecha equivocada: decían 1 de octubre y se habían escrito el 30 de septiembre. No las tocamos. Añadimos una fe de erratas con la fecha real, y quien lea las entradas viejas encuentra la corrección justo después.
Lo que escribes y nadie lee
Una bitácora solo sirve si alguien la abre. Por eso cada lección va al sitio que mejor la protege:
| Si es… | Va en… | Porque… |
|---|---|---|
| Algo que no puede fallar nunca | Un gate o un hook | Salta aunque nadie se acuerde |
| Una regla de cómo trabajar | CLAUDE.md | Claude lo lee en cada sesión |
| El porqué de una decisión, con su fecha | La bitácora | Se consulta cuando hace falta entender |
La bitácora es la capa más frágil de las tres: depende de que alguien la busque. Úsala para el porqué, no como único guardián de lo importante.
Un prompt para que Claude escriba la entrada
Es nuestro, no de Anthropic.
De la conversación a la entrada de bitácora
Cuándo usarlo: al terminar una sesión en la que decidiste algo que no es obvio.
Lo honesto
- «Bitácora de decisiones» y «catálogo de patrones» son nuestros nombres. En la industria verás «ADR» (registro de decisiones de arquitectura) y «postmortem». La idea es la misma.
- Fowler propone un archivo por decisión, numerado. Nosotros usamos un solo archivo que crece hacia abajo. Las dos formas sirven; lo que no sirve es no escribir.
- La bitácora no reemplaza a los controles. Si algo se repite, súbelo a un gate.
- Escribirla cuesta. Fowler dice que el propio acto de escribirla ayuda a pensar, sobre todo en grupo, porque obliga a poner sobre la mesa los puntos de vista distintos.
Escribe el porqué el mismo día, con su fecha y lo que descartaste, y no borres nunca lo escrito: corrige con una entrada nueva. Y cuando el mismo error pase dos veces, ponle nombre y súbelo a un control.
¿Y ahora qué?
Tres formas de seguir, según lo que prefieras.
El mensaje para tu grupo
¿Le sirve a alguien de tu equipo o de tu grupo? Cópialo tal cual o ábrelo directo en WhatsApp.
Te paso esta guía: Bitácora de decisiones. El porqué por escrito, antes de que se olvide. https://iactn.com/arsenal/bitacora-de-decisiones/Fuentes, leídas el 01-10-2026
- Architecture Decision Record · Martin Fowler, 24 de marzo de 2026. Qué es un registro de decisiones, que no se modifica sino que se reemplaza, las alternativas y consecuencias, la brevedad, la pirámide invertida y guardarlo junto al código en texto simple.
- Postmortem Culture: Learning from Failure · libro de Site Reliability Engineering de Google. Qué es un postmortem, que sin aprendizaje escrito los incidentes se repiten y la cultura sin culpables.