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

Docker Magento가 도는 우분투 서버에서 Claude Code를 쓰는 워크플로우를 다듬은 기록. "원격 서버 + AI 코딩 에이전트"로 일하는 사람용.

TL;DR

• 로컬 클론 쓰지 마라. 로컬엔 Magento가 없어 에이전트가 bin/magento로 자기 작업을 검증 못 한다. 서버에서 직접 편집 + 즉시 테스트, 커밋 없이.
• VS Code 익스텐션 대신 tmux. 서버에 SSH 한 번 → tmux에서 패널 쪼개 Claude Code 여러 개. SSH 끊겨도 세션 유지(tmux attach로 재접속).
• 이미지 입력은 스크린샷 폴더를 서버로 미러링 + 최신 파일 자동 첨부 래퍼(cc).

# 서버 ~/.bashrc — 최신 스크린샷을 자동으로 집어 claude에 첨부
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 "이 레이아웃 왜 깨졌어?" 하면 방금 찍은 이미지가 자동으로 들어간다.

로컬에 클론해서 작업하면 안 되나 — 안 된다

• 커밋이 "테스트의 전제조건"이 된다. 로컬을 원본으로 두면 한 줄 확인하려고 매번 commit → push → 서버 pull. 커밋이 "동작하나 보자"의 수단이 되면 루프가 느려지고 히스토리가 wip, fix로 더러워진다. 커밋은 "확인됨, 저장"이어야 한다.
• 결정타: 로컬엔 Magento가 없다. Claude Code의 힘은 코드 수정만이 아니라 그 자리에서 명령 실행·결과 확인(compile → 로그 → 에러 → 재수정)에 있다. 로컬에선 에이전트가 자기 작업을 검증 못 하는 명백한 다운그레이드.

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

매 수정마다 compile? 대부분 아니다

Magento에서 명령이 필요한 변경은 일부뿐이다.

• .phtml·블록/모델 PHP·JS·Tailwind 소스 → 저장하고 새로고침하면 바로 (developer 모드 + Docker bind-mount).
• .xml 레이아웃·번역 → cache:flush만.
• di:compile → di.xml에 새 의존성·플러그인·preference 추가하거나 새 모듈 setup:upgrade 할 때뿐.

평소 로직·템플릿 작업은 명령어 0개. 테마 작업 땐 npm run watch(Tailwind)를 띄워두면 CSS가 저장하는 족족 빌드된다. 그리고 정말 필요한 순간엔 Claude Code한테 "고치고 필요한 마젠토 명령까지 실행하고 결과 봐줘"라고 하면 알아서 판단해 돌리고 에러까지 확인한다 — 서버에서 에이전트를 돌리는 이유 그 자체다.

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

불편함의 원인은 "서버 작업"이 아니라 **"VS Code 익스텐션을 경유하는 것"**이었다. Claude Code는 터미널 네이티브 도구고 익스텐션은 부가물, 본체는 CLI다. 그러면 방향은 명확하다 — 익스텐션을 거치지 말고 서버 터미널에서 tmux로 여러 개 직접 띄운다.

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

tmux 세션은 SSH가 아니라 서버에 붙어 있어 인터넷이 끊기거나 노트북을 닫아도 죽지 않는다. 카페에서 덮고 집에서 tmux attach 하면 하던 대화가 그대로 이어진다.

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

이미지 붙여넣기: ss 싱크 + cc

VS Code를 못 버리던 이유 중 하나가 클립보드 이미지 붙여넣기. 순수 터미널에선 기본으로 안 된다. CleanShot 공개 URL도 있지만 마젠토 관리자·주문·API 키 화면이 공개 인터넷에 올라가는 게 걸려 로컬 싱크로 갔다(위 TL;DR의 cc 함수). 동작은 "캡처 → cc" 두 단계뿐. 토큰은 전달 방식이 아니라 이미지 해상도가 좌우하므로 영역 캡처 습관이 곧 토큰 절약이다.

tmux 세션 매니저는 이미 있다

순수 tmux는 "어느 세션이 끝났는지"를 못 보여준다. 그 빈 곳을 채우는 도구들: craftzdog/tmux-claude-session-manager(프로젝트별 세션 + 끝남/작업중 상태 팝업, Claude Code hooks 사용), NTM(이름붙은 세션·브로드캐스트·충돌 감지 + 원격 SSH 끊김에도 세션 유지 — 원격에 특히 맞음), nielsgroen/claude-tmux(tmux 팝업 TUI로 세션 전환·모니터링). 순서: 맨손 tmux로 감 잡고, 세션이 늘어 "뭐가 돌고 뭐가 끝났지?"가 답답해지면 그때 매니저 한 겹을 얹는다.

배운 것

• 원격 Claude Code는 통로를 잘못 잡으면 불편해진다. 서버 직접 작업(DB·마젠토 접근, 에이전트 자기검증)은 유지하되 통로만 익스텐션 → tmux로 바꾸면 멀티세션·세션 영속성을 얻는다.
• 격리가 필요 없는 작업에 격리 도구를 쓰지 마라. 그 경우 tmux가 정답이다.
• 터미널의 약점(이미지 입력)은 파일 싱크 + 래퍼 함수로 메울 수 있다 — GUI 도구 부럽지 않다.