# 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. 자주 쓰는 디버깅 명령

```bash
# 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가 자동 저장 → 다음 세션에도 적용