Toda vez que você formata a máquina, abre aquele README de trinta passos e começa a copiar comando por comando. No passo 14 algo quebra, você improvisa, esquece de anotar, e seis meses depois o próximo dev (ou você mesmo) sofre de novo. Setup manual não é produtividade — é dívida técnica que você paga com o seu tempo.
O setup manual é uma fábrica de bug silencioso
O problema do passo a passo no braço não é a chatice, é a divergência. Você instala a versão 20 do Node, o colega pega a 18, o CI roda na 22. Ninguém está errado no README — o README simplesmente não descreve o que realmente está rodando em cada máquina.
Cada ajuste manual é um estado que ninguém versiona. "Ah, tive que exportar uma variável no zshrc" vira conhecimento tribal, some quando a pessoa sai, e reaparece como um bug de duas horas. A pergunta certa não é "como instalo isso?" e sim "como faço a máquina se instalar sozinha?".
Bootstrap idempotente: rode dez vezes, dá no mesmo
A peça central é um script de bootstrap — um setup.sh (ou .ps1) que leva a máquina do zero ao ambiente pronto. A regra de ouro é idempotência: rodar uma ou dez vezes tem que dar exatamente o mesmo resultado, sem duplicar linha no arquivo nem quebrar se a ferramenta já existe.
Na prática isso é checar antes de agir:
if ! command -v gh >/dev/null 2>&1; then
brew install gh
fi
Gerenciadores de pacote ajudam porque já são idempotentes: brew install num pacote existente não faz estrago. O inimigo é o >> que acrescenta cego — rode duas vezes e seu .zshrc ganha a mesma linha duplicada. Prefira gerar o arquivo inteiro a partir de um template a ir empilhando echo.
Deixe o gerenciador de pacotes fazer o serviço sujo
Baixar .dmg, arrastar para Aplicativos, aceitar licença — nada disso escala nem se automatiza bem. Um gerenciador de pacotes transforma instalação em uma lista declarativa: você diz o que quer, ele resolve o como.
- macOS: Homebrew, com um
Brewfileque lista tudo (brew bundle). - Linux: apt/dnf/pacman para o sistema, mais um gerenciador de versão (asdf, mise) para linguagens.
- Windows: winget ou Scoop, que finalmente dão um caminho scriptável de verdade.
A vantagem some se você continuar instalando "aquele uns três à parte" na mão. Se entrou no ambiente, entra na lista. O Brewfile (ou equivalente) vira a fonte de verdade do que sua máquina precisa — e um diff no Git conta a história de cada mudança.
Dotfiles no Git: sua config para de morar só na sua cabeça
Seu .zshrc, .gitconfig, config do editor, aliases — isso é código, trate como código. Um repositório de dotfiles versiona sua configuração e deixa você reproduzi-la em qualquer lugar com um git clone e um symlink.
Não precisa de framework: uma pasta no Git e um script que cria os links simbólicos (ln -sf) já resolve 90% dos casos. O ganho real não é backup — é histórico. Quando um alias começa a se comportar estranho, git log te mostra o que mudou e quando. E separe o que é público do que é segredo: token e chave privada não entram no repo; use um .env local, um cofre, ou variáveis do sistema.
Se não passou em máquina limpa, não existe
Aqui mora a armadilha: seu script "funciona" porque a sua máquina já tem metade das coisas instaladas. A única prova de que o bootstrap funciona é rodá-lo num ambiente limpo, onde nada é pressuposto.
Você tem opções baratas: um container Docker (docker run -it ubuntu bash), uma VM descartável, ou — o mais honesto — um job de CI que sobe do zero e roda seu setup.sh a cada push. Se o GitHub Actions consegue instalar seu ambiente numa imagem virgem, qualquer colega novo também vai conseguir. É o mesmo princípio de um teste automatizado: sem execução em ambiente controlado, é só esperança.
Comece pequeno, hoje
Não pare o mundo pra construir a automação perfeita. Da próxima vez que você resolver algo na mão, gaste dois minutos a mais e jogue o comando num setup.sh. Na semana seguinte, mova seu .zshrc pra um repo. Depois, rode o script num container e veja o que quebra.
Em pouco tempo você troca o README de trinta passos por um comando só — e a máquina nova fica produtiva antes de você terminar o café.