# Como documentar decisões técnicas para que não se percam Source: https://baqueiro.es/pt/ingenieria-sin-atajos/como-documentar-decisoes-tecnicas/ Published: 2025-10-16T07:47:00+00:00 Updated: 2025-10-16T07:47:00+00:00 Author: Baqueiro Desarrollo Web Language: pt-PT Usage: Attribution required: quoting allowed with a visible link back --- **TL;DR** - Uma decisão técnica não documentada esquece-se e volta a ser discutida vezes sem conta. Custa tempo e gera frustração. - Um bom registo não conta só a solução escolhida. Conta o contexto e o que foi posto de lado. - Chega um formato simples de 5 secções, guardado onde alguém o procuraria no momento da dúvida. - Documentar não é burocracia. É respeito pelo tempo futuro da tua equipa e pelo teu. Há 6 meses decidimos não usar um determinado plugin de cache num projeto. Discutimo-lo numa reunião, chegámos a um consenso e seguimos em frente. Na semana passada, um programador acabado de entrar perguntou porque é que não o usávamos e propôs instalá-lo. Passei 20 minutos a explicar algo que já tínhamos decidido. Não é o fim do mundo, mas esses 20 minutos não voltam. Multiplica isso por cada decisão técnica de um projeto de vários meses e por cada pessoa que entra. O resultado são dias inteiros de conversas repetidas. Documentar decisões técnicas não é burocracia desnecessária. É um seguro contra o esquecimento. E o esquecimento sai caro. ## Porque é que as decisões se perdem (e porque é que isso dói) Nas equipas de desenvolvimento, as decisões técnicas têm uma vida média curta. Os motivos são previsíveis: **Rotação da equipa.** Quem tomou a decisão já não está. Quem chega não tem o contexto e parte do princípio de que a decisão atual não tem razão de ser. **Distância no tempo.** Há 8 meses decidiste não usar React porque o projeto não o justificava. Agora cresceu e alguém propõe migrar. E tu ficas na dúvida: foi uma decisão consciente ou é que, na altura, ninguém na equipa dominava React? **Mudança de contexto.** As decisões tomam-se com a informação disponível em cada momento. Essa informação muda, e a decisão deveria ser revista. Mas, se não sabes o que a motivou, não consegues saber se a mudança é relevante. **Comunicação informal.** “Falámos disso no Slack”, “ficou decidido na reunião”, “isso sabe o João”. O Slack perde-se no scroll infinito, as reuniões não são gravadas e o João foi para outra empresa. ## O que é um bom registo de decisões Na Baqueiro usamos um formato simples a que chamamos Decision Record (DR). Não é uma invenção nossa: baseia-se nos Architecture Decision Records (ADR), uma prática bastante difundida no setor, simplificada para equipas pequenas. Cada DR tem 5 secções: **1. Contexto.** Que problema estávamos a resolver? Que restrições tínhamos (orçamento, prazos, conhecimento da equipa)? Que alternativas avaliámos? **2. Decisão.** O que escolhemos? Tem de ser concreta: “vamos usar Laravel com Laravel Nova para o painel de administração”, não “uma solução moderna”. **3. Consequências.** O que ganhamos e o que perdemos? Todas as decisões têm contrapartidas, e um bom DR é honesto sobre elas. **4. Data e participantes.** Quando foi tomada e quem participou? Assim sabes a quem perguntar se surgirem dúvidas. **5. Estado.** Está em vigor, foi substituída ou revista? As decisões mudam, e o DR tem de o refletir. ## Onde guardamos os Decision Records O formato importa, mas a localização importa mais. Um DR num documento que ninguém abre não serve para nada. Guardamo-los em 3 sítios, consoante a sua natureza: **Decisões de um projeto concreto:** no próprio repositório, numa pasta /docs/decisions/. Junto ao código e versionadas com ele. É a primeira coisa que vês ao entrar no projeto. **Decisões de arquitetura transversais:** na wiki da equipa, organizadas por área (frontend, backend, infraestrutura), porque afetam todos os projetos. **Decisões sobre ferramentas e processos:** no Notion, junto aos procedimentos internos. Por exemplo, porque usamos Figma e não Sketch. A regra é simples: a documentação tem de estar onde alguém a procuraria naturalmente no momento em que tem a dúvida. ## Quando criar um Decision Record Não documentamos tudo, porque seria paralisante. Criamos um DR quando: - A decisão é difícil de reverter (framework, base de dados, arquitetura de serviços). - Esperamos que alguém a ponha em causa mais tarde (novas entradas no projeto, crescimento). - Há alternativas razoáveis que outros poderiam propor, e queremos deixar claro porque as pusemos de lado. - A decisão afeta o trabalho de outras pessoas (processos, ferramentas partilhadas). Não criamos DR para decisões triviais (usar snake_case nas tabelas), óbvias (usar HTTPS) nem para aquilo que o próprio código já explica. ## Um exemplo de Decision Record Este DR baseia-se num dos nossos projetos, anonimizado e ligeiramente simplificado: > **DR-014: Não vamos usar Elasticsearch para a pesquisa de produtos** > > > > *Data:* setembro de 2024 > > > > *Participantes:* direção técnica, responsável de backend, responsável de sistemas > > > > *Contexto:* O cliente tem cerca de 3000 produtos e quer pesquisa avançada (filtros combinados, ordenação por relevância). A equipa de backend propôs implementar Elasticsearch para melhorar o desempenho e as capacidades de pesquisa. > > > > *Decisão:* Vamos usar a pesquisa nativa do MySQL com índices otimizados. Não vamos implementar Elasticsearch nesta fase. > > > > *Razões:* > > > > - Um catálogo de 3000 produtos está folgadamente dentro do que o MySQL com bons índices resolve bem. > - O Elasticsearch complicaria o deploy: exige um servidor adicional ou um serviço gerido. > - A equipa não tem experiência a operar Elasticsearch em produção, e o risco de problemas de infraestrutura supera hoje os benefícios. > - O cliente não tem orçamento para a infraestrutura adicional. > > > > *Consequências:* > > > > - Pesquisamos com índices FULLTEXT do MySQL e consultas otimizadas. O desempenho é aceitável para o volume atual. > - Não vamos ter pesquisa tolerante a erros de digitação nem um cálculo de relevância avançado. > - Se o catálogo ultrapassar os 10 000 produtos ou o cliente precisar de uma pesquisa mais sofisticada, será preciso reconsiderar. > > > > *Estado:* Em vigor. Rever se o catálogo ultrapassar os 10 000 produtos ou se o cliente pedir funcionalidades de pesquisa que o MySQL não consiga oferecer. Uns meses depois, alguém perguntou: “porque é que não usamos Elasticsearch?”. Enviámos-lhe a ligação para o DR-014. A conversa durou 3 minutos, não 30. A decisão manteve-se porque o contexto não tinha mudado. ## Como manter os Decision Records atualizados Um DR desatualizado é pior do que não ter nenhum, porque dá uma falsa segurança sobre uma decisão que já não se aplica. A nossa regra: sempre que alguém põe em causa uma decisão documentada, o respetivo DR é revisto. - Se se mantém, acrescenta-se uma linha: “revisto em [data], contexto sem alterações”. - Se muda, marca-se como substituído e cria-se um novo que explique o contexto atual e tenha uma ligação para o anterior. Assim vai-se formando um histórico que tem valor por si só: vês como a arquitetura evoluiu e porquê. Para integrar alguém novo no projeto, vale ouro. É a mesma lógica que aplicamos às automatizações, onde a falta de documentação transforma qualquer alteração em arqueologia, como explicamos em [o custo oculto das automatizações mal documentadas](https://baqueiro.es/pt/automatizacion/custo-automatizacoes-mal-documentadas/). ## Objeções habituais **“Não temos tempo para isto.”** Escrever um DR leva de 10 a 20 minutos. Discutir a mesma decisão 3 vezes porque não ficou por escrito leva horas. É matemática. **“O código já é documentação suficiente.”** O código explica o que se fez, não porquê. E o porquê é precisamente o que se esquece e o que mais custa reconstruir. **“Ninguém lê a documentação.”** Se não é lida, o problema é onde está ou como está organizada, não a documentação em si. Um DR no repositório aparece naturalmente quando alguém trabalha nessa parte do código. **“As decisões mudam constantemente, acabaríamos com um caos de documentos desatualizados.”** Se algo muda constantemente, não devia ser um DR. Os DR são para decisões com consequências duradouras. O que muda todas as semanas é configuração, não arquitetura. ## Perguntas frequentes ### O cliente deve ver os Decision Records? Depende. Os que afetam decisões de negócio, sim. Os puramente internos, não. Para clientes com perfil técnico mantemos uma versão resumida. ### O que acontece se alguém ignorar um DR e fizer o que lhe apetece? Os DR não são leis, são o registo de um consenso. Se alguém quer mudar uma decisão, discute-se e atualiza-se o DR. Ignorá-lo é um problema de cultura de equipa, não de documentação. ### Precisamos de uma ferramenta especial? Não. Um ficheiro Markdown no repositório funciona perfeitamente. O importante é o hábito, não a ferramenta. Se queres começar hoje, cria a pasta, escreve o DR da última decisão que a tua equipa tenha discutido 2 vezes e numera-o como DR-001. ## Conclusão Documentar decisões técnicas não é uma desculpa para não as tomar, nem burocracia para justificar o que já existe. É respeito pelo tempo futuro: o teu, quando não te lembrares porque fizeste algo; o da tua equipa, quando alguém entrar num projeto já começado; e o de quem herdar o código daqui a uns anos. Se a tua equipa perde tempo a discutir decisões que já foram tomadas, ou se entras em projetos sem perceber porque estão feitos assim, talvez te falte um sistema de Decision Records. Na Baqueiro podemos ajudar-te a implementá-lo sem complicar a tua forma de trabalhar. [Conta-nos como trabalha hoje a tua equipa](https://baqueiro.es/pt/contacto/).