Você troca de notebook, formata a máquina ou entra num time novo. E lá se vão dois dias reinstalando coisa, caçando aquele alias que você jurou que nunca esqueceria e descobrindo, no pior momento, que o projeto roda em Node 18 e você instalou o 22. Reprodutibilidade não é luxo de quem tem TOC. É o que separa um dev que volta a produzir em minutos de um que volta em dias.
O problema não é a máquina, é a memória
Ambiente de dev é conhecimento que mora na sua cabeça e evapora. Cada export, cada brew install, cada ajuste no .bashrc é uma decisão que você não vai lembrar daqui a seis meses. A meta é simples: transformar esse conhecimento tácito em arquivos versionados. Se está num repositório, sobrevive à formatação.
Dotfiles: seu ambiente em um repositório
Seus arquivos de configuração — .zshrc, .gitconfig, .vimrc, aliases — são os dotfiles. Coloque-os num repositório Git e você tem seu shell inteiro versionado. A técnica mais limpa é o bare repo apontando para a home, mas para começar basta uma pasta ~/dotfiles com um script que cria os symlinks:
ln -sf ~/dotfiles/zshrc ~/.zshrc
ln -sf ~/dotfiles/gitconfig ~/.gitconfig
Máquina nova? git clone, roda o script, e seu terminal é o de sempre. Ferramentas como chezmoi e stow automatizam isso e ainda lidam com diferenças entre máquinas (trabalho vs. pessoal). Só não caia na tentação de versionar segredo junto — já chegamos lá.
Version managers: pare de brigar com versões
Instalar Node, Python ou Ruby direto no sistema é pedir para quebrar. Cada projeto quer uma versão, e o sudo global vira campo minado. Version managers resolvem isso: nvm para Node, pyenv para Python, rbenv para Ruby.
Melhor ainda: o asdf (ou o mise, seu sucessor mais rápido) unifica tudo num só. Você declara as versões num arquivo .tool-versions na raiz do projeto:
nodejs 20.11.0
python 3.12.2
Entrou na pasta, o ambiente troca sozinho para as versões certas. Comita esse arquivo e o time inteiro roda o mesmo runtime — chega de "na minha máquina funciona".
Containers e devcontainers: a máquina é descartável
Version manager resolve linguagem. Mas e o Postgres, o Redis, aquela lib de sistema chata de instalar? É aí que containers entram. Um docker-compose.yml no repositório sobe banco e dependências com um comando, iguais para todo mundo, sem poluir sua máquina.
Os devcontainers vão além: você descreve o ambiente inteiro num .devcontainer/devcontainer.json e o VS Code (ou o GitHub Codespaces) monta um container com tudo pronto — extensões, ferramentas, versões. O onboarding vira "abre o projeto e espera o build". A máquina física passa a ser só um cliente burro; o ambiente vive no repositório.
Segredos e .env: onde a maioria se queima
Regra número um: .env nunca vai para o Git. Coloque .env no .gitignore antes do primeiro commit, não depois — segredo que já foi pro histórico continua lá mesmo se você apagar o arquivo.
O padrão sério é versionar um .env.example com as chaves mas sem os valores:
DATABASE_URL=
API_KEY=
Assim o próximo dev sabe o que precisa preencher sem você vazar nada. Para segredos de verdade, use um gerenciador — 1Password CLI, doppler, sops — que injeta os valores na hora de rodar, sem deixar rastro em disco. E se um segredo vazou pro histórico, rotacione a chave. Apagar o commit não desfaz o vazamento.
O teste de fogo: monte tudo do zero
A prova de que seu ambiente é reprodutível é brutalmente simples: pegue uma máquina limpa (ou um container) e monte tudo seguindo só o que está no repositório. Se travou em algum passo, esse passo é conhecimento que ainda mora só na sua cabeça — documente ou automatize.
Comece pequeno: hoje, mova seus dotfiles para um repo. Amanhã, adote um version manager. Semana que vem, escreva o docker-compose. Não precisa da configuração perfeita — precisa de uma que você consiga reconstruir. Porque a próxima máquina nova vem aí, e a diferença entre café quente e café frio é o quanto você automatizou antes.