ec59efcdb6
Claude Code 협업 효율화를 위한 문서 체계 구축: - CLAUDE.md: 서비스 맵·코드 규칙·배포 정보 (매 세션 자동 로드) - 슬래시 커맨드 5개: deploy, check-deploy, cache-bust, add-page, add-api - WORKFLOW-GUIDE.md: Plan 모드·서브에이전트·검증 루프 활용 가이드 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# 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가 자동 저장 → 다음 세션에도 적용
|