Blog
¿Esta respuesta de la API no es diferente al diseño en Figma?
Viernes, justo antes del release. Un mensaje en Slack y todo el equipo se paraliza.
El PM mantenía los tickets de Jira al día. El diseñador pulía los archivos de Figma. Los devs lanzaban PRs a toda velocidad. Todos haciendo su mejor trabajo en su área — y sin embargo, al momento de integrar, salta la desalineación.
Empieza la arqueología de Slack del viernes por la noche. “¿Dónde se decidió esta spec?” “Esta API no coincide con el ticket original — ¿quién la cambió?” Nadie tiene la respuesta, porque el contexto detrás de la decisión no quedó registrado en ningún lado.
Caímos en este infierno de “nadie hizo nada mal, pero todo se incendió” más veces de las que nos gustaría admitir. Beaket nació de esa experiencia.
Las specs están diseñadas para mentir
No es que las specs sean malas. El problema es la estructura que las rodea.
La información vive naturalmente en distintos lugares — los PMs viven en Jira, los diseñadores en Figma, los devs en GitHub. Eso es normal y no hay por qué cambiarlo. Cada herramienta es la mejor en lo suyo.
El problema aparece cuando intentamos copiar todo a un único lugar, tratándolo como la versión “oficial.”
En el momento en que transcribes algo a Notion o a una wiki, ya existen dos copias. Cuando una se actualiza, la otra se convierte en mentira. Una spec que deja de mantenerse pierde el razonamiento detrás de las decisiones pasadas y se aleja de la realidad con cada semana que pasa.
No es cuestión de disciplina. Es un problema estructural. Mientras existan copias, la divergencia es inevitable.
Connect, Don’t Copy
Por eso abandonamos el enfoque de “centralizar todo.” Crear otra wiki más solo llevaría al mismo resultado.
Lo que hace Beaket es trazar relaciones entre la información que ya existe.
No necesitas copiar tus diseños de Figma ni tus discusiones de GitHub a Beaket. Cada herramienta sigue siendo la fuente de la verdad en su dominio. Beaket simplemente conecta esas fuentes a través del contexto de por qué se tomó una decisión.
En concreto, estructura las decisiones del proyecto en tres tipos de nodos:
- Spec — El requisito de negocio. ¿Qué estamos construyendo y por qué?
- Brief — El registro de decisión de diseño. Qué se decidió desde la perspectiva de diseño, por qué, y qué se rompe sin ello.
- ADR — El registro de decisión técnica. ¿Por qué este enfoque? ¿Qué alternativas se consideraron y descartaron?
Estos tres se conectan entre sí a través de aristas, formando un grafo de decisiones. En Beaket no se escriben especificaciones detalladas. Solo se registra qué se decidió, por qué y con qué se conecta — nada más.
La regla de “escribir menos”
Siendo honestos, este fue el punto más debatido del producto.
“¿No deberíamos permitir más detalle?” Por supuesto que esa pregunta apareció. Pero en el momento en que permites escribir en detalle, has creado otra wiki. Y las wikis siempre se pudren.
Por eso pusimos intencionalmente una restricción en Beaket: escribir menos.
El criterio es simple — ¿mi yo del futuro vendrá a buscar el porqué dentro de seis meses? Si sí, escríbelo. Si no, no lo hagas. Las listas de parámetros y los pasos de implementación van en GitHub. Beaket guarda solo la unidad mínima del porqué.
Es un tradeoff deliberado. Beaket nunca va a ser una herramienta de documentación técnica completa. Está hecho así a propósito.
El Ready Flag: un apretón de manos, no una aprobación
Hay un mecanismo más que nos alegra haber construido.
Después de que se escribe una Spec, el diseñador y el dev marcan independientemente un flag de “Ready”. El diseñador señala “entiendo los requisitos desde la perspectiva de UI.” El dev señala “los entiendo desde la perspectiva técnica.” Solo cuando ambos flags están marcados la Spec se convierte en “Ready.”
Esto no es un flujo de aprobación. Es un apretón de manos.
No es “lo leí”, sino “desde mi perspectiva, podemos avanzar.” Es una protección estructural contra arrancar la implementación sobre requisitos ambiguos.
Y si una Spec cambia después de estar marcada como Ready, el radio de impacto — cada Brief y ADR conectado — se muestra automáticamente. Sin necesidad de rebuscar en el historial de Slack.
Siguiendo el rastro de las decisiones
Beaket registra el historial de cambios más allá de quién cambió qué y cuándo. También captura el por qué.
Selecciona cualquier fragmento de texto y puedes rastrear cuándo fue modificado, por quién y por qué razón. Lo llamamos Decision Trail.
No es una funcionalidad vistosa. Pero dentro de seis meses, cuando alguien pregunte “¿por qué esta spec es así?” — la respuesta está ahí. Solo eso ya cambia la velocidad con la que un equipo toma decisiones.
Lo que todavía no sabemos
No creemos que Beaket sea ideal para todos los equipos.
Para equipos pequeños donde todos trabajan en el mismo espacio y el contexto se comparte de forma natural, puede ser excesivo. Para organizaciones de cientos de personas, todavía no hemos validado lo suficiente.
De lo que estamos seguros es de una cosa: perder el contexto detrás de las decisiones siempre tiene un costo. Y ese costo crece exponencialmente a medida que el equipo escala y el tiempo pasa.
Beaket es una herramienta para mantener ese costo bajo control — de forma estructural. No es una solución mágica. Se parece más a un seguro.
Si en tu equipo alguna vez pasó que nadie pudo explicar por qué se tomó una decisión de diseño — empieza conectando una sola decisión. Fíjate a dónde te lleva.