Claude Code 개발 워크플로우 가이드

AVA_DEV

AVA_DEV (Hyun)

Claude Admin

Claude Code v2.1.72

Welcome back!

Sonnet 4.6 · API Usage Billing

/home/hyun/_ava_server

Tips for getting started

Run /init to create a CLAUDE.md file with instructions for Claude
Note: For the best experience, launch claude in a project directory.

Recent activity

2h ago워크플로우 문서 작성

/resumeformore

00:00 00

❯

● Read 1 file (ctrl+o to expand)

● 안녕하세요! Claude Code 개발 워크플로우 가이드를 소개합니다.

● 아래에서 원하는 섹션을 선택해주세요:

? for shortcuts

claude-kr0:claude+ "* Claude Code" — DressDio Labs — 2026-03-11

01 개요

Claude Code란

Claude Code는 Anthropic의 AI 코딩 어시스턴트로, 터미널(CLI) 환경에서 동작합니다. 파일 읽기/쓰기, 명령어 실행, 서버 SSH 접속, Docker 관리까지 직접 수행할 수 있어 코드 작성 → 빌드 → 배포 → 검증을 하나의 대화에서 끝낼 수 있습니다.

우리 팀의 개발 구조

💻 macOS (개발자 로컬)

~/_ava_server/www_xxx/ ← Claude Code 작업 공간

⇅ Mutagen 실시간 양방향 동기화

🖥 서버 (117.16.145.143)

~/www_xxx/

repo/

소스 원본 (git)

dev/

개발 환경 (Docker)

dev.xxx.avalabs.me

prod/

정식 환경 (Docker)

xxx.avalabs.me

💡

핵심 원칙: 소스 편집은 맥북에서만, 앱 실행은 서버 Docker에서, 브라우저 확인은 dev.xxx.avalabs.me에서.

02 개발 환경

사전 요구사항

항목	설명
macOS	개발 머신
Claude Code	`npm install -g @anthropic-ai/claude-code`
SSH 키	`~/.ssh/avalabs` (서버 접속용)
Mutagen	`brew install mutagen-io/mutagen/mutagen`
서버	Ubuntu, Docker, Docker Compose 설치 완료

SSH 설정

~/.ssh/config:

configHost avalabs
  HostName 117.16.145.143
  User hyun
  IdentityFile ~/.ssh/avalabs

프로젝트 디렉토리

📂 ~/_ava_server/

📁www_gate/트레이딩 모니터
📁www_dress/토큰 베스팅 대시보드
📁www_sandbox/블록체인 샌드박스
📁www_sysbox/거버넌스 관리
📁www_token/토큰 정보
📁www_dropbox/에어드롭
📁www_main/메인 스토어
📁sync-scripts/Mutagen 동기화 스크립트
📁docs/이 문서들

03 일상 개발 사이클

전체 흐름

Claude Code 실행 — 맥북 터미널에서 프로젝트 폴더 이동 후 claude

소스 수정 — Claude Code가 직접 파일을 읽고, 분석, 수정

Mutagen 동기화 — 자동으로 서버 repo/에 실시간 반영

deploy-dev.sh 실행 — Claude Code가 SSH로 서버 배포

dev 사이트 확인 — dev.xxx.avalabs.me에서 검증

완료 또는 반복 — 이상 없으면 deploy.sh로 정식 배포

Claude Code 시작

bash# 프로젝트 폴더에서 Claude Code 실행
cd ~/_ava_server
claude

# 또는 특정 프로젝트로 바로 진입
cd ~/_ava_server/www_gate
claude

dev 배포

bashssh avalabs "bash ~/www_gate/deploy-dev.sh"

deploy-dev.sh 동작: ① rsync repo/ → dev/ ② docker compose up -d --build

정식(prod) 배포

bashssh avalabs "bash ~/www_gate/deploy.sh"

deploy.sh 동작: ① 미커밋 변경사항 자동 git commit ② rsync repo/ → prod/ ③ docker compose up -d --build

배포 후 확인

bash# 컨테이너 상태
ssh avalabs "docker ps --filter name=hyun_trade"

# 앱 로그
ssh avalabs "docker logs hyun_trade_dev --tail 30"

# HTTP 응답
curl -s -o /dev/null -w "%{http_code}" https://dev.trade.avalabs.me

04 서버 3-폴더 구조

구조 설명

모든 프로젝트는 서버에서 동일한 3-폴더 구조를 따릅니다:

📂 ~/www_xxx/

📁repo/git 소스 원본
- 📂.git/
- 📄docker-compose.ymldev용
- 📄docker-compose.hyun.ymlprod용
- 📁deploy/Dockerfile, env
📁dev/개발 환경 배포본 (rsync)
📁prod/정식 환경 배포본 (rsync)
⚙️deploy-dev.shrepo/ → dev/
⚙️deploy.shrepo/ → prod/

왜 3-폴더 구조인가

문제	해결
dev와 prod가 같은 소스로 실행되면 위험	repo/에서 각각 별도 rsync
dev 수정이 즉시 prod에 반영되면 안 됨	dev/와 prod/ 격리
소스 원본 보존 필요	repo/에 git 유지
배포 자동화	deploy-dev.sh, deploy.sh

데이터 흐름

💻 개발자 (맥북)

Mutagen

repo/

deploy-dev.sh

dev/

Docker

dev.xxx.avalabs.me

repo/

deploy.sh

prod/

Docker

xxx.avalabs.me

05 Docker 인프라

네트워크

모든 컨테이너(prod/dev)는 hyun_db_net 단일 Docker 네트워크를 공유합니다.

🔗 hyun_db_net bridge network

hyun_postgresprod DB :5555

hyun_postgres_devdev DB :5556

hyun_tradewww_gate prod

hyun_trade_devwww_gate dev

hyun_sandboxwww_sandbox prod

hyun_sandbox_devwww_sandbox dev

... 기타 컨테이너

⚠️

중요: Docker 네트워크는 반드시 hyun_db_net 하나만 사용. 새 네트워크를 생성하지 않습니다.

포트 매핑

프로젝트	Prod	Dev	Prod URL	Dev URL
www_main	5700	5701	`store.avalabs.me`	`dev.store.avalabs.me`
www_gate	5510	5511	`trade.avalabs.me`	`dev.trade.avalabs.me`
www_dress	5600	5601	`dress.avalabs.me`	`dev.dress.avalabs.me`
www_sandbox	5501	5504	`sandbox.avalabs.me`	`dev.sandbox.avalabs.me`
www_sysbox	5500	5503	`sysbox.avalabs.me`	`dev.sysbox.avalabs.me`
www_token	5520	5523	`tokens.avalabs.me`	`dev.tokens.avalabs.me`
www_dropbox	5502	5505	`dropbox.avalabs.me`	`dev.dropbox.avalabs.me`
PostgreSQL prod	5555	—	—	—
PostgreSQL dev	—	5556	—	—

컨테이너 네이밍 규칙

구분	형식	예시
PROD	`hyun_{이름}`	`hyun_trade`
DEV	`hyun_{이름}_dev`	`hyun_trade_dev`

06 DB 관리

DB 구조

Prod DB	Dev DB	사용자	프로젝트
`gate_data`	`gate_data_dev`	`gate`	www_gate
`dress_sandbox`	`dress_sandbox_dev`	`sandbox`	www_sysbox + www_sandbox
`airdrop`	`airdrop_dev`	`airdrop`	www_dropbox

DB 정책

⚠️

개발 초기: dev/prod 각각 별도 DB 사용
정식 서비스 후: 상황에 따라 dev가 prod DB를 사용할 수 있음
스키마 변경 시: dev DB에서 변경 후 반드시 prod DB에도 동일하게 적용

DB 접속 방법

bash# SSH 터널 (맥북에서 dev DB 접속)
ssh -f -L 5556:localhost:5556 avalabs -N

# psql 접속
psql -h localhost -p 5556 -U gate gate_data_dev

# 서버에서 직접 접속
docker exec -it hyun_postgres_dev psql -U gate -d gate_data_dev

07 Claude Code 활용 가이드

Claude Code가 할 수 있는 것

📝

파일 읽기/수정/생성

소스코드 직접 편집, 설정 파일 수정

⚡

명령어 실행

npm install, git commit, docker logs 등

🌐

SSH 원격 실행

서버 배포, 로그 확인, DB 조회

🔍

웹 검색/참조

최신 API 문서, 라이브러리 조회

📦

다중 파일 동시 수정

리팩토링, 기능 추가 일괄 수정

🩺

에러 진단

로그 분석 → 원인 파악 → 수정 → 재배포

효과적인 작업 지시 방법

✓

좋은 지시:
"www_gate의 텔레그램 봇에서 대량 매수/매도 알림 조건을 $100, $200, $300, $500 4단계로 변경해줘. 각 티어별 독립 쿨다운 5분."

✗

나쁜 지시:
"알림 좀 고쳐줘" → 어떤 알림? 어떻게? 기준 불명확

핵심 원칙

대상을 명확히 — 어떤 프로젝트, 어떤 파일/기능
원하는 결과를 구체적으로 — 수치, 형식, 조건 명시
한 번에 하나의 주제 — 복잡한 작업은 단계별로
확인 후 다음 단계 — dev에서 확인 → prod 배포

08 실전 작업 패턴

소스코드 수정 → dev 배포

"www_dress Token Info 페이지에 실시간 가격 표시해줘"

관련 소스 파일 분석
API 프록시 엔드포인트 추가
프론트엔드 API 호출 추가
deploy-dev.sh 실행
dev 사이트 응답 확인
결과 보고

버그 수정

"www_dropbox dev 컨테이너가 재시작 반복"

docker logs 에러 확인
원인 분석 (DB 인증 실패)
환경변수/비밀번호 수정
컨테이너 재시작
healthy 상태 확인

인프라 작업

"모든 프로젝트를 3-폴더 구조로 표준화해줘"

현재 구조 분석
각 프로젝트별 deploy-dev.sh 생성
기존 dev 컨테이너 중지
deploy-dev.sh 실행
전체 상태 검증
문서 업데이트

기능 조사 → 수정

"텔레그램 알림 구현 구조 정리해줘"

관련 파일 탐색/분석
구조 정리 + 보고
사용자 수정 요청 시 → 코드 수정 → 배포

09 개발 규칙

소스코드 수정 원칙

수정 필요 부분만 수정 — 파일 전체를 새로 작성하지 않는다
기존 패턴 유지 — 코딩 스타일, 네이밍 규칙을 따른다
magic number 금지 — 상수로 선언하여 사용

배포 규칙

⚠️

dev 먼저, prod 나중 — 반드시 dev에서 확인 후 prod 배포
prod/ 직접 수정 금지 — 항상 repo/ → deploy.sh → prod/
환경변수 파일 로컬 수정 금지 — 서버에서만 관리

DB 규칙

스키마 수정은 사전 확인 필수
sysbox/sandbox는 DB 공유 — 한쪽 변경이 양쪽에 영향
dev 스키마 변경 시 prod에도 반영

빌드 관련

package.json 변경 시 Docker 캐시 무효화 → npm ci 재실행
NEXT_PUBLIC_*, VITE_* 환경변수는 빌드 시 임베딩 → 변경 시 재빌드 필수
빌드 실패 시: docker compose build --no-cache

10 트러블슈팅

컨테이너가 시작 안 됨

bash# 상태 + 로그 확인
ssh avalabs "docker ps -a --filter name=hyun_xxx"
ssh avalabs "docker logs hyun_xxx_dev --tail 50"

# 일반적 원인:
# - DB 연결 실패 → 환경변수, 네트워크 확인
# - 포트 충돌 → docker ps로 포트 확인
# - 빌드 실패 → docker compose build --no-cache

Mutagen 동기화 문제

bashmutagen sync list
bash sync-scripts/gate_ava-local.sh stop
bash sync-scripts/gate_ava-local.sh start

Docker 네트워크 에러

bashssh avalabs "docker network ls | grep hyun"
# hyun_db_net이 없으면 PostgreSQL 재시작
ssh avalabs "cd ~/hyun_postgres && docker compose up -d"

사이트 접속 불가 (HTTPS)

bashssh avalabs "sudo nginx -t"
ssh avalabs "sudo certbot certificates"
dig dev.xxx.avalabs.me +short @8.8.8.8

11 프로젝트별 기술 스택

프로젝트	스택	DB	비고
www_main	React + Vite + Tailwind	없음	정적 사이트
www_gate	Express + React + Socket.IO	PostgreSQL	실시간 WebSocket
www_dress	Vanilla JS + Express	없음	Gate.io API 프록시
www_sandbox	Next.js 16 + Prisma	PostgreSQL	sysbox와 DB 공유
www_sysbox	Next.js 16 + Prisma + Wagmi	PostgreSQL	sandbox와 DB 공유
www_token	Next.js 16 + Wagmi	없음	블록체인 직접 조회
www_dropbox	Express + React + Vite + Wagmi	PostgreSQL	에어드롭 시스템

12 신규 프로젝트 추가

포트 배정 — 기존 포트와 겹치지 않게

서버 폴더 생성 — ~/www_xxx/{repo,dev,prod}

소스 + Docker 설정 — Dockerfile + docker-compose.yml

환경변수 파일 — .env.docker, .env.dev.docker

배포 스크립트 — deploy-dev.sh, deploy.sh

DB 생성 — 필요 시, dev/prod 각각

컨테이너 시작 + HTTP 확인

DNS 등록 — 가비아 A 레코드

Nginx + SSL — 리버스 프록시 + certbot

Mutagen + 문서 업데이트

13 명령어 모음

맥북에서

명령	설명
`ssh avalabs "bash ~/www_xxx/deploy-dev.sh"`	dev 배포
`ssh avalabs "bash ~/www_xxx/deploy.sh"`	prod 배포
`ssh avalabs "docker logs hyun_xxx_dev --tail 50"`	dev 로그
`ssh avalabs "docker ps \| grep hyun"`	컨테이너 상태
`bash sync-scripts/xxx_ava-local.sh`	Mutagen 시작

서버에서

명령	설명
`docker compose up -d --build`	재빌드 + 재시작
`docker compose down`	중지 (DB 유지)
`docker compose build --no-cache`	캐시 없이 재빌드
`docker exec -it hyun_postgres_dev psql -U gate -d gate_data_dev`	dev DB 접속

★ 실전 교훈

실제 개발 과정에서 겪은 문제와 해결 방법. 클릭하여 상세 확인.

🌐

CORS 문제 해결

▼

상황

www_dress에서 브라우저가 Gate.io API를 직접 호출 → CORS 차단

해결

Express 서버에 /api/ticker 프록시 엔드포인트 추가

교훈

외부 API는 서버 프록시를 통해 호출한다.

🔗

Docker 네트워크 통일

▼

상황

www_gate dev에서 hyun_db_dev_net (존재하지 않는 네트워크) 참조 → 시작 실패

해결

모든 컨테이너가 hyun_db_net 하나를 공유하도록 통일

교훈

Docker 네트워크는 hyun_db_net 하나만 사용. 새 네트워크를 만들지 않는다.

🖼️

이미지 로딩 패턴

▼

상황

position: absolute + display: none + onLoad 패턴 → onLoad 미실행 시 placeholder가 이미지를 가림

해결

<img> 직접 렌더 + onError 시에만 fallback

교훈

이미지 로딩은 단순하게. imgError 상태 하나만 사용.

🔒

dev/prod 격리의 중요성

▼

상황

dev 컨테이너가 repo/에서 직접 실행 → 소스 변경 즉시 반영되어 불안정

해결

3-폴더 구조 (repo → dev/ rsync → Docker build) 표준화

교훈

dev도 prod와 동일한 격리 구조를 유지한다.

🔑

DB 비밀번호 불일치

▼

상황

www_dropbox dev 컨테이너 재시작 반복 → DB 인증 실패

해결

init-databases.sh의 초기 비밀번호와 .env.dev.docker 비밀번호 불일치 → DB 사용자 비밀번호 재설정

교훈

DB 사용자 생성 시 비밀번호를 env 파일과 반드시 일치시킨다.