リモートサーバーで Claude Code をきちんと使う — ローカルクローンを捨て tmux + スクリーンショット自動転送

Docker Magento が動く Ubuntu サーバーで 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
}

Mac 側で CleanShot の保存先を Mutagen でサーバーの ~/ss へ単方向ミラーリング → tmux で cc "このレイアウトなぜ崩れた？" とすれば、今撮ったばかりの画像が自動で入る。

ローカルにクローンして作業してはダメか — ダメだ

• コミットが「テストの前提条件」になる。 ローカルを原本にすると、一行確認するのに毎回 commit → push → サーバーで pull。コミットが「動くか見てみよう」の手段になった瞬間、ループが遅くなり、履歴が wip・fix で汚れる。コミットは「確認済み、保存」であるべきだ。
• 決定打: ローカルには Magento がない。 Claude Code の力はコードの修正だけでなく、その場でコマンドを実行し結果を確認すること（compile → ログ → エラー → 再修正）にある。ローカルではエージェントが自分の作業を検証できない、明白なダウングレードだ。

メンタルモデルを2つに分けた。インナーループ（開発）はサーバーで直接編集 + 即テスト、コミットなし。 アウターループ（デプロイ）は動作確認後に push → 本番で pull。 サーバーを直接編集するのでステージングは常に最新、「ローカル→ステージング同期」という問題そのものが消える — それはローカル編集を選んだときだけ生じる自作の問題だった。

修正のたびに 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 に「直して、必要な Magento コマンドまで実行して結果を見て」と言えば、自分で判断して実行しエラーまで確認する — サーバーでエージェントを動かす理由そのものだ。

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 という手もあるが、Magento の管理画面・注文・API キー画面が公開インターネットに上がるのが気になり、ローカル同期にした（上の TL;DR の cc 関数）。動作は「キャプチャ → cc」の2ステップだけ。トークンは転送方式（URL/ファイル）ではなく画像解像度が左右するので、範囲キャプチャの習慣がそのままトークン節約になる。

tmux セッションマネージャはすでにある

素の tmux は「どのセッションが終わったか」を見せられない。その隙間を埋めるツール: craftzdog/tmux-claude-session-manager（プロジェクトごとのセッション + 終了/作業中ステータスをポップアップ表示、Claude Code hooks を使用）、NTM（名前付きセッション・ブロードキャスト・衝突検出に加え、リモートサーバーで動かすとき SSH 切断でもセッションが維持される — リモートに特に合う）、nielsgroen/claude-tmux（tmux ポップアップ TUI でセッション切り替え・モニタリング）。順序はこう: まず素の tmux で感覚をつかみ、セッションが増えて「何が動いて何が終わった？」がもどかしくなったら、そのときマネージャを一枚重ねる。

学んだこと

• リモートの Claude Code は通り道を間違えると不便になる。サーバー直接作業（DB・Magento アクセス、エージェントの自己検証）は維持しつつ、通り道を拡張から tmux に変えれば、マルチセッションとセッション永続性が手に入る。
• 隔離が要らない作業に隔離ツールを使うな。 その場合は tmux が正解だ。
• ターミナルの弱点（画像入力）はファイル同期 + ラッパー関数で埋められる — GUI ツールをうらやむ必要はない。