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 전용 시더만 허용

마이그레이션 실행

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

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

이유

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

---

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 명령어 패턴

# 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) 업데이트

# 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

서버 환경 업데이트

# 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	설명
organizer-agent	프로젝트 구조화 및 정리
proposal-agent	제안서 작성
research-agent	리서치 및 조사

---

사용 가능한 Skills

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

Skill	설명
pptx-skill	PowerPoint 생성
pdf-template-skill	PDF 템플릿 분석/생성
proposal-skill	제안서 생성
storyboard-generator	스토리보드 생성
code-flow-web-report	코드 플로우 웹 리포트
codebase-analysis-web-report	코드베이스 분석 리포트
code-bug-finder	버그 탐지
code-refactoring	코드 리팩토링
uml-generator	UML 다이어그램 생성
design-skill	디자인 작업

사용 방법: /skill-name 형식으로 호출 (예: /pptx-skill)