sam-docs/CLAUDE.md

# Claude Code 전역 설정

> 이 파일은 모든 프로젝트에 적용되는 전역 규칙입니다.

## 메모리

### sam설명
SAM 프로젝트의 기술적 개요 문서입니다. 이 문서를 참조하면 SAM 프로젝트가 무엇인지 이해할 수 있습니다.

**파일 경로**: `/home/aweso/sam/docs/SAM_PROJECT_OVERVIEW_FOR_AI.md`

**핵심 요약**:
- **회사**: 주일/경동 (블라인드/스크린 제조업체)
- **프로젝트**: SAM (Smart Automation Management) - 차세대 ERP/MES 통합 시스템
- **기술 스택**: Laravel 11 + HTMX + Tailwind CSS + MySQL 8.0
- **아키텍처**: Multi-tenant (tenant_id 기반 데이터 격리)
- **레거시**: 5130.co.kr (PHP 기반) → SAM으로 마이그레이션 중

**사용자가 'sam설명'이라고 말하면**:
1. 위 경로의 `SAM_PROJECT_OVERVIEW_FOR_AI.md` 파일을 읽어서 전체 내용을 파악하세요
2. SAM 프로젝트의 비즈니스 도메인, 기술 스택, 현재 작업 현황을 이해한 상태로 작업하세요

---

## Git 커밋 규칙 (최우선 필수 규칙)

> **경고: 이 규칙은 절대 누락되어서는 안 됩니다!**

### 필수 수행 절차

**모든 코드 작업 완료 후 반드시 다음을 수행:**

1. 변경된 파일이 있는 Git 저장소로 이동
2. `git status`로 변경사항 확인
3. `git add <파일들>` 로 스테이징
4. `git commit -m "type:메시지"` 로 커밋

### 커밋 메시지 형식 (필수)

| Prefix | 사용 시점 | 예시 |
|--------|----------|------|
| `feat:` | 새로운 파일/기능 생성 | `feat:새 기능 추가` |
| `fix:` | 버그 수정, 코드 수정 | `fix:오류 수정` |
| `refactor:` | 코드 리팩토링 | `refactor:구조 개선` |
| `docs:` | 문서 수정 | `docs:README 업데이트` |
| `chore:` | 설정, 빌드 관련 | `chore:설정 변경` |

### Claude Code 설정 파일도 커밋 대상

다음 파일들이 변경되면 반드시 커밋:

| 파일/폴더 | 설명 | 커밋 예시 |
|-----------|------|----------|
| `CLAUDE.md` | 프로젝트 설정 | `docs:CLAUDE.md 규칙 업데이트` |
| `claudedocs/` | Claude 관련 문서 | `docs:기능 분석 문서 추가` |
| `.claude/settings.json` | Claude 설정 | `chore:Claude 설정 변경` |
| `agents/`, `skills/` | 커스텀 에이전트/스킬 | `feat:새 스킬 추가` |

### 체크리스트 (작업 완료 시 확인)

- [ ] 변경된 파일이 있는 저장소에서 git add → git commit
- [ ] CLAUDE.md, claudedocs/, agents/, skills/ 변경 확인 → git commit
- [ ] 커밋 메시지에 적절한 prefix 사용 (feat:/fix:/refactor:/docs:/chore:)
- [ ] 한글로 명확한 커밋 메시지 작성

---

## 주요 프로젝트 경로

| 경로 | 설명 | Git 저장소 |
|------|------|-----------|
| `/home/aweso/sam/mng` | 관리자 웹 (Laravel) | 독립 저장소 |
| `/home/aweso/sam/api` | API 서버 (Laravel) | 독립 저장소 |

**각 폴더는 독립적인 Git 저장소입니다. 해당 폴더에서 git 명령을 실행해야 합니다.**

---

## 데이터베이스 아키텍처 (필수 규칙)

> **경고: 이 규칙을 반드시 준수하세요!**

### 핵심 원칙

**모든 데이터베이스 관련 파일은 API 프로젝트에서만 관리합니다.**

| 항목 | API (`/home/aweso/sam/api`) | MNG (`/home/aweso/sam/mng`) |
|------|----------------------------|----------------------------|
| 마이그레이션 | ✅ 여기에 생성 | ❌ 생성 금지 |
| 시더 | ✅ 여기에 생성 | ⚠️ MNG 전용만 허용 |
| 팩토리 | ✅ 여기에 생성 | ❌ 생성 금지 |

### 금지 사항

```
❌ /home/aweso/sam/mng/database/migrations/ 에 파일 생성 금지
❌ MNG에서 테이블 생성/수정 마이그레이션 작성 금지
```

### 허용 사항

```
✅ /home/aweso/sam/api/database/migrations/ 에 모든 마이그레이션 생성
✅ MNG에서는 MngMenuSeeder 같은 MNG 전용 시더만 허용
```

### 마이그레이션 실행

```bash
# 마이그레이션은 반드시 API 컨테이너에서 실행
docker exec sam-api-1 php artisan migrate

# MNG 컨테이너에서 마이그레이션 실행 금지
# docker exec sam-mng-1 php artisan migrate  ← 사용하지 않음
```

### 이유

- MNG: 프론트엔드/관리자 화면 담당 (컨트롤러, 뷰, 라우트)
- API: 백엔드/데이터베이스 담당 (마이그레이션, 모델 정의, API)
- 단일 DB를 두 프로젝트가 공유하므로 마이그레이션은 한 곳에서만 관리

---

## 메뉴 관리 규칙 (필수)

> **경고: 메뉴 시더(Seeder)를 절대 실행하지 마세요!**

### 배경

메뉴 시더 실행 시 부서별 권한 설정(permission_overrides)이 초기화되는 문제가 반복 발생합니다.
메뉴 ID가 변경되면 기존 부서-메뉴 권한 매핑이 깨지기 때문입니다.

### 금지 사항

```
❌ php artisan db:seed --class=MngMenuSeeder 실행 금지
❌ php artisan db:seed --class=*MenuSeeder 실행 금지
❌ 메뉴 시더 파일 생성 금지
❌ 메뉴 데이터를 일괄 삭제 후 재생성하는 방식 금지
```

### 메뉴 변경 시 올바른 절차

메뉴 추가/수정/삭제/이동이 필요할 때는 **사용자에게 수동 실행 안내**를 제공합니다:

1. **tinker 명령어를 안내** (사용자가 직접 실행)
2. **또는 SQL 쿼리를 안내** (사용자가 phpMyAdmin 등에서 직접 실행)
3. **절대 시더를 만들어 실행하지 않음**

### 안내 예시

```
메뉴를 추가하려면 아래 명령을 서버에서 실행해 주세요:

ssh sam-server "cd /home/webservice/mng && php artisan tinker --execute=\"
App\\Models\\Commons\\Menu::create([
    'tenant_id' => 1,
    'parent_id' => <부모ID>,
    'name' => '새 메뉴',
    'url' => '/new-menu',
    'icon' => 'icon-name',
    'sort_order' => 1,
    'is_active' => true,
]);
\""
```

### 체크리스트 (메뉴 변경 요청 시)

- [ ] 시더 파일 생성하지 않음
- [ ] 시더 실행하지 않음
- [ ] tinker 또는 SQL로 개별 레코드만 수정
- [ ] 변경 후 부서 권한 설정이 유지되는지 확인

---

## Docker 환경 (필수 인지)

> **중요: 로컬 개발 환경은 Docker 기반입니다!**

### 왜 Docker를 통해 실행하나?

PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있습니다.
로컬 PC(WSL)에는 이런 도구들이 없으므로, 반드시 Docker 컨테이너를 통해 실행해야 합니다.

```
로컬 PC (WSL)
└── Docker
    ├── sam-mng-1    ← PHP + Laravel (MNG 앱)
    ├── sam-api-1    ← PHP + Laravel (API 앱)
    ├── sam-mysql-1  ← MySQL DB
    └── sam-nginx-1  ← Nginx 웹서버
```

### Docker 명령어 패턴

```bash
# MNG 앱에서 artisan 명령 실행
docker exec sam-mng-1 php artisan <명령어>

# API 앱에서 artisan 명령 실행
docker exec sam-api-1 php artisan <명령어>

# 예시: 시더 실행
docker exec sam-mng-1 php artisan db:seed --class=MngMenuSeeder

# 예시: 마이그레이션 실행 (API에서만!)
docker exec sam-api-1 php artisan migrate

# 예시: 캐시 클리어
docker exec sam-mng-1 php artisan cache:clear
```

### 체크리스트 (명령 실행 시)

- [ ] `php artisan` 명령 → `docker exec sam-mng-1 php artisan` 또는 `sam-api-1` 사용
- [ ] `composer` 명령 → `docker exec sam-mng-1 composer` 또는 `sam-api-1` 사용
- [ ] DB 시더 실행 필요 시 → Docker를 통해 실행
- [ ] **마이그레이션은 반드시 API에서 실행** → `docker exec sam-api-1 php artisan migrate`

---

## 공동 개발 워크플로우 (필수)

> **중요: 코드를 pull 받은 후 반드시 필요한 명령을 실행하세요!**

### 로컬 환경 (Docker) 업데이트

```bash
# 1. 코드 받기 (WSL에서 실행)
cd /home/aweso/sam/api
git pull

cd /home/aweso/sam/mng
git pull

# 2. 의존성 업데이트 (composer.json 변경 시)
docker exec sam-api-1 composer install
docker exec sam-mng-1 composer install

# 3. DB 마이그레이션 (API에서만!)
docker exec sam-api-1 php artisan migrate

# 4. 캐시 클리어 (설정 변경 시)
docker exec sam-api-1 php artisan config:clear
docker exec sam-mng-1 php artisan config:clear
```

### 서버 환경 업데이트

```bash
# API 프로젝트
cd /home/webservice/api
git pull
composer install
php artisan migrate
php artisan config:clear

# MNG 프로젝트 (마이그레이션 없음)
cd /home/webservice/mng
git pull
composer install
php artisan config:clear
```

### 요약 표

| 작업 | 로컬 (Docker) | 서버 |
|------|--------------|------|
| git pull | WSL에서 직접 | 서버에서 직접 |
| composer install | `docker exec sam-api-1 composer install` | `composer install` |
| migrate | `docker exec sam-api-1 php artisan migrate` | `php artisan migrate` |
| config:clear | `docker exec sam-api-1 php artisan config:clear` | `php artisan config:clear` |

### 체크리스트 (pull 후)

- [ ] API: `git pull` → `composer install` → `php artisan migrate` → `config:clear`
- [ ] MNG: `git pull` → `composer install` → `config:clear` (마이그레이션 없음)

---

## 사용 가능한 Agents

`~/.claude/agents/` 폴더에 있는 에이전트들:

### 코드 품질 & 개발

| Agent | 모델 | 설명 | 출처 |
|-------|------|------|------|
| `code-reviewer` | sonnet | 코드 리뷰 (품질/보안/유지보수성), 메모리 학습 지원 | 공식 문서 패턴 |
| `debugger` | sonnet | 에러/테스트 실패 근본 원인 분석 및 수정 | 공식 문서 패턴 |
| `test-runner` | haiku | 테스트 실행 및 결과 분석/요약 | 커뮤니티 인기 |
| `security-auditor` | sonnet | OWASP Top 10 기반 보안 취약점 감사 | 커뮤니티 인기 |
| `performance-optimizer` | sonnet | N+1 쿼리, 알고리즘, 캐싱 최적화 | 커뮤니티 인기 |
| `refactoring-agent` | sonnet | 코드 구조 개선, SOLID 원칙, DRY 위반 제거 | 커뮤니티 인기 |
| `laravel-expert` | sonnet | Laravel 전문가 (SAM 프로젝트 환경 인지) | 커스텀 |

### 워크플로우 & 문서

| Agent | 모델 | 설명 | 출처 |
|-------|------|------|------|
| `git-manager` | haiku | Git 브랜치/커밋/머지/PR 관리 | 커뮤니티 인기 |
| `doc-writer` | haiku | API 문서, README, 기술 가이드 작성 | 커뮤니티 인기 |
| `research-agent` | sonnet | 웹 리서치 및 자료 조사 | 기존 |
| `organizer-agent` | - | 프로젝트 구조화 및 정리 | 기존 |
| `proposal-agent` | - | 제안서 작성 | 기존 |

---

## 사용 가능한 Skills

`~/.claude/skills/` 폴더에 있는 스킬들 (슬래시 명령어로 사용):

### 문서/프레젠테이션

| Skill | 설명 |
|-------|------|
| `pptx-skill` | PowerPoint 생성 |
| `ppt-auto-generator` | 마크다운/텍스트에서 PPT 생성 |
| `pdf-template-skill` | PDF 템플릿 분석/생성 |
| `text-analyzer-skill` | 텍스트 분석 및 PDF 구조 매핑 |
| `proposal-skill` | 제안서 생성 |
| `storyboard-generator` | 스토리보드 생성 |
| `design-skill` | 프레젠테이션 HTML 디자인 |

### 코드 분석/시각화

| Skill | 설명 |
|-------|------|
| `code-flow-web-report` | 웹 앱 런타임 흐름 시각화 리포트 |
| `code-flow-web-doc-generator` | 소스 코드 호출/데이터 흐름 다이어그램 HTML 생성 |
| `codebase-analysis-web-report` | 코드베이스 아키텍처 인터랙티브 HTML 리포트 |
| `uml-generator` | UML 다이어그램 생성 |

### 코드 품질 (levnikolaevich/claude-code-skills)

| Skill | 설명 | 출처 |
|-------|------|------|
| `code-bug-finder` | 버그 자동 탐지 및 보고서 생성 | 기존 |
| `code-refactoring` | 리팩토링 권장사항/성능 분석/코드 패치 | 기존 |
| `code-commenter` | 소스 코드에 이해하기 쉬운 주석 추가 | 기존 |
| `async-await-keyword-fixer` | JS/TS 누락된 async/await 수정 | 기존 |
| `code-quality-checker` | DRY/KISS/YAGNI 위반 탐지 | levnikolaevich |
| `code-quality-auditor` | 코드 복잡도, 매직넘버 분석 | levnikolaevich |
| `code-principles-auditor` | DRY/KISS/YAGNI, TODO, DI 패턴 검사 | levnikolaevich |
| `dead-code-auditor` | 미사용 코드 탐지 | levnikolaevich |
| `build-auditor` | 컴파일러/타입 에러 검사 | levnikolaevich |
| `concurrency-auditor` | 레이스 컨디션 탐지 | levnikolaevich |
| `layer-boundary-auditor` | 레이어 위반, I/O 격리 검사 | levnikolaevich |
| `observability-auditor` | 로깅, 메트릭 적절성 검사 | levnikolaevich |
| `query-efficiency-auditor` | DB 쿼리 효율성 분석 | levnikolaevich |
| `dependencies-auditor` | 오래된 패키지, CVE 취약점 검사 | levnikolaevich |
| `regression-checker` | 기존 테스트 실행으로 사이드이펙트 탐지 | levnikolaevich |
| `story-quality-gate` | 코드리뷰 + 테스트 2단계 품질 검증 | levnikolaevich |

### 테스트/커버리지

| Skill | 설명 | 출처 |
|-------|------|------|
| `app-comprehensive-test-generator` | 테스트 시나리오 생성/실행, QA 리포트 | 기존 |
| `coverage-improvement-planner` | 테스트 커버리지 분석 및 개선 계획 | 기존 |
| `test-coverage-auditor` | 테스트 커버리지 측정/분석 | levnikolaevich |
| `test-isolation-auditor` | 테스트 독립성/격리 검사 | levnikolaevich |
| `webapp-testing` | Playwright 기반 웹 앱 UI 테스트 | anthropics 공식 |

### 보안 (Trail of Bits)

| Skill | 설명 | 출처 |
|-------|------|------|
| `security-auditor` | 시크릿 노출, Injection, XSS 탐지 | levnikolaevich |
| `static-analysis` | CodeQL/Semgrep/SARIF 정적 분석 (3개 하위 스킬) | Trail of Bits |
| `insecure-defaults` | 위험한 기본 설정, 하드코딩 자격증명 탐지 | Trail of Bits |
| `sharp-edges` | 에러 유발 API, 위험한 디자인 패턴 탐지 | Trail of Bits |
| `differential-review` | 보안 중심 코드 변경 리뷰 | Trail of Bits |

### 디버깅/로깅

| Skill | 설명 |
|-------|------|
| `system-debug-logger` | 에러/예외 자동 캡처 디버그 로깅 |
| `node-debug-logging-middleware` | Node.js Express/Koa 디버깅 로그 미들웨어 |

### 프론트엔드/UI

| Skill | 설명 | 출처 |
|-------|------|------|
| `frontend-design` | 프론트엔드 디자인 품질 향상 (AI slop 방지) | anthropics 공식 |
| `flutter-ux-hardening` | Flutter 앱 UI/UX 강화 | 기존 |
| `웹문서` | SAM 프로젝트 웹문서 디자인 표준 | 기존 |

### 유틸리티

| Skill | 설명 |
|-------|------|
| `duplicate-file-cleaner` | 중복 이미지/미디어 파일 정리 |
| `npm-release-manager` | NPM 패키지 배포 자동화 |

**사용 방법**: `/skill-name` 형식으로 호출 (예: `/code-quality-checker`)