AX 팁 21 — 새 기기 설치·복구를 스크립트 하나로

작성

  • AX 팁
  • Claude Code
  • 개발 환경 자동화
  • dotfiles

새 맥을 세팅할 때와 설정 링크가 깨졌을 때를 같은 스크립트 하나로 처리하면 됩니다. 스크립트는 여러 번 돌려도 결과가 같게(멱등) 만들고, --check 를 붙이면 아무것도 바꾸지 않고 어긋난 것만 세어 보고하게 합니다. 경로는 스크립트마다 적지 않고 파이썬 파일 하나에 모아 두고, 다른 위치로 옮기면 그 파일이나 환경 변수만 바꿉니다.

밝은 사무실 책상에서 새 노트북을 설정하는 여성 AI 생성 이미지

지난 편에서는 새로 받은 저장소에서 한글 파일명이 풀리는 문제를 다뤘고, 그 해결책을 설치 스크립트의 0단계에 넣었다고 적었습니다. 이번 편은 그 설치 스크립트 자체 이야기입니다.

왜 새 기기를 세팅할 때마다 반나절이 걸렸을까?

에이전트가 읽는 규칙 파일, 슬래시 명령, 훅, 출력 스타일을 저장소 하나에 모아 둡니다. 그런데 Claude Code 는 이 파일들을 저장소가 아니라 홈 폴더의 정해진 자리(~/.claude/ 아래, ~/CLAUDE.md 등)에서 읽습니다. 그래서 저장소의 원본을 그 자리에 심볼릭 링크로 이어 줘야 합니다.

처음에는 이 링크를 손으로 만들었습니다. 새 기기에서 하나씩 ln -s 를 치다 보면 몇 개는 꼭 빠졌고, 빠진 것은 며칠 뒤 「왜 이 명령이 안 뜨지?」로 돌아왔습니다. 검색해 보면 「새 맥 개발 환경 세팅 자동화」, 「dotfiles 심볼릭 링크 관리」를 묻는 글이 정말 많고, 공개된 dotfiles 저장소 대부분이 bootstrap.sh 하나로 도구 설치와 링크 생성을 묶는 구조를 씁니다. 저도 같은 결론에 닿았습니다.

2026년 10월 9일에 설치 스크립트와 경로 정본 파일을 같은 커밋으로 처음 만들었습니다. 2026년 11월 15일에 재 보니 설치 스크립트는 299줄, 경로 파일은 208줄이고, 이름 바뀐 이력까지 따라가면 설치 스크립트에 커밋 31개, 경로 파일에 25개가 쌓였습니다.

설치와 복구를 왜 하나로 합쳤을까?

설치 스크립트는 처음 한 번만 도는 것으로 생각하기 쉽습니다. 그런데 실제로 링크가 깨지는 일은 새 기기보다 쓰던 기기에서 더 자주 생겼습니다. 저장소를 다른 폴더로 옮겼을 때, 파일 묶음을 분류 폴더로 다시 정리했을 때, 새 명령 파일을 더했을 때가 모두 해당합니다.

그래서 처음부터 「설치 = 복구」로 정했습니다. 스크립트는 지금 상태와 원하는 상태를 비교해 다른 곳만 고칩니다. 이미 맞으면 아무것도 하지 않으니 몇 번을 돌려도 안전하고, 무엇이 깨졌는지 몰라도 그냥 다시 돌리면 됩니다.

설치 스크립트 한 번이 하는 일bootstrap.sh 실행 → 0. 한글 파일명 맞추기; 0. 한글 파일명 맞추기 → 1. 홈 폴더 링크; 1. 홈 폴더 링크 → 2. git 설정; 2. git 설정 → 3. 훅·설정·플러그인 동기화; 3. 훅·설정·플러그인 동기화 → 4. 저장소별 안내 파일 링크; 4. 저장소별 안내 파일 링크 → 어긋남 건수 보고bootstrap.sh 실행0. 한글 파일명 맞추기1. 홈 폴더 링크2. git 설정3. 훅·설정·플러그인동기화4. 저장소별 안내 파일링크어긋남 건수 보고
설치 스크립트 한 번이 하는 일 — 어긋난 곳만 고치고, 맞는 곳은 건너뛴다

바꾼 방법 1: 링크 함수 하나가 「확인·건너뛰기·고치기」를 다 한다

스크립트의 중심은 아래 함수입니다. 링크 하나를 원하는 상태로 맞추는 일을 모두 이 함수가 맡습니다.

link() {  # link <원본> <링크 위치>
  local src="$1" dst="$2"
  local cur; cur="$(readlink "$dst" 2>/dev/null)"
  if [ -L "$dst" ] && [ "${cur%/}" = "${src%/}" ]; then return; fi
  if [ -e "$dst" ] && [ ! -L "$dst" ]; then
    echo "  SKIP 실파일이 있어 덮어쓰지 않음: $dst"; drift=$((drift+1)); return
  fi
  drift=$((drift+1))
  if [ "$CHECK" -eq 1 ]; then echo "  DRIFT $dst → $src"; return; fi
  mkdir -p "$(dirname "$dst")" && ln -sfn "$src" "$dst" && echo "  LINK $dst → $src"
}

이 열 줄에 실제로 겪은 일이 세 가지 들어 있습니다.

  • 이미 같은 곳을 가리키면 바로 끝냅니다. 끝 슬래시만 다른 경우도 같은 링크로 봅니다.
  • 그 자리에 링크가 아닌 진짜 파일이 있으면 덮어쓰지 않고 보고만 합니다. 내가 손으로 만든 설정을 스크립트가 지우는 일이 가장 무서웠습니다.
  • 점검 모드면 고칠 대상을 찍기만 하고, 아니면 링크를 만듭니다. 두 경우 모두 어긋남 건수(drift)를 하나 올립니다.

바꾼 방법 2: 점검 모드로 「돌리기 전에」 본다

--check 를 붙이면 같은 스크립트가 아무것도 바꾸지 않고 어긋난 것만 세고, 하나라도 있으면 종료 코드 1 을 냅니다. 매일 도는 점검이 이 모드를 불러서, 설치를 잊은 기기가 있으면 그날 알려 줍니다.

bash scripts/session/bootstrap.sh --check   # 바꾸지 않고 어긋난 것만 보고
bash scripts/session/bootstrap.sh           # 어긋난 것만 고침(여러 번 돌려도 같음)

이 글을 쓰면서 쓰던 맥에서 점검 모드를 돌려 보니 4초 만에 끝났고, 어긋남 12건이 나왔습니다(2026년 11월 15일 기준). 고장 난 것은 없는데도 12건이 나온 것이 오히려 이 모드의 쓸모를 보여 줍니다. 손으로 세팅했다면 이 12개가 어디서 벌어졌는지 찾는 데만 한참 걸렸을 것입니다.

점검과 적용이 같은 함수를 지나가는 것도 중요합니다. 점검 코드를 따로 두면 언젠가 적용 코드와 어긋나고, 그러면 「점검은 통과인데 실제로는 깨진」 상태가 생깁니다.

바꾼 방법 3: 경로는 한 파일에서만 정한다

스크립트를 짜다 보면 홈 폴더 아래 경로를 여기저기 적게 됩니다. 저장소를 한 번 옮기자 그 경로들이 한꺼번에 낡았습니다. 그래서 경로를 정하는 파이썬 파일을 하나 두고, 설치 스크립트와 훅이 모두 그 파일에서 경로를 읽게 했습니다.

_env = os.environ.get("CC_INSTRUCTIONS_DIR")
_env = _env if _env and os.path.isfile(os.path.join(_env, "AGENTS.md")) else None
INSTR = _env or _repo_root() or os.path.join(HOME, "Desktop", "instructions")

순서가 핵심입니다. 환경 변수가 있으면 먼저 쓰되, 그 폴더에 규칙 파일이 없으면 옮기기 전의 낡은 값으로 보고 버립니다. 다음은 이 파일 자신이 놓인 위치로 저장소를 찾고, 그래도 없을 때만 기본 경로를 씁니다. 설치 스크립트는 지금 저장소 위치를 이 환경 변수로 설정에 다시 넣어 두므로, 저장소를 옮긴 뒤 한 번 돌리면 모든 도구가 새 위치를 봅니다.

설치 스크립트도 자기 위치를 pwd -P 로 실제 폴더 기준으로 계산합니다. 2026년 10월 20일에 링크 경로로 스크립트를 불렀더니 같은 폴더를 다른 경로로 보고 거짓 어긋남을 낸 일이 있어서 넣은 줄입니다.

그동안 어디서 막혔을까?

스크립트가 31번 바뀐 데에는 이유가 있습니다. 커밋 기록과 주석에 남은 굵직한 장면을 시간 순으로 모아 보면 이렇습니다.

설치 스크립트가 배운 것10-09 설치 스크립트·경로 정본 처음 만듦; 10-11 0단계에 한글 파일명 맞추기 추가; 10-21 시험용 빈 홈에서는 플러그인 설치 건너뜀 (실제 설치가 몇 시간 멈춤); 10-31 두 맥이 함께 보는 폴더에 링크를 만들지 않음; 10-31 플러그인은 설치 여부가 아니라 버전까지 비교10-09설치 스크립트·경로 정본 처음 만듦10-110단계에 한글 파일명 맞추기 추가10-21시험용 빈 홈에서는 플러그인 설치 건너뜀실제 설치가 몇 시간 멈춤10-31두 맥이 함께 보는 폴더에 링크를 만들지 않음10-31플러그인은 설치 여부가 아니라 버전까지비교
설치 스크립트가 배운 것
  • 시험 스크립트가 빈 홈 폴더를 만들어 설치를 돌렸는데, 그 안에서 실제 언어 서버·플러그인 설치가 몇 시간 멈췄습니다. 지금은 가짜 홈이면 설치 단계를 건너뜁니다.
  • 데스크톱 폴더를 두 대의 맥이 클라우드로 함께 보는데, 그 안에 링크를 만들자 두 맥이 서로의 경로로 덮어써서 한쪽이 깨졌습니다. 지금은 공유 폴더에 아무것도 만들지 않고, 두 맥은 git 커밋과 pull 로만 맞춥니다.
  • 플러그인이 「설치됨」인지만 보니, 저장소 쪽 버전이 올라가도 옛 설치본이 그대로 돌았습니다. 지금은 설치본 버전과 저장소 버전을 비교해 다르면 업데이트합니다.

지금은 하루가 어떻게 달라졌을까?

새 기기든 쓰던 기기든 할 일이 하나로 줄었습니다. 저장소를 받고 설치 스크립트를 돌리면 끝이고, 이상하면 점검 모드로 먼저 봅니다. 무엇이 깨졌는지 추측하는 시간이 사라졌습니다.

새 설정이 생기면 문서에 「손으로 이렇게 하세요」라고 적는 대신 이 스크립트에 단계를 더합니다. 그러면 다음 기기도, 다음 복구도 같은 단계를 자동으로 밟습니다. 문서는 잊혀도 스크립트는 매번 돕니다.

자주 묻는 질문

설치 스크립트를 여러 번 돌려도 괜찮나요?

괜찮게 만드는 것이 핵심입니다. 각 단계가 지금 상태를 먼저 보고 원하는 상태와 다를 때만 고치면, 두 번째 실행부터는 아무것도 바뀌지 않습니다. 진짜 파일을 덮어쓰지 않는 규칙까지 넣어 두면 실수로 돌려도 잃는 것이 없습니다.

GNU Stow 같은 도구 대신 직접 짠 이유는 무엇인가요?

링크만 만든다면 Stow 로도 충분합니다. 저는 링크 외에 git 설정, 훅 복사, 설정 파일 동기화, 플러그인 버전 확인까지 한 번에 점검하고 싶었고, 그 모든 단계의 어긋남을 하나의 건수로 모으려고 직접 짰습니다.

경로를 한 파일에 모으면 무엇이 좋아지나요?

저장소를 옮기거나 다른 기기에서 폴더 구조가 달라도, 그 파일 하나나 환경 변수 하나만 바꾸면 됩니다. 경로가 스크립트 여러 곳에 흩어져 있으면 옮길 때마다 어디를 놓쳤는지 찾아야 합니다.

사이트를 만들어볼까요?

무료 상담 받기