Todo mundo julga um repositorio pela raiz. Se a primeira tela do ls ja da vontade de fechar a aba, o resto do projeto vai doer. Organizar projeto nao e firula: e o que decide se alguem contribui em uma hora ou em uma semana.
A raiz do projeto e a primeira impressao
A raiz e a capa. Quem chega abre ela antes de qualquer arquivo. Deixa poucas coisas ali: README, licenca, config de lint/format, o gerenciador de pacotes e as pastas de topo. Config espalhada e cinquenta arquivos soltos na raiz sao ruido — e ruido esconde o que importa.
Pastas por dominio, nao por tipo
O erro classico e agrupar por tipo tecnico: controllers/, services/, models/. Funciona no tutorial, vira caca ao tesouro no projeto real, porque uma unica feature fica espalhada em cinco pastas.
Agrupe por dominio: cobranca/, usuarios/, relatorios/. Cada pasta conta o que o sistema faz, nao como foi codado. Bonus: mexer numa feature toca uma pasta, e a estrutura vira documentacao gratis do negocio.
Monorepo ou multirepo: escolha, nao torca
Monorepo: tudo num repo, um historico, refactor atravessa pacotes de uma vez. Otimo enquanto o time e o CI aguentam.
Multirepo: cada servico no seu canto, deploy e dono independentes — ao custo de versionar o contrato entre eles.
Nao tem vencedor universal. Time pequeno com codigo acoplado: monorepo. Servicos com ciclos de vida distintos e donos separados: multirepo. O unico pecado e nao decidir e deixar o acaso escolher por voce.
README e docs: o mapa fica na raiz
Um README que so repete o nome do projeto e desperdicio. Ele responde tres perguntas: o que e isso, como eu rodo, onde acho o resto. Um comando de setup que funciona em copia-e-cola vale mais que qualquer paragrafo bonito.
Documentacao mais longa vai pra docs/, linkada do README. O README e o mapa; docs/ e o territorio. Se o mapa esta escondido, ninguem acha o caminho.
Convencoes que rodam sozinhas
Regra que depende de alguem lembrar nao existe. Coloca linter e formatter no repo, rodando no commit (pre-commit) e no CI. Adota um padrao de commit — Conventional Commits resolve — pra o historico virar changelog quase de graca.
A ideia e simples: a maquina cobra a convencao, nao o colega no PR. Discussao de virgula em code review e tempo que ninguem recupera.
Scripts padronizados e o teste do onboarding
Todo projeto precisa dos mesmos verbos: instalar, rodar, testar, buildar. Use os mesmos nomes em todo repo (setup, dev, test, build), nao importa a stack por baixo. Ninguem deveria decorar o comando magico especifico de cada projeto.
O teste final e o onboarding: entrega o repo pra quem nunca viu e cronometra ate rodar local. Travou em algum passo? Ali esta o buraco da sua estrutura, apontado por um usuario real.
Repositorio bom nao e o que voce entende. E o que o proximo entende sem precisar te chamar no chat.
