Por Que Todo Repositório Deveria Ter uma Pasta docs/solutions
Um dev que entra no projeto daqui a seis meses não precisa do changelog. Precisa saber por que a decisão foi tomada e o que quase deu errado.
docs/solutions/ é a resposta mais simples possível para isso: um diretório no repositório, versionado junto ao código, documentando o que foi aprendido em vez do que foi feito.
O problema que ela resolve
Toda equipe carrega conhecimento tribal. "Por que usamos LVM-thin aqui e não ZFS?" — o engenheiro que tomou essa decisão oito meses atrás sabe. Quando ele sai, o conhecimento vai junto.
Confluence e Notion capturam documentação de projeto, mas não sobrevivem ao contexto do momento. Não há o commit que gerou o problema, nem a data em que a decisão foi tomada, nem o PR que implementou a correção.
O resultado prático: equipes refazem análises que já foram feitas, repetem os mesmos erros em contextos parecidos e onboardam gente nova via "pergunta para o fulano" — que não escala.
A convenção
Cada arquivo documenta um problema resolvido ou um blocker superado. A estrutura mínima:
# [Título descritivo do problema resolvido — não genérico]
## Context
Quando isso acontece. Quem encontra. Em que estado o sistema está.
## Problem
O que estava bloqueando. Por que não era trivial resolver.
## Solution
O que funcionou. Comandos exatos quando relevante.
## Why This Approach
Por que esta e não as alternativas óbvias.
Alternativas consideradas e por que foram descartadas.
## Prerequisites
O que precisa estar pronto antes.
Por que não as alternativas
Confluence por projeto serve para documentação formal, mas fica desconectado do código. Sem rastreabilidade commit↔doc, e desatualiza porque não existe atrito nenhum impedindo você de criar uma página inconsistente.
Wikis do GitHub/GitLab vivem fora do repositório principal. Não aparecem num grep local e não há CI para validá-las.
Comentários no código são legíveis em contexto, mas não são pesquisáveis por problema, e não capturam o raciocínio de nível superior — a parte do "por que esta abordagem".
docs/solutions/ vence porque fica no repositório: versionado com o código, pesquisável com rg, linkável de commits e tickets.
Quatro razões pelas quais funciona
- Versionado com o código. O commit que resolve o problema carrega a documentação. Doze meses depois,
git log --all -- docs/solutions/X.mdconta a história inteira. - Linkável. Uma linha
Refs: docs/solutions/blockers-report.md#B2numa mensagem de commit cria rastreabilidade real entre a decisão e sua justificativa. - Pesquisável. Está no repositório. Aparece no
rg "LVM-thin", na busca do GitHub, no seletor de arquivos do editor. Sem browser, sem troca de contexto. - Alimenta o grafo. Cada arquivo vira uma nota
literatureno Zettelkasten, então o conhecimento do repositório aterra no conhecimento pessoal permanente em vez de ficar preso a um projeto só.
O que custa
Você ganha um onboarding drasticamente mais rápido, decisões passadas consultáveis antes de refazer o trabalho e — como efeito colateral — posts que emergem naturalmente, já que cada arquivo de solution é um rascunho pronto.
Você paga com disciplina. O PR que resolve um problema também precisa criar o arquivo. Sem enforcement a convenção degrada, e há o risco de virar um log de troubleshooting sem estrutura se ninguém seguir o template.
Como isso falha
Vira um Stack Overflow pessoal. Arquivos que são só dumps de comandos sem raciocínio. O diagnóstico é simples: se ## Why This Approach está vazia, não é uma solution — é um gist.
Fica obsoleto. O arquivo documenta um workaround que depois foi resolvido de outro jeito, mas ninguém atualizou. Adicione uma linha ## Status: superseded by X quando a abordagem mudar.
Granularidade errada. Um arquivo por comando é fino demais; um arquivo cobrindo "todos os problemas de deploy" é grosso demais. A heurística: um problema num contexto específico equivale a um arquivo.
O que eu aprendi
O template mínimo importa mais do que o template perfeito. Cinco seções preenchidas pela metade valem mais do que um formato elaborado que ninguém usa.
## Why This Approach é a seção mais valiosa e a mais pulada. Forçá-la — mesmo que a resposta seja só "porque as alternativas A e B falharam pelo motivo X" — é o que separa documentação de arquivamento.
E nomeie os arquivos de forma descritiva. windows-terminal-ssh-fragments.md é encontrável; solution-001.md exige um índice que ninguém mantém.