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를 두 프로젝트가 공유하므로 마이그레이션은 한 곳에서만 관리

---

메뉴 관리 규칙 (필수)

경고: 메뉴 시더(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 명령어 패턴

# 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	모델	설명	출처
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)