tk-factory-services/.claude/WORKFLOW-GUIDE.md

Claude Code 워크플로우 가이드 — TK Factory Services

1. CLAUDE.md 활용

• 프로젝트 루트의 CLAUDE.md가 매 세션 자동 로드 → 프로젝트 컨텍스트 즉시 파악
• 서비스별 CLAUDE.md 추가 가능 (예: system1-factory/CLAUDE.md) → 해당 디렉토리 작업 시 추가 로드
• git으로 관리되므로 팀원 간 공유 가능

2. 슬래시 커맨드 (.claude/commands/)

커맨드	설명	사용 예
/deploy	원클릭 NAS 배포	/deploy system1-web
/check-deploy	NAS 서비스 상태 점검	/check-deploy
/cache-bust	변경된 JS/CSS 캐시 버스팅 일괄 갱신	/cache-bust
/add-page	System1 새 HTML 페이지 스캐폴드	/add-page consumable/stock 소모품 재고
/add-api	System1 새 API 엔드포인트 스캐폴드	/add-api consumable-stock

커스텀 추가: .claude/commands/에 .md 파일 추가하면 자동 인식.

3. Plan 모드 활용

적합한 작업:

• 여러 서비스에 걸친 기능 추가 (예: 새 마이크로서비스)
• DB 스키마 변경 + API + 프론트엔드 동시 수정
• 대규모 리팩터링 (30+ 파일 변경)

사용법:

1. /plan으로 Plan 모드 진입
2. Claude가 코드 탐색 → 구현 계획 작성
3. 계획 검토 · 수정 → 승인
4. 자동 실행

4. 서브에이전트 활용 패턴

에이전트	용도	예시
Explore	코드베이스 탐색	"system1과 system2에서 인증 처리 방식 비교해줘"
Plan	구현 설계	"tkeg에 새 모듈 추가 계획 세워줘"

• 독립적 탐색은 병렬 실행 가능 (최대 3개)
• 넓은 범위 검색에 유용 (단순 파일 찾기는 직접 검색이 빠름)

5. 검증 피드백 루프 (Boris Cherny 패턴)

코드 변경 후 검증 사이클:

1. 빌드 확인 → docker compose build <서비스>
2. 배포 → /deploy <서비스>
3. health check → 자동 실행 (deploy에 포함)
4. 수동 확인 → 브라우저에서 모바일 + 데스크탑 테스트

6. 효율적 작업 패턴

프론트엔드 수정 (Vanilla JS 서비스)

1. HTML/JS/CSS 수정
2. /cache-bust로 캐시 버스팅 갱신
3. git commit + /deploy system1-web

API 수정 (Node.js 서비스)

1. model → controller → route 수정
2. git commit + /deploy system1-api
3. curl로 API 테스트

tkeg 수정 (React + FastAPI)

1. 프론트: npm run build (Vite 자동 해시, 캐시 버스팅 불필요)
2. 백엔드: FastAPI 코드 수정
3. git commit + /deploy tkeg-api tkeg-web

여러 서비스 동시 수정

1. /plan으로 계획 수립
2. 변경 실행
3. 영향받는 서비스 모두 재배포: /deploy system1-api system1-web system2-api

7. 자주 쓰는 디버깅 명령

# DB 접속 (NAS)
ssh hyungi@100.71.132.52 "docker exec tk-mariadb mysql -uhyungi_user -p'hyung-ddfdf3-D341@' hyungi"

# 로그 확인 (NAS)
ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose logs -f --tail=50 <서비스>"

# 컨테이너 상태 (NAS)
ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose ps"

# PostgreSQL 접속 (tkeg)
ssh hyungi@100.71.132.52 "docker exec tk-tkeg-postgres psql -U tkbom_user -d tk_bom"

8. 팁

• 작은 단위로 커밋: 서비스별로 나눠서 커밋하면 롤백이 쉬움
• CLAUDE.md 업데이트: 새 서비스 추가 시 서비스 맵 테이블 갱신
• 메모리 활용: 반복되는 피드백은 Claude가 자동 저장 → 다음 세션에도 적용