Przenośność setupu — repo dotfiles + bootstrap script

Q23 · Operations & hygiene Jak przenosisz swój setup (CLAUDE.md, hooks, skills) między maszynami?

Maksymalna odpowiedź: “Repo dotfiles obejmujące ~/.claude, ~/.codex, ~/.agents, ~/.cursor + bootstrap script.”

Dlaczego to ważne: Twój setup to twoja produktywność. Traktowanie go jak coś jednorazowego to traktowanie swojej przewagi jak coś jednorazowego.

Dlaczego to ważne w 2026

Czas życia maszyny developera w 2026 jest krótszy niż kiedykolwiek. MacBook kupiony w lutym idzie na wymianę na korporacyjny sprzęt w maju; europejski reset firmowych laptopów wprowadzony pod regułami higieny urządzeń zgodnymi z DORA wymusza ponowny image co dwanaście miesięcy; twój domowy Linux pada; cloud workspace w Codespaces lub Coder jest odbudowywany każdej nocy; uruchamiasz microVM Vercel Sandbox na jeden run agenta i niszczysz go cztery godziny później. W każdym z tych momentów jedyną rzeczą stojącą między tobą a produktywną pierwszą godziną na nowej maszynie jest to, czy twój setup — CLAUDE.md, hooks, skills, konfiguracje MCP, aliasy shellowe, reguły Cursor, profil Codex — wędruje razem z tobą, czy musisz odtwarzać go z pamięci.

Dla mediany developera w 2024 “przenoszenie setupu” oznaczało .zshrc i .gitconfig. Dla developera wspomaganego AI w 2026 oznacza to rząd wielkości więcej stanu: 600-liniowy ~/.claude/CLAUDE.md z trudno wypracowanymi regułami obowiązującymi we wszystkich projektach, katalog ~/.claude/hooks/ z pięcioma czy sześcioma skryptami bash, które gatekeepują commity i triggerują tworzenie PR-ów, drzewo ~/.claude/skills/ z dwudziestoma plus folderami skillów, które sam napisałeś lub sforkowałeś, ~/.codex/config.toml z profilami providerów i politykami zatwierdzania, ~/.cursor/rules.json i ustawienia .cursor-tutor, katalog ~/.agents/ z konfiguracjami MCP per agent i allowlistami narzędzi, oraz ~/.config/claude-code/ z nadpisaniami telemetrii i feature flagami. Odtwarzanie tego ręcznie na każdej nowej maszynie to nie kilka godzin — to dni powolnej rekonstrukcji, z najgorszym rodzajem tarcia “wiem, że miałem na to regułę” za każdym razem, gdy uderza w ciebie znajomy bug, który twój stary setup obsługiwał po cichu.

To dlatego Q23 siedzi w sekcji Operations & hygiene i dlatego maksymalna odpowiedź jest bezkompromisowa: nie “mam repo dotfiles z moim zshrc”, ale wersjonowane repo dotfiles obejmujące każdy katalog narzędzi AI, sparowane z bootstrap scriptem, który doprowadza świeżo zaimagowaną maszynę do “gotowa do pracy” jedną komendą. Cokolwiek mniej to zostawianie produktywności na stole, oraz — coraz częściej — zostawianie wiedzy instytucjonalnej na stole, gdy onboardujesz osobę z zespołu, która skorzystałaby z twojego CLAUDE.md i skillów.

Jak naprawdę wygląda maksymalny wynik

Setup z maksymalnym wynikiem w Q23 ma jedno repozytorium na GitHubie (prywatne lub publiczne — twoja decyzja), z deterministycznym layoutem, idempotentnym bootstrap scriptem i zerem sekretów w commitach. Świeża maszyna — macOS, Linux albo Codespace — uruchamia jednolinijkowy bootstrap, a dziesięć minut później piszesz w Claude Code z pełnym CLAUDE.md, twoje hooks odpalają, twoje skills są dostępne, twoje profile Codex są skonfigurowane, twoje reguły Cursor zaaplikowane, a twój shell zachowuje się dokładnie tak, jak na każdej innej maszynie, którą posiadasz.

Oto layout, który wygrywa:

~/dotfiles/
├── README.md                       # jak zbootstrapować, plus manifest tego, co śledzone
├── bootstrap.sh                    # idempotentny installer — bezpieczny do uruchomienia dwa razy
├── home/                           # pliki mirrorowane do $HOME
│   ├── .zshrc
│   ├── .gitconfig
│   ├── .gitignore_global
│   ├── .config/
│   │   ├── claude-code/            # feature flagi, telemetria
│   │   ├── ghostty/
│   │   └── starship.toml
│   ├── .claude/
│   │   ├── CLAUDE.md               # twoje globalne instrukcje dla agenta
│   │   ├── settings.json           # model, hooks, allowlist (bez sekretów)
│   │   ├── hooks/                  # *.sh — pre-commit, stop-hooks, itd.
│   │   ├── skills/                 # twoje autorskie skills (jeden folder każdy)
│   │   └── commands/               # slash commands
│   ├── .codex/
│   │   ├── config.toml             # approval_policy, model_provider, profiles
│   │   ├── instructions.md         # globalne instrukcje Codex
│   │   └── prompts/                # nazwane prompty
│   ├── .cursor/
│   │   ├── rules.json              # globalne reguły Cursor
│   │   └── mcp.json                # serwery MCP (tylko op:// references)
│   └── .agents/
│       ├── mcp/                    # współdzielone konfiguracje serwerów MCP
│       └── allowlists/             # allowlisty narzędzi per agent
├── machine-overrides/              # szablonowane delty per host (chezmoi/yadm)
│   ├── default.yaml
│   ├── work-laptop.yaml
│   └── home-linux.yaml
└── .gitignore                      # blokuje *.key, *.pem, .env, sessions/

Towarzyszący bootstrap.sh jest głupi z premedytacją — płaski skrypt bash, który każde przyszłe ty przeczyta w 30 sekund:

#!/usr/bin/env bash
set -euo pipefail

# 1. Zainstaluj package managery + podstawowe narzędzia
if [[ "$OSTYPE" == "darwin"* ]]; then
  command -v brew >/dev/null || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  brew bundle --file=./Brewfile
else
  sudo apt-get update && sudo apt-get install -y zsh git curl ripgrep fd-find fzf
fi

# 2. Zainstaluj tooling agenta (idempotentnie — re-runs bezpieczne)
curl -fsSL https://claude.ai/install.sh | bash
curl -fsSL https://openai.com/codex/install.sh | bash
command -v cursor-agent >/dev/null || npm install -g @cursor/cli

# 3. Linkuj lub kopiuj śledzone pliki do $HOME (chezmoi obsługuje to, jeśli go używasz)
chezmoi init --apply --source="$(pwd)/home"

# 4. Uwierzytelnij się w secret managerze (NIGDY nie zapisuj tutaj sekretu)
op signin || echo "Uruchom 'op signin' raz interaktywnie po zakończeniu bootstrapu."

# 5. Trigger jednorazowego sanity check
claude doctor || true
codex --version
cursor-agent --version
echo "Bootstrap zakończony. Otwórz nowy shell."

To wszystko. Bez magii, bez własnościowej warstwy instalacyjnej, bez 800-liniowego provisionera. Zasada brzmi: “jeśli skrypt wywali się w połowie, masz przeczytać i naprawić linijkę, która padła.” Wszystko, co chce być sprytne — templatowanie, szyfrowanie, delty per maszyna — żyje wewnątrz dotfile managera (chezmoi lub yadm), a nie wewnątrz bootstrapu.

Aktualny krajobraz (zweryfikowany przez web search)

chezmoi (templatowany, machine-specific)

chezmoi to konsensusowy zwycięzca w 2026 dla każdego, kto ma więcej niż jedną maszynę. Śledzi katalog source w gicie, renderuje szablony Go (z OS, hostname i arch jako wejściami) do twojego $HOME i wspiera natywne szyfrowanie z age lub gpg dla tych nielicznych plików, które muszą być w repo, ale nie w plaintekście. Pliki są śledzone po ich nazwie docelowej — dot_claude/CLAUDE.md w source staje się ~/.claude/CLAUDE.md po apply — co utrzymuje repo przeglądalne na GitHubie. Pisemny przewodnik z 2026 roku na Zenn Standardizing AI Agent Instructions and Permission Management with chezmoi and Hooks prowadzi przez użycie chezmoi konkretnie do zarządzania konfigami Claude Code i Codex z szablonami, które interpolują nazwę maszyny w allowlisty i skrypty hooków. Jednolinijkowy bootstrap (sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply your-github-handle) klonuje, templatuje i aplikuje w jednym kroku — i jest rerunnable.

Kiedy wybrać chezmoi: masz więcej niż jedną maszynę, maszyny różnią się w realny sposób (praca vs osobiste, macOS vs Linux, x86 vs Apple Silicon) i chcesz, by niektóre pliki (jak ~/.claude/CLAUDE.md) były w 90% identyczne z deltami per maszyna na górze.

yadm (git-based)

yadm to cienki wrapper wokół gita, który operuje bezpośrednio na $HOME. Tam, gdzie chezmoi ma podział source-target, yadm śledzi pliki w miejscu — yadm add ~/.claude/CLAUDE.md dodaje żywy plik do zarządzanego przez yadm bare repo w ~/.local/share/yadm/repo.git. Wspiera nadpisania per host przez sufiksy w nazwach plików (.zshrc##os.Darwin, .zshrc##hostname.work-mbp), pliki szyfrowane gpg przez yadm encrypt i bootstrap hooks przez ~/.config/yadm/bootstrap. Jest lżejszy niż chezmoi koncepcyjnie — jeśli już mówisz płynnie po gicie, yadm wydaje się 30-sekundową krzywą uczenia — ale historia templatowania jest słabsza. Nie ma szablonów Go; wszystko per-maszyna to alternatywny plik.

Kiedy wybrać yadm: masz jedną lub dwie maszyny, znasz git bardzo dobrze, a twoje delty per maszyna są na tyle małe, że da się je wyrazić jako alternatywy.

Plain git symlinking (np. `stow`, własnoręczny)

Najstarszy wzorzec: zwykłe repo gitowe, z plikami w ich śledzonej strukturze, symlinkowane do $HOME przez stow, dotbot lub ręczny skrypt. To najprostsza rzecz, która działa i ma najniższy overhead mentalny — to, co widzisz w repo, to to, co jest na dysku. Kosztem jest to, że delty per maszyna zamieniają się w branche, warunkowy sourcing w .zshrc lub copy-paste między podobnymi plikami. Dla czystych konfiguracji narzędzi AI, które są w 100% identyczne między maszynami (twój ~/.claude/CLAUDE.md, twój ~/.codex/instructions.md, twój folder skillów), plain symlinking jest w porządku i daje maksymalną przenośność — twoje repo działa z lub bez jakiegokolwiek konkretnego narzędzia dotfile zainstalowanego. natelandau/dotfiles to dobre repo referencyjne w tym stylu.

Kiedy wybrać plain git: masz jedną maszynę albo wszystkie twoje maszyny mają identyczny OS / arch i nie potrzebujesz delt per host, a wolisz transparentne narzędzia niż feature-rich.

Co uwzględnić z narzędzi AI

Śledź te w swoich dotfiles, w tej kolejności priorytetu:

~/.claude/CLAUDE.md — twoje globalne instrukcje dla Claude Code. Najbardziej wartościowy pojedynczy plik w całym twoim setupie developera w 2026. Jeśli masz trudno wypracowane reguły typu “zawsze czytaj plik przed edycją”, “nigdy nie uruchamiaj destrukcyjnych komend gita bez zgody”, “auto-PR po znaczącej pracy”, żyją one tutaj.
~/.claude/settings.json — preferencja modelu, allowlisty, rejestracja hooków. Usuń najpierw sekrety; używaj referencji op:// dla wszystkiego wrażliwego.
~/.claude/hooks/ — każdy skrypt shellowy, który gatekeepuje lub augmentuje twoje sesje Claude Code. Stop hook auto-pr-watch.sh, twoje pre-edit hooks, twoje file-saved hooks. To jest executable code i absolutnie powinien być wersjonowany.
~/.claude/skills/ — twoje autorskie skills, jeden folder każdy z SKILL.md + plikami wspierającymi. To twoja osobista ekspertyza zakodowana dla agenta.
~/.claude/commands/ — twoje slash commands.
~/.codex/config.toml i ~/.codex/instructions.md — profile providerów Codex, polityki zatwierdzania i twoje globalne instrukcje.
~/.codex/prompts/ — nazwane szablony promptów.
~/.cursor/rules.json — reguły Cursor (globalne reguły dla edycji inline i trybu agenta).
~/.cursor/mcp.json — rejestr serwerów MCP w Cursor, z referencjami op:// dla wszelkich tokenów.
~/.agents/ — współdzielone konfiguracje serwerów MCP, allowlisty narzędzi i inny cross-agent state.
~/.config/claude-code/ — nadpisania telemetrii, feature flagi, beta opt-iny.
Szablony .mcp.json — trzymaj startowy .mcp.json w dotfiles/templates/, żeby nowe projekty bootstrapowały serwery MCP z znanej-dobrej bazy.

Czego NIE uwzględniać

Tak samo ważne. To kategorie, które psują się w momencie, gdy trafią do publicznego lub nawet prywatnego repo:

Sekrety w jakiejkolwiek formie. Żadnego OPENAI_API_KEY=sk-..., żadnych tokenów GitHub w settings.json, żadnych admin keys Anthropic w konfigach MCP. Jeśli plik referencjuje sekret, powinien referencjować op://Personal/openai/credential (lub odpowiednik twojego secret managera), a secret manager obsługuje rozwiązywanie w runtime. Zobacz Q22 dla pełnego wzorca.
Cookies i session tokens. Żadnego .config/gh/hosts.yml, jeśli zawiera session token. Żadnego ~/.claude/sessions/. Żadnego .cursor-tutor, jeśli przechowuje auth.
Stan specyficzny dla maszyny. Katalogi cache (~/.claude/cache/), logi (~/.claude/logs/), ID telemetrii (~/.config/claude-code/machine-id), historia runów Codex. Nic z tego nie powinno za tobą podążać między maszynami — to szum w najlepszym wypadku, fingerprinting w najgorszym.
Tożsamość osobista różna per maszyna. Klucze hostowe SSH (per maszyna), nazwy hostów systemowych, aliasy mDNS.
Wszystko, czego nie chciałbyś, żeby teammate znalazł, jeśli udostępnisz mu URL repo jutro. Uruchom gitleaks detect i trufflehog filesystem . na repo przed pushem.

.gitignore, który łapie typowych winowajców dla drzewa narzędzi AI:

# Narzędzia AI — nigdy nie śledź tych
**/sessions/
**/cache/
**/logs/
**/.history/
**/auth.json
**/credentials.json
**/*.key
**/*.pem
.env
.env.local

Wdrożenie krok po kroku

Utwórz repo, zdecyduj o managerze. Stwórz nowe repo GitHub o nazwie dotfiles (prywatne, jeśli zawiera cokolwiek, czego wolałbyś nie pokazywać, publiczne, jeśli chcesz mieć je jako portfolio — większość ludzi wybiera prywatne). Zdecyduj między chezmoi (templatowanie), yadm (git-in-$HOME) lub plain stow-style symlinking. Jeśli niepewny, wybierz chezmoi.
Audytuj swój obecny $HOME pod kątem narzędzi AI. Uruchom ls -la ~/ | grep -E '(claude|codex|cursor|agent)' i find ~/.config -maxdepth 2 -name '*claude*' -o -name '*codex*' -o -name '*cursor*', żeby wiedzieć, co realnie jest na dysku. Nie pomijaj tego — większość ludzi jest zaskoczona tym, co znajduje.
Pobierz śledzone pliki do katalogu source. Z chezmoi: chezmoi add ~/.claude/CLAUDE.md, potem chezmoi add ~/.claude/settings.json, potem chezmoi add ~/.claude/hooks/, i tak dalej. Z yadm: yadm add ~/.claude/CLAUDE.md i reszta. Z plain git: przenieś pliki do repo i zastąp je symlinkami.
Usuń sekrety i zastąp je referencjami. Otwórz każdy śledzony plik i znajdź wszystko wrażliwe — API keys, tokeny OAuth, ID kont, wewnętrzne hostnames. Zastąp każdy referencją do secret managera (op://Personal/... dla 1Password, ${DOPPLER_TOKEN} dla Doppler, itd.). Przetestuj ponownie, że narzędzie nadal działa przez wrapper managera (op run -- claude).
Napisz bootstrap.sh. Zacznij od szkieletu z sekcji Jak naprawdę wygląda maksymalny wynik i dostosuj do swojego stosu — Homebrew na macOS, apt na Linuksie, twoja konkretna metoda instalacji Codex, npm globals, których chcesz. Przetestuj go dwa razy: raz na świeżym VM (UTM, OrbStack lub GitHub Codespace), raz na istniejącej maszynie, żeby potwierdzić, że jest idempotentny i nie nadpisuje stanu.
Dodaj .gitignore i pre-commit secret scan. Skopiuj .gitignore z góry. Zainstaluj gitleaks i dodaj pre-commit hook (gitleaks protect --staged). Uruchom gitleaks detect --source . raz nad całym drzewem przed pierwszym pushem.
Pushuj i zbootstrapuj drugą maszynę. Pushuj na GitHub, potem na innej maszynie (lub świeżym VM) uruchom jednolinijkowiec chezmoi (sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply YOUR-HANDLE) lub swój odpowiednik. Zmierz czas. Jeśli to ponad 10 minut do “gotowa do pracy”, przytnij bootstrap.
Udokumentuj README. Dwa akapity: jak zbootstrapować i co jest śledzone. Drugi to manifest — kiedy przyszłe-ty zastanawia się “gdzie wsadziłem moje hooks Claude?”, README odpowiada w pięć sekund.
Ustaw rutynę odświeżania. Raz w miesiącu, chezmoi re-add (lub yadm add ponownie) nad twoimi śledzonymi plikami, żeby wciągnąć drift. Raz na kwartał, uruchom pełny bootstrap na jednorazowym VM, żeby potwierdzić, że nadal działa end-to-end.
Onboarduj jednego teammate’a. Daj mu URL repo. Jeśli jest w “gotowy do pracy” w ciągu godziny, ci się udało. Jeśli uderza w pięć nieudokumentowanych prerequisitów, napraw bootstrap, aż te pięć będzie zautomatyzowanych.

Częste pułapki

Commitowanie sekretów. Pojedynczy najczęstszy błąd — ~/.claude/settings.json z inline’owym API key, .codex/config.toml z kluczem providera, mcp.json z bearer tokenem. Zawsze pipuj wszystko przez swojego secret managera (Q22) i dodaj gitleaks do pre-commit. Jeśli pushniesz sekret przez przypadek, rotuj go natychmiast — załóż, że repo jest publiczne od momentu pusha, nawet jeśli jest prywatne, ponieważ API secret-scanningowe GitHuba już je widziały.

Brak bootstrap scriptu. Repo z plikami, ale bez installera. Kończysz z 14-krokowym README, które wymaga uważnego czytania za każdym razem, gdy onboardujesz nową maszynę. Sens dotfiles to automatyzacja — jeśli musisz myśleć za każdym razem, pominiesz to na następnym evencie provisioningu. Nawet 20-liniowy skrypt bash jest nieskończenie lepszy niż markdown checklista.

Hardcodowane ścieżki absolutne specyficzne dla maszyny. Wpisanie na sztywno /Users/yourname/... do CLAUDE.md lub settings.json to bug przenośności czekający, żeby ugryźć w momencie, gdy twoja nazwa użytkownika na nowej maszynie jest inna (Codespaces używa vscode; korporacyjny macOS często używa firstname.lastname). Używaj $HOME, ~ lub szablonu chezmoi {{ .chezmoi.homeDir }}.

Śledzenie cache i logów. ~/.claude/cache/, ~/.claude/logs/, ~/.config/claude-code/machine-id — pęcznieją repo, leakują fingerprinty maszyn i tworzą merge konflikty. Gitignoruj je agresywnie.

Zapominanie o obsłudze driftu. Edytujesz ~/.claude/CLAUDE.md bezpośrednio, nigdy nie uruchamiasz chezmoi re-add, a miesiąc później twoje repo jest nieaktualne. Albo zobowiąż się do edycji source (chezmoi edit ~/.claude/CLAUDE.md), albo ustaw miesięczne przypomnienie, żeby re-addować śledzone pliki.

Brak drugiej maszyny. Repo dotfiles, które nigdy nie było zbootstrapowane na drugiej maszynie, to teatr — realnie nie wiesz, czy działa. Odpal Codespace raz na kwartał i uruchom bootstrap end-to-end jako fire drill.

Mieszanie dotfiles z regułami projektowymi. Instrukcje specyficzne dla projektu żyją w CLAUDE.md projektu (commitowane do repo projektu). Globalne, cross-project reguły żyją w ~/.claude/CLAUDE.md (twoje dotfiles). Nie mieszaj ich — globalna powinna być użyteczna niezależnie od tego, w którym projekcie jesteś.

Jak sprawdzić, czy już tam jesteś

Przejdź przez tę checklistę. Każdy odhaczony box = maksymalny wynik. Pominięte boxy = action itemy.

Jeśli wszystkie dwanaście jest odhaczonych, jesteś na maksymalnym wyniku w Q23. Jeśli jesteś na ośmiu do jedenastu, jesteś na 3 lub 4 i jedno skoncentrowane popołudnie od maksimum. Poniżej ośmiu, traktuj to jako swoją najwyższej dźwigni inwestycję Operations & hygiene na ten kwartał — kompoundujący zwrot z “każda nowa maszyna jest gotowa w 10 minut” jest ogromny.

Dalsza lektura

Q22 · Zarządzanie sekretami Twoje repo dotfiles musi być wolne od plaintekstowych sekretów — przekieruj każdy klucz przez 1Password lub Doppler ze scoped tokenami i kwartalnym audytem.

Q13 · Agent hooks Hooks w ~/.claude/hooks/ to pojedyncza najwyższej dźwigni rzecz do przeniesienia między maszynami. Wersjonuj je, testuj, dostarczaj.

Q15 · Git worktrees Worktrees to sposób, w jaki twoje repo dotfiles pozostaje edytowalne na każdej maszynie bez bólu branch-switchingu. Sparuj je ze swoim bootstrapem.

Wypełnij Developer Scorecard Sprawdź, gdzie stoisz we wszystkich 25 pytaniach w ~10 minut.