docs: CLAUDE.md + 슬래시 커맨드 + 워크플로우 가이드 추가

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>
2026-03-16 15:13:49 +09:00
parent c2e8b58849
commit ec59efcdb6
7 changed files with 259 additions and 0 deletions
--- a/.claude/WORKFLOW-GUIDE.md
+++ b/.claude/WORKFLOW-GUIDE.md
@@ -0,0 +1,92 @@
+# 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가 자동 저장 → 다음 세션에도 적용
--- a/.claude/commands/add-api.md
+++ b/.claude/commands/add-api.md
@@ -0,0 +1,30 @@
+System1(system1-factory) 새 API 엔드포인트를 생성합니다.
+
+인자: $ARGUMENTS (예: "consumable-stock 소모품 재고" 또는 리소스명)
+
+절차:
+1. 기존 패턴 확인:
+   - system1-factory/api/ 아래 기존 model, controller, route 파일 하나씩 읽어 패턴 파악
+
+2. Model 생성 (`api/models/<리소스>.js`):
+   - Knex 기반 DB 쿼리 패턴
+   - CRUD 기본 메서드: getAll, getById, create, update, delete
+
+3. Controller 생성 (`api/controllers/<리소스>Controller.js`):
+   - responseFormatter (res.success, res.error, res.paginated) 사용
+   - try/catch + 에러 핸들링 패턴
+   - 페이지네이션 지원 (GET list)
+
+4. Route 생성 (`api/routes/<리소스>Routes.js`):
+   - Express Router
+   - auth 미들웨어 적용
+   - RESTful 패턴: GET /, GET /:id, POST /, PUT /:id, DELETE /:id
+
+5. 라우트 등록:
+   - `api/config/routes.js` (또는 app.js/server.js)에 새 라우트 추가
+
+6. 생성된 파일 목록 + API 엔드포인트 정리 보고
+
+주의:
+- 다른 서비스(system2, tkpurchase 등)의 API 추가 시 해당 서비스의 패턴을 먼저 확인
+- System3, tkeg는 FastAPI 패턴 (Python)
--- a/.claude/commands/add-page.md
+++ b/.claude/commands/add-page.md
@@ -0,0 +1,25 @@
+System1(system1-factory) 새 HTML 페이지를 생성합니다.
+
+인자: $ARGUMENTS (예: "consumable/stock 소모품 재고 관리")
+→ 경로와 페이지 제목을 파싱
+
+절차:
+1. 기존 페이지를 템플릿으로 사용:
+   - system1-factory/web/ 아래 비슷한 기능의 기존 HTML 페이지를 찾아 참조
+   - 공통 구조: 헤더(nav), 사이드네비, 메인 콘텐츠 영역
+
+2. 새 HTML 파일 생성 (`system1-factory/web/<경로>.html`):
+   - 공통 CSS: tkfb.css, Tailwind CDN, Font Awesome
+   - 공통 JS: tkfb-core.js, api-base.js
+   - 페이지 제목, 설명 커스터마이즈
+   - 사이드네비에 현재 페이지 active 표시
+
+3. 대응 JS 컨트롤러 파일 생성 (필요 시):
+   - `system1-factory/web/js/<경로>.js`
+   - 기존 JS 패턴 따르기 (DOMContentLoaded, API 호출 등)
+
+4. 생성된 파일 목록 보고 + 캐시 버스팅 안내
+
+주의:
+- 다른 서비스(system2, system3 등)에 페이지 추가 시 해당 서비스의 패턴을 먼저 확인
+- HTML의 script/link 태그에 ?v= 버전 포함
--- a/.claude/commands/cache-bust.md
+++ b/.claude/commands/cache-bust.md
@@ -0,0 +1,20 @@
+커밋 전 변경된 JS/CSS 파일에 대해 캐시 버스팅 버전을 갱신합니다.
+
+절차:
+1. `git diff --name-only HEAD`로 아직 커밋 안 된 변경사항 중 .js, .css 파일 목록 추출
+   - staged + unstaged 모두 포함: `git diff --name-only HEAD` + `git diff --name-only --cached`
+   - untracked 파일도 포함: `git ls-files --others --exclude-standard -- '*.js' '*.css'`
+
+2. 각 변경된 JS/CSS 파일에 대해:
+   - 해당 파일을 참조하는 HTML 파일을 grep으로 검색 (같은 서비스 디렉토리 내)
+   - `<script src="...파일명...?v=...">` 또는 `<link href="...파일명...?v=...">` 패턴 찾기
+
+3. 찾은 HTML 참조의 `?v=` 버전을 오늘 날짜 기반으로 갱신:
+   - 포맷: `?v=YYYYMMDD01` (같은 날 여러 번이면 NN 증가)
+   - 기존 ?v= 없으면 추가
+
+4. 변경된 HTML 파일 목록과 갱신된 버전 번호를 보고
+
+주의사항:
+- tkeg는 Vite 빌드이므로 제외 (자동 해시)
+- 같은 파일의 ?v=를 여러 HTML에서 참조할 수 있으므로 모두 갱신
--- a/.claude/commands/check-deploy.md
+++ b/.claude/commands/check-deploy.md
@@ -0,0 +1,25 @@
+NAS 서비스 상태 점검:
+
+1. SSH로 docker compose ps 실행:
+   ```
+   ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose ps"
+   ```
+
+2. 각 주요 서비스 health check (curl로 확인):
+   - Gateway (30000): curl http://100.71.132.52:30000/
+   - SSO Auth (30050): curl http://100.71.132.52:30050/health
+   - System1 API (30005): curl http://100.71.132.52:30005/api/health
+   - System2 API (30105): curl http://100.71.132.52:30105/api/health
+   - System3 API (30200): curl http://100.71.132.52:30200/health
+   - tkuser API (30300): curl http://100.71.132.52:30300/api/health
+   - tkpurchase API (30400): curl http://100.71.132.52:30400/api/health
+   - tksafety API (30500): curl http://100.71.132.52:30500/api/health
+   - tksupport API (30600): curl http://100.71.132.52:30600/api/health
+   - tkeg API (30700): curl http://100.71.132.52:30700/health
+
+3. 로컬 vs NAS git 커밋 비교:
+   - 로컬: `git rev-parse HEAD`
+   - NAS: `ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && git rev-parse HEAD"`
+   - 차이가 있으면 어떤 커밋이 빠져있는지 보고
+
+4. 결과를 표로 정리하여 보고 (서비스명 | 상태 | health check | 비고)
--- a/.claude/commands/deploy.md
+++ b/.claude/commands/deploy.md
@@ -0,0 +1,26 @@
+전제조건: Tailscale SSH 키 인증 (hyungi@100.71.132.52) 설정 완료
+
+서비스명: $ARGUMENTS
+
+배포 실행 절차:
+1. `git status`로 커밋 안 된 변경사항 확인 → 있으면 사용자에게 경고하고 계속할지 확인
+2. `git push` 실행
+3. SSH로 NAS에서 배포:
+   ```
+   ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && git pull && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose up -d --build $ARGUMENTS"
+   ```
+4. 30초 대기 후 health check:
+   - API 서비스면: `curl -s http://100.71.132.52:<포트>/api/health` 또는 `/health`
+   - Web 서비스면: `curl -s -o /dev/null -w '%{http_code}' http://100.71.132.52:<포트>/`
+5. 결과 보고 (성공/실패, 걸린 시간)
+
+서비스별 포트 매핑:
+- system1-api: 30005, system1-web: 30080
+- system2-api: 30105, system2-web: 30180
+- system3-api: 30200, system3-web: 30280
+- tkuser-api: 30300, tkuser-web: 30380
+- tkpurchase-api: 30400, tkpurchase-web: 30480
+- tksafety-api: 30500, tksafety-web: 30580
+- tksupport-api: 30600, tksupport-web: 30680
+- tkeg-api: 30700, tkeg-web: 30780
+- gateway: 30000, sso-auth: 30050
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,41 @@
+# CLAUDE.md — TK Factory Services
+
+## 프로젝트 개요
+공장관리 플랫폼. 8개 마이크로서비스, 21개+ Docker 컨테이너. Synology NAS 배포, Cloudflare Tunnel.
+
+## 서비스 맵
+| 서비스 | 디렉토리 | 스택 | API/Web 포트 | DB |
+|--------|----------|------|-------------|-----|
+| Gateway | gateway/ | nginx | 30000 | - |
+| SSO Auth | sso-auth-service/ | Node.js | 30050 | MariaDB |
+| System1 공장관리 | system1-factory/ | Node.js + nginx | 30005/30080 | MariaDB |
+| System2 신고 | system2-report/ | Node.js + nginx | 30105/30180 | MariaDB |
+| System3 부적합 | system3-nonconformance/ | FastAPI + nginx | 30200/30280 | MariaDB |
+| tkuser 사용자 | user-management/ | Node.js + nginx | 30300/30380 | MariaDB |
+| tkpurchase 소모품 | tkpurchase/ | Node.js + nginx | 30400/30480 | MariaDB |
+| tksafety 안전 | tksafety/ | Node.js + nginx | 30500/30580 | MariaDB |
+| tksupport 행정 | tksupport/ | Node.js + nginx | 30600/30680 | MariaDB |
+| tkeg BOM | tkeg/ | FastAPI + React(Vite) | 30700/30780 | PostgreSQL |
+
+System1에는 FastAPI bridge도 있음 (30008, AI 연동용).
+
+## 기술 스택
+- **프론트엔드**: Vanilla JS + Tailwind CDN + Font Awesome (빌드 없음). tkeg만 React+Vite+MUI
+- **백엔드(Node)**: Express + mysql2/Knex. 패턴: Routes → Controllers → Services → Models → DB
+- **백엔드(Python)**: FastAPI + SQLAlchemy (System3, tkeg)
+- **DB**: MariaDB 공유(hyungi) + PostgreSQL(tkeg: tk_bom) + Redis(세션)
+- **인증**: JWT SSO — sso_token 쿠키(domain=.technicalkorea.net) + localStorage 폴백
+- **접근레벨**: worker(1) < group_leader(2) < support_team(3) < admin(4) < system(5)
+
+## 코드 규칙
+1. **캐시 버스팅 필수**: JS/CSS 수정 시 HTML `<script>`/`<link>` 태그의 `?v=YYYYMMDDNN` 반드시 갱신
+2. **API 응답 포맷**: `{ success: true, data: {...}, message: "..." }` — res.success(), res.paginated() 등
+3. **커밋 메시지**: `type(scope): 한국어 설명` (예: `fix(tkfb): 모바일 레이아웃 수정`)
+4. **CSS 전역**: system1-factory → tkfb.css (모든 페이지 로드). 모바일 = @media (max-width: 768px)
+
+## 배포
+전제: Tailscale SSH 키 인증 설정 완료 (hyungi@100.71.132.52)
+```bash
+git push && ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && git pull && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose up -d --build <서비스명>"
+```
+상세: DEPLOY-GUIDE.md 참조. 아키텍처: ARCHITECTURE.md 참조.