원격 서버에서 Claude Code 제대로 쓰기 — 로컬 클론을 버리고, tmux와 스크린샷 자동 전달까지

Docker로 띄운 Magento가 우분투 서버에 있다. 작업할 땐 VS Code Remote-SSH로 서버에 들어가, 모듈 폴더 안에서 Claude Code를 돌린다. 이 워크플로우를 다듬으면서 했던 고민과 결론을 정리한다. 비슷하게 "원격 서버 + AI 코딩 에이전트"로 일하는 사람에게 도움이 될 것 같다.

로컬에 클론해서 작업하면 안 되나?

가장 먼저 든 생각. 코드를 로컬에 클론해두고, 거기서 편하게 작업한 다음 서버로 보내면 안 되나? 결론은 안 좋다, 그리고 그 이유가 이 글의 출발점이다.

첫째, 커밋이 "테스트의 전제조건"이 된다. 로컬을 원본으로 두고 git으로 동기화하면, 한 줄 고쳐서 확인하려고 매번 commit → push → 서버에서 pull을 해야 한다. 커밋이 "동작하나 보자"의 수단이 되는 순간 루프가 느려지고, git 히스토리가 wip, fix, 다시 fix로 더러워진다. 커밋은 "확인됨, 저장"의 의미여야 한다.

둘째, 그리고 이게 결정적인데 — 로컬엔 Magento가 없으니 Claude Code가 bin/magento를 못 돌린다. Claude Code의 진짜 힘은 코드를 고치는 것만이 아니라, 그 자리에서 명령을 실행하고 결과를 확인하는 데 있다. compile 돌리고, 로그 보고, 에러 잡고 다시 고치는 루프. 로컬에선 에이전트가 자기 작업을 검증할 수 없다. 명백한 다운그레이드다.

그래서 멘탈 모델을 둘로 나눴다. 이너 루프(개발)는 Magento가 도는 서버에서 직접 편집 + 즉시 테스트, 커밋 없음. 아우터 루프(배포)는 동작 확인 후 push → 프로덕션에서 pull. 여기서 git push는 "staging→prod 게이트"지 "로컬→staging 동기화"가 아니다. 서버를 직접 편집하면 staging은 항상 최신이라, "로컬→staging 자동 동기화"라는 문제 자체가 사라진다. 그건 로컬 편집을 택했을 때만 생기는, 자초한 문제였다.

"수정할 때마다 compile 쳐야 하나?" — 대부분 아니다

서버 작업의 번거로움으로 느꼈던 것. 알고 보니 오해였다. Magento에서 명령이 필요한 변경은 일부뿐이다.

.phtml 템플릿, 블록/모델 내부 PHP 로직, JS, Tailwind 소스는 저장하고 새로고침하면 바로 보인다 (developer 모드 + Docker bind-mount면 컨테이너가 호스트 파일을 그대로 본다). .xml 레이아웃이나 번역은 cache:flush만 하면 된다. di:compile이 정말 필요한 건 di.xml에 새 의존성·플러그인·preference를 추가하거나 새 모듈을 setup:upgrade 할 때뿐이다.

즉 평소 로직 짜고 템플릿 만지는 작업은 명령어 0개. 매 수정마다 compile 치는 건 불필요한 습관이었다. 테마 작업 땐 npm run watch(Tailwind watch)를 띄워두면 CSS가 저장하는 족족 빌드된다. full static deploy는 프로덕션 배포 때만.

그리고 compile/flush가 정말 필요한 순간엔 Claude Code한테 "고치고 필요한 마젠토 명령까지 실행하고 결과 봐줘"라고 하면 자기가 판단해서 돌리고 에러까지 확인한다. 손으로 칠 필요가 없다. 이게 서버에서 에이전트를 돌리는 이유 그 자체다.

VS Code 익스텐션이 불편했던 진짜 이유

새 대화를 열려면 창/패널을 오가야 하고, Warp이나 Conductor 같은 도구로 쓰는 것보다 불편했다. 한참 헤매다 원인을 깨달았다. 불편함의 원인은 "서버 작업"이 아니라 "VS Code 익스텐션을 경유하는 것"이었다.

Claude Code는 원래 터미널 네이티브 도구다. VS Code 익스텐션은 부가물이고 본체는 CLI다. Warp이 편한 이유는 터미널에서 바로 띄우니까. 그러면 해결의 방향은 명확하다 — 익스텐션을 거치지 말고 서버 터미널에서 Claude Code를 여러 개 직접 띄우면 된다.

tmux: 멀티세션 + SSH 끊겨도 살아있음

답은 tmux였다. SSH로 서버에 한 번 들어가 tmux를 띄우면, 그 안에서 패널을 쪼개 각각 Claude Code를 돌릴 수 있다. 새 세션마다 SSH를 새로 열 필요가 없다.

ssh server (한 번)
└─ tmux
   ├─ 패널1: ModuleA 에서 claude
   ├─ 패널2: ModuleB 에서 claude
   └─ 패널3: tail -f var/log/  (로그)

진짜 강점은 따로 있다. tmux 세션은 SSH가 아니라 서버 자체에 붙어 있어서, 인터넷이 끊기거나 노트북을 닫아도 죽지 않는다. 카페에서 작업하다 노트북 덮고, 집에서 다시 접속해 tmux attach 하면 하던 Claude Code 대화가 그대로 이어진다. GUI 도구엔 없는, 서버 기반 작업의 강점이다.

그리고 격리(git worktree) 얘기 — Conductor 같은 도구가 브랜치/worktree를 만드는 건 여러 에이전트가 같은 파일을 동시에 밟을 때 충돌을 막으려는 거다. 그런데 모듈별로 폴더가 갈린 독립 작업은 worktree 없이도 충돌나지 않는다. 게다가 Magento는 코드를 worktree로 분리해도 그게 도는 인스턴스(DB·캐시·compiled)가 하나라 결국 병목이다. 격리가 필요 없는 작업이라면 맨손 tmux로 충분하다.

이미지 붙여넣기 문제, 그리고 ss + cc

VS Code를 못 버리던 이유 중 하나가 클립보드 이미지 붙여넣기였다. 마젠토 화면 깨진 걸 캡처해서 바로 넣으면 Claude Code가 본다. 순수 터미널에선 이게 기본으로 안 된다.

CleanShot 공개 URL을 붙이는 방법도 있지만, 마젠토 관리자·주문·API 키 화면이 공개 인터넷에 올라가는 게 걸렸다. 그래서 로컬 싱크 방식으로 갔다. 스크린샷(ss) 폴더를 서버로 실시간 미러링하고, 서버엔 "최신 스크린샷을 자동으로 집는" 래퍼 함수를 둔다. 파일명을 욜한이 알 필요가 없는 게 핵심이다.

# 서버 ~/.bashrc
SHOT_DIR="$HOME/ss"
cc() {
  local latest
  latest=$(ls -t "$SHOT_DIR"/*.png 2>/dev/null | head -1)
  if [ -n "$latest" ]; then
    echo "🖼  첨부: $(basename "$latest")"
    claude "$@" "$latest"
  else
    claude "$@"
  fi
}

맥에서 CleanShot 저장 위치를 싱크 폴더로 잡고(Mutagen으로 서버 ~/ss에 단방향 미러링), tmux에서 cc "이 레이아웃 왜 깨졌어?" 하면 방금 찍은 이미지가 자동으로 들어간다. 동작은 "캡처 → cc" 두 단계뿐. 토큰은 전달 방식(URL/파일)과 무관하고 이미지 해상도가 좌우하므로, 영역 캡처 습관이 곧 토큰 절약이다.

tmux 기반 세션 매니저는 이미 존재한다

"격리 기반(Conductor 류) 말고, 내가 원하는 tmux 멀티세션 관리 도구는 없나?" 찾아보니 있었다. 순수 tmux는 "어느 세션이 끝났는지"를 못 보여주는데, 그 빈 곳을 채우는 도구들이다.

craftzdog/tmux-claude-session-manager는 프로젝트별 세션을 띄우고 끝남/작업중 상태를 팝업에서 보여준다(Claude Code hooks로 상태를 tmux에 찍는다). NTM(Named Tmux Manager)은 이름붙은 세션·브로드캐스트·충돌 감지에 더해, 원격 서버에서 돌릴 때 SSH 끊김에도 세션이 유지되도록 설계됐다 — 원격 환경에 특히 맞는다. nielsgroen/claude-tmux는 tmux 팝업 TUI로 세션 전환·모니터링을 제공한다.

순서는 이렇게 잡았다. 일단 맨손 tmux로 시작해 감을 잡고, 세션이 늘어 "뭐가 돌고 뭐가 끝났지?"가 답답해지면 그때 매니저 한 겹을 얹는다.

정리

원격 서버에서 Claude Code를 쓰는 건 불편한 게 아니라, 통로를 잘못 잡으면 불편해진다. 서버에서 직접 작업하는 건 유지하되(DB·마젠토 접근, 에이전트 자기검증이라는 큰 장점은 그대로), 통로를 VS Code 익스텐션에서 터미널 + tmux로 바꾸면 멀티세션·세션 영속성을 얻는다. 거기에 ss 싱크 + cc 함수로 이미지 입력까지 메우면, GUI 도구 부럽지 않다. 핵심 교훈 하나만 남기면 — 격리가 필요 없는 작업에 격리 도구를 쓰지 마라. 그 경우 tmux가 정답이다.