Blog
Essa resposta da API não tá diferente do design no Figma?
Sexta-feira, véspera do release. Uma mensagem no Slack e o time inteiro congela.
O PM estava mantendo os tickets do Jira em dia. O designer estava refinando o Figma. Os devs estavam mandando PRs a toda velocidade. Todo mundo dando o seu melhor dentro da sua área — até que, na hora de integrar, aparece o desalinhamento.
Começa a arqueologia de sexta à noite no Slack. “Onde foi que essa spec foi decidida?” “Essa API tá diferente do ticket original — quem mudou?” Ninguém sabe responder, porque o contexto por trás da decisão não ficou registrado em lugar nenhum.
Nós caímos nesse inferno de “ninguém errou, mas tudo pegou fogo” mais vezes do que gostaríamos de admitir. O Beaket nasceu dessa experiência.
Specs são feitas para mentir
Não é que specs sejam ruins. O problema é a estrutura ao redor delas.
A informação naturalmente vive em lugares diferentes — PMs vivem no Jira, designers no Figma, devs no GitHub. Isso é normal e não deve mudar. Cada ferramenta é a melhor no que faz.
O problema é quando tentamos copiar tudo para um único lugar, tratando-o como a versão “oficial.”
No momento em que você transcreve algo para o Notion ou uma wiki, existem duas cópias. Quando uma é atualizada, a outra vira mentira. Uma spec que para de ser mantida perde o raciocínio por trás das decisões antigas e vai se distanciando da realidade semana após semana.
Isso não é falta de disciplina. É um problema estrutural. Enquanto existirem cópias, a divergência é inevitável.
Connect, Don’t Copy
Por isso abandonamos a abordagem de “centralizar tudo”. Criar mais uma wiki só ia levar ao mesmo resultado.
O que o Beaket faz é traçar relações entre informações que já existem.
Você não precisa copiar seus designs do Figma ou discussões do GitHub para o Beaket. Cada ferramenta continua sendo a fonte da verdade no seu domínio. O Beaket apenas conecta essas fontes pelo contexto de por que uma decisão foi tomada.
Na prática, ele estrutura as decisões do projeto em três tipos de nós:
- Spec — O requisito de negócio. O que estamos construindo e por quê?
- Brief — O registro da decisão de design. O que foi decidido do ponto de vista de design, por quê, e o que quebra sem isso.
- ADR — O registro da decisão técnica. Por que essa abordagem? Quais alternativas foram consideradas e descartadas?
Esses três se conectam por arestas, formando um grafo de decisões. Você não escreve especificações detalhadas no Beaket. Registra apenas o que foi decidido, por quê e com o que se conecta — nada mais.
A regra do “escreva menos”
Sendo honesto, esse foi o ponto mais debatido no produto.
“Não deveríamos permitir mais detalhes?” Claro que essa pergunta surgiu. Mas no momento em que você permite escrita detalhada, você criou outra wiki. E wikis sempre apodrecem.
Por isso colocamos intencionalmente uma restrição no Beaket: escreva menos.
A regra é simples — daqui a seis meses, o eu do futuro vai voltar aqui procurando o porquê? Se sim, escreva. Se não, não escreva. Listas de parâmetros e passos de implementação ficam no GitHub. O Beaket guarda apenas a unidade mínima do porquê.
É um tradeoff deliberado. O Beaket nunca vai ser uma ferramenta de documentação técnica completa. Isso é proposital.
O Ready Flag: um aperto de mão, não uma aprovação
Tem mais um mecanismo que estamos felizes de ter construído.
Depois que uma Spec é escrita, o designer e o dev marcam independentemente um flag de “Ready”. O designer sinaliza “entendi os requisitos do ponto de vista de UI.” O dev sinaliza “entendi do ponto de vista técnico.” Só quando ambos os flags estão marcados a Spec se torna “Ready.”
Isso não é um fluxo de aprovação. É um aperto de mão.
Não é “li o documento”, mas sim “da minha perspectiva, podemos seguir em frente.” É uma proteção estrutural contra começar a implementar em cima de requisitos ambíguos.
E se uma Spec mudar depois de marcada como Ready, o raio de impacto — cada Brief e ADR conectado — aparece automaticamente. Sem precisar vasculhar o histórico do Slack.
Seguindo a trilha das decisões
O Beaket registra o histórico de mudanças além do quem mudou o quê e quando. Ele também captura o porquê.
Selecione qualquer trecho de texto e você consegue rastrear quando foi alterado, por quem e por qual motivo. Chamamos isso de Decision Trail.
Não é uma funcionalidade chamativa. Mas daqui a seis meses, quando alguém perguntar “por que essa spec é assim?” — a resposta está ali. Só isso já muda a velocidade com que um time toma decisões.
O que ainda não sabemos
Não achamos que o Beaket sirva para todo time.
Para equipes pequenas, onde todo mundo trabalha no mesmo espaço e o contexto é naturalmente compartilhado, pode ser demais. Para organizações com centenas de pessoas, ainda não validamos o suficiente.
O que temos certeza é de uma coisa: perder o contexto por trás das decisões sempre tem um custo. E esse custo cresce exponencialmente conforme o time escala e o tempo passa.
O Beaket é uma ferramenta para manter esse custo sob controle — estruturalmente. Não é bala de prata. É mais parecido com um seguro.
Se no seu time já aconteceu de ninguém conseguir explicar por que uma decisão de design foi tomada — comece conectando uma única decisão. Veja aonde isso leva.