sam-docs/CLAUDE.md

Claude Code 전역 설정

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

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