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 생성
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)