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 12 + HTMX + Tailwind CSS + MySQL 8.0 (PHP 8.4)
• 아키텍처: Multi-tenant (tenant_id 기반 데이터 격리)
• 레거시: 5130.co.kr (PHP 기반) → SAM으로 마이그레이션 중

사용자가 'sam설명'이라고 말하면:

1. 위 경로의 SAM_PROJECT_OVERVIEW_FOR_AI.md 파일을 읽어서 전체 내용을 파악하세요
2. SAM 프로젝트의 비즈니스 도메인, 기술 스택, 현재 작업 현황을 이해한 상태로 작업하세요

---

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

경고: 이 규칙은 절대 누락되어서는 안 됩니다! 기준 문서: sam/docs/standards/git-conventions.md

필수 수행 절차

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

1. 변경된 파일이 있는 Git 저장소로 이동
2. git status로 변경사항 확인
3. git add <파일들> 로 스테이징
4. git commit -m "type: [scope] 작업내용" 로 커밋

커밋 메시지 형식 (필수)

type: [scope] 작업내용

- 세부항목 (생략가능)
- 세부항목 2

Issue: URL (생략가능)

예시:

feat: [calendar] 달력 기능 개선

- 클릭시 오류 기능 개선
- 색상 변경

fix: [auth] 로그인 시 세션 만료 오류 수정

Commit Types

Type	설명	예시
feat	새로운 기능 추가	feat: [file] 파일 업로드 기능 추가
fix	버그 수정	fix: [auth] 세션 만료 오류 수정
chore	설정, 빌드 등 변경	chore: composer 패키지 업데이트
refactor	프로덕션 코드 리팩토링	refactor: [user] 서비스 메서드 분리
style	포맷/코딩 스타일 수정	style: Pint 포맷팅 적용
test	테스트 추가/수정	test: Product API 테스트 추가
docs	문서 변경	docs: API 문서 업데이트

Claude 서명 제외 (필수)

❌ Co-Authored-By: Claude <noreply@anthropic.com> — 포함 금지
❌ 🤖 Generated with Claude Code — 포함 금지

• Git hooks로 자동 제거됨
• 간결하고 명확한 한글 커밋 메시지만 유지

푸시 정책

MNG 자동 푸시 (커밋 즉시 배포)

MNG 프로젝트는 커밋 후 자동으로 개발+운영 서버에 배포한다. 트리거 워드 불필요.

커밋 완료 후 자동 실행 절차:

1. git push origin develop (개발 서버 배포)
2. git checkout main && git pull origin main (최신화)
3. git cherry-pick <방금_커밋_해시> (운영 반영)
4. git push origin main (운영 서버 배포)
5. git checkout develop (작업 브랜치 복귀)

# MNG 커밋 후 자동 실행 예시
cd /home/aweso/sam/mng
git push origin develop
git checkout main && git pull origin main
git cherry-pick abc1234
git push origin main
git checkout develop

충돌 발생 시: 사용자에게 알리고 해결 지원 (자동 중단하지 않음) 여러 커밋 연속 시: 마지막 커밋 후 한 번만 실행 (중간 커밋에서는 생략 가능)

API / React 푸시 (트리거 워드 기반)

API, React는 기존대로 사용자가 트리거 워드를 말할 때만 푸시 실행.

트리거: "개발서버 푸시"

사용자가 **"개발서버 푸시"**라고 말하면 다음을 자동 실행:

1. 각 프로젝트(api, mng, react)에서 git status 확인
2. 커밋되지 않은 변경사항이 있으면 커밋 규칙에 따라 커밋
3. 현재 브랜치가 develop인지 확인 (아니면 develop으로 전환)
4. git push origin develop 실행 (변경사항 있는 프로젝트만)
5. 결과 요약 출력

# 변경사항 있는 프로젝트만 실행
cd /home/aweso/sam/api && git push origin develop
cd /home/aweso/sam/mng && git push origin develop
cd /home/aweso/sam/react && git push origin develop

Jenkins가 Gitea Webhook으로 개발 서버에 자동 배포한다.

트리거: "운영서버 푸시"

사용자가 **"운영서버 푸시"**라고 말하면 다음을 자동 실행:

전제: develop의 변경사항이 개발 서버에서 테스트 완료된 상태 방식: cherry-pick — 이번 세션에서 작업한 커밋만 골라서 main에 반영 (develop 전체 머지 금지)

1. 각 프로젝트에서 develop에 미푸시 커밋 확인 → 있으면 먼저 git push origin develop
2. 체리픽 대상 커밋 식별 — 이번 세션에서 작업한 커밋 해시 목록을 git log --oneline으로 확인하여 사용자에게 표시
3. 사용자에게 체리픽 대상 커밋 목록을 보여주고 확인 받기
4. git checkout main (모든 프로젝트 운영 브랜치: main)
5. git pull origin main — 최신화 (충돌 방지 핵심 단계)
6. git cherry-pick <commit1> <commit2> ... — 확인받은 커밋만 순서대로 적용
7. 충돌 발생 시 → 사용자에게 알리고 해결 지원
8. git push origin main — Jenkins가 운영 서버에 자동 배포
9. git checkout develop — 작업 브랜치로 복귀
10. 결과 요약 출력 (체리픽한 커밋 목록 포함)

# 예시: mng에서 이번 세션 커밋 2개만 체리픽
cd /home/aweso/sam/mng

# 1. develop 미푸시 확인
git push origin develop

# 2. 체리픽 대상 확인 (사용자 승인)
git log --oneline  # → abc1234, def5678

# 3. main 전환 및 최신화
git checkout main && git pull origin main

# 4. 선택한 커밋만 체리픽 (시간순 — 오래된 것부터)
git cherry-pick abc1234 def5678

# 5. 푸시 및 복귀
git push origin main
git checkout develop

merge와의 차이: git merge develop은 develop의 모든 커밋을 main에 반영하지만, git cherry-pick은 지정한 커밋만 반영한다. 다른 개발자의 미검증 커밋이 운영에 올라가는 문제를 방지한다. 주의: cherry-pick 후 develop에 main을 머지하지 않는다. 동일 변경이 이미 develop에 존재하므로 불필요하다.

운영서버 푸시 대상 프로젝트 (2026-02-27~)

프로젝트	개발서버 푸시	운영서버 푸시	비고
MNG	✅	✅
API	✅	✅	2026-02-27부터 허용
React	✅	❌ 중지	개발 완료 시점에 배포 예정

"운영서버 푸시" 트리거 시 MNG + API만 cherry-pick → main push 실행. React는 develop push만 수행.

푸시 대상 자동 판별

조건	동작
현재 작업 디렉토리가 특정 프로젝트	해당 프로젝트만 푸시
sam/ 루트이거나 명시 없음	3개 프로젝트 모두 확인 후 변경사항 있는 것만 푸시
사용자가 프로젝트 지정 ("api 개발서버 푸시")	지정된 프로젝트만 푸시

Claude Code 설정 파일도 커밋 대상

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

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

커밋 전 체크리스트

• ./vendor/bin/pint 실행 (코드 포맷팅, 해당 시)
• git diff로 변경사항 검토
• 불필요한 파일 제외 (.env, node_modules 등)
• 변경된 파일이 있는 저장소에서 git add → git commit
• CLAUDE.md, claudedocs/, agents/, skills/ 변경 확인 → git commit
• 커밋 메시지: type: [scope] 한글 작업내용 형식 준수
• Co-Authored-By 서명 미포함 확인

---

주요 프로젝트 경로

경로	설명	Git 저장소
/home/aweso/sam/mng	관리자 웹 (Laravel)	독립 저장소
/home/aweso/sam/api	API 서버 (Laravel)	독립 저장소
/home/aweso/sam/react	프론트엔드 (Next.js)	독립 저장소

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

서버 경로 참고:

• 개발/운영 서버 모두 /home/webservice/ 하위에 동일한 구조로 배치
• 서버: /home/webservice/api, /home/webservice/mng, /home/webservice/react, /home/webservice/sales

---

서버 접근 정책 (3단계 분류)

2026-02-21 사고 교훈: Claude가 서버에 SSH로 접속하여 설정을 변경한 결과 502 Bad Gateway 발생. → 교훈: 읽기는 허용, 변경은 확인 후, 위험 작업은 금지

핵심 원칙

서버 접근을 3단계로 분류하여 관리한다:

단계	분류	정책
🟢 Level 1	읽기 전용 (진단/조회)	자유 허용 — 사용자 요청 시 즉시 실행
🟡 Level 2	경미한 변경	사용자 확인 후 실행 — 실행 전 명령어를 보여주고 승인받기
🔴 Level 3	위험한 변경	절대 금지 — 안내만 제공

🟢 Level 1: 읽기 전용 (자유 허용)

사용자가 서버 진단/조회를 요청하면 즉시 SSH 접속하여 실행 가능:

✅ ls, cat, head, tail, less — 파일/디렉토리 조회
✅ ps aux, top, htop — 프로세스 확인
✅ df -h, free -m — 디스크/메모리 확인
✅ git status, git log, git diff — Git 상태 조회
✅ stat, id, whoami — 권한/소유자 확인
✅ nginx -t, php -v — 설정 검증 (변경 아닌 테스트만)
✅ tail -f /var/log/*.log — 로그 조회
✅ systemctl status — 서비스 상태 조회
✅ crontab -l — 크론 작업 조회

🟡 Level 2: 경미한 변경 (확인 후 실행)

실행 전 명령어를 사용자에게 보여주고 승인받은 후 실행:

⚠️ git pull — 코드 업데이트
⚠️ composer install — 의존성 설치
⚠️ php artisan migrate — DB 마이그레이션
⚠️ php artisan config:clear, cache:clear — 캐시 초기화
⚠️ chmod, chown — 파일 권한 변경 (소규모)
⚠️ systemctl restart — 서비스 재시작
⚠️ npm install — 패키지 설치

실행 절차:

1. 실행할 명령어를 먼저 사용자에게 표시
2. 사용자 승인 확인
3. 승인 후 실행

🔴 Level 3: 위험한 변경 (절대 금지 — 안내만)

Claude가 절대 직접 실행하지 않으며, 사용자에게 명령어를 안내만 제공:

❌ rm -rf, 대량 파일 삭제
❌ nginx/apache 설정 파일 직접 수정
❌ /etc/ 하위 시스템 설정 변경
❌ 서버에서 npm run build (메모리 부족 위험)
❌ DB 직접 수정 (DROP, TRUNCATE, 대량 UPDATE/DELETE)
❌ 방화벽(iptables, ufw) 규칙 변경
❌ 사용자 계정 생성/삭제/비밀번호 변경
❌ scp, rsync로 대량 파일 전송
❌ 프로세스 강제 종료 (kill -9)
❌ 서버 재부팅

서버 접속 정보

서버	호스트	계정	SSH 접근	역할
개발 서버	114.203.209.83	pro, hskwon	Claude 가능	개발/스테이징 + Jenkins CI/CD + Gitea
운영 서버	(비공개)	별도 계정	Claude 불가 — 개발팀장만 접근	정식 서비스

참고: Jenkins(114.203.209.83:8080)와 Gitea(114.203.209.83:3000)는 개발 서버에서 운영한다.

운영 서버 정책: Claude는 운영 서버에 SSH 접속할 수 없다. IP 접근이 제한되어 있으며 개발팀장만 접근 가능하다. 운영 배포는 git push origin main → Jenkins 자동 배포로만 이루어지며, 운영 서버 상태 확인이 필요하면 사용자(개발팀장)에게 요청한다.

배포 흐름 (Jenkins CI/CD)

Claude 역할                   Jenkins (자동)              운영 서버
┌───────────────────┐         ┌──────────────────┐       ┌──────────────┐
│ 코드 작성/수정     │         │                  │       │              │
│ git add / commit   │         │                  │       │              │
│                    │─push──→ │ Gitea Webhook    │       │              │
│                    │(사용자) │ → Jenkins 빌드   │       │              │
│                    │         │ → Lint/Test      │       │              │
│                    │         │ → SSH Deploy ────│──→    │ git pull     │
│                    │         │                  │       │ composer     │
│ 서버 진단 (L1)    │         │                  │       │ migrate      │
│ 서버 변경 (L2)    │─확인──→ │                  │       │              │
│ 위험 작업 (L3)    │─안내──→ │                  │       │ (팀장 직접)  │
└───────────────────┘         └──────────────────┘       └──────────────┘

브랜치 전략: develop → 개발 서버 (자동 배포), main → 운영 서버 (PR 머지 + 팀장 승인)

체크리스트 (서버 작업 시)

• Level 1 (읽기): 사용자 요청 시 즉시 실행
• Level 2 (변경): 명령어를 보여주고 승인 후 실행
• Level 3 (위험): 절대 직접 실행하지 않고 안내만 제공
• 사고 방지: 설정 파일 수정, 서비스 중단 가능성 있는 작업은 Level 3

---

React 빌드/배포 정책 (필수 규칙)

경고: React(Next.js) 빌드를 운영 서버에서 직접 실행하지 않는다!

배경

개발 서버(2코어, 3.8GB RAM + Swap 4GB)에서 Jenkins가 React 빌드를 수행한다. Jenkins 빌드 실패 시 로컬(WSL)에서 빌드 후 결과물을 서버에 배포한다(fallback).

금지 사항

❌ 운영 서버에서 npm run build 실행 금지
❌ 서버 SSH 접속 후 빌드 명령 실행 금지
❌ Claude가 직접 npm run build 실행 금지 (로컬 포함)

빌드/배포 방법 (Jenkins 자동화)

Claude 역할                 Jenkins (자동)              운영 서버
┌─────────────────┐         ┌──────────────────┐       ┌──────────────┐
│ 코드 작성/수정   │         │ Checkout         │       │              │
│ git commit       │─push──→ │ Install + Lint   │       │              │
│                  │(사용자) │ Build (Next.js)  │       │              │
│                  │         │ Package (tar.gz) │──scp→ │ 압축 해제    │
│                  │         │                  │       │ node 재시작  │
└─────────────────┘         └──────────────────┘       └──────────────┘

Fallback: Jenkins 빌드 실패(OOM) 시 로컬에서 react/deploy.sh로 수동 배포

빌드가 필요한 상황

사용자에게 다음과 같이 안내한다:

React 코드가 변경되었습니다. git push 후 Jenkins가 자동 배포합니다.
(Jenkins 실패 시 로컬에서 deploy.sh로 수동 배포해주세요.)

---

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

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

핵심 원칙

모든 데이터베이스 관련 파일은 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

# 개발 서버: Docker 없음, 직접 실행
cd /home/webservice/api && php artisan migrate

# 운영 서버: --force 플래그 필수 (production 환경)
cd /home/webservice/api && php artisan migrate --force

# MNG에서 마이그레이션 실행 금지 (로컬/서버 모두)

DB 환경 분리

환경	DB명	호스트	용도
로컬 (Docker)	samdb	sam-mysql-1:3306	개발/테스트
개발 서버	samdb	localhost	스테이징
운영 서버	sam_prod	localhost	정식 서비스
통계 DB	sam_stat	동일 서버	StatMonitorService 전용

참고: sam_stat은 API/MNG 모두 config/database.php의 별도 connection으로 접속한다.

이유

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

테이블 생성/수정 시 options JSON 컬럼 정책 (필수)

경고: 테이블 생성/수정, 마이그레이션 작성, 모델 생성 시 반드시 아래 정책 문서를 먼저 읽고 준수하세요! 정책 문서: /home/aweso/sam/docs/standards/options-column-policy.md

핵심 원칙: FK/조인키만 전용 컬럼, 나머지 속성은 options JSON에 저장

전용 컬럼 (일반 컬럼)	options JSON
FK/조인키 (다른 테이블 참조)	테넌트별로 다를 수 있는 확장 속성
WHERE/ORDER BY 자주 사용 필드	선택적(nullable) 부가 정보
UNIQUE 제약 필드	구조가 유동적인 데이터
INDEX 필요한 고빈도 조회 필드	드롭다운 선택지 목록
집계(SUM/AVG) 대상	이력/스냅샷성 데이터

필수 준수 사항:

✅ 모든 비즈니스 테이블에 $table->json('options')->nullable() 포함
✅ 모델 cast: 'options' => 'array' (❌ 'json' 금지)
✅ 모델에 getOption() / setOption() 헬퍼 메서드 추가
✅ options 키 3개 이상 시 OPTION_* 상수 정의
✅ options 수정 시 setOption() 사용 (전체 덮어쓰기 금지)
✅ API 응답 노출 시 accessor + $appends 추가

작업 전 체크리스트:

• 정책 문서(docs/standards/options-column-policy.md) 읽기
• 새 필드가 전용 컬럼인지 options인지 판단 (판단 흐름도 참고)
• 마이그레이션에 options JSON 컬럼 포함 확인
• 모델에 'options' => 'array' cast + 헬퍼 메서드 포함 확인

---

메뉴 관리 규칙 (필수)

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

배경

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

금지 사항

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

메뉴 변경 시 올바른 절차

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

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

안내 예시

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

# 개발 서버
ssh pro@114.203.209.83 "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,
]);
\""

# 운영 서버 (동일 경로, 서버 주소만 변경)
ssh <운영계정>@<운영서버IP> "cd /home/webservice/mng && php artisan tinker --execute=\"...동일...\""

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

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

---

실행 환경 (필수 인지)

중요: 로컬 / 개발 서버 / 운영 서버의 환경이 다릅니다!

환경 비교 (3-Tier)

항목	로컬 (WSL)	개발 서버	운영 서버
구성 방식	Docker 컨테이너	Bare-metal (네이티브)	Bare-metal (네이티브)
PHP	컨테이너 내부 (8.4)	직접 설치 (8.4)	직접 설치 (8.4)
MySQL	컨테이너 (sam-mysql-1)	직접 설치 (8.0)	직접 설치 (8.0)
Nginx	컨테이너 (sam-nginx-1)	직접 설치	직접 설치
명령 실행	docker exec 필요	직접 실행	직접 실행
서버 IP	localhost	114.203.209.83	(신규, 미확정)
추가 서비스	—	Jenkins, Gitea	—
DB	samdb	samdb	sam_prod

배경: 서버는 Docker가 무거워서 PHP, Nginx, MySQL 등을 네이티브로 설치하여 운영한다.

로컬 환경 (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 웹서버

서버 환경 (Bare-metal — 개발/운영 동일 구조)

서버에는 Docker가 없다. PHP 8.4, Nginx, MySQL 8.0이 직접 설치되어 있다.

개발 서버 (114.203.209.83)              운영 서버 (신규)
├── Nginx                               ├── Nginx
├── PHP-FPM (3 pools)                   ├── PHP-FPM (3 pools)
│   ├── api.sock                        │   ├── api.sock
│   ├── mng.sock                        │   ├── mng.sock
│   └── sales.sock                      │   └── sales.sock
├── MySQL 8.0 (samdb)                   ├── MySQL 8.0 (sam_prod)
├── Supervisor                          ├── Supervisor
│   ├── sam-api-worker (x1)             │   ├── sam-api-worker (x1)
│   ├── sam-mng-worker (x2)             │   ├── sam-mng-worker (x2)
│   └── sam-api-scheduler               │   └── sam-api-scheduler
├── Node.js (React SSR :3000)           ├── Node.js (React SSR :3000)
├── Jenkins (:8080)                     │
├── Gitea (:3000)                       │
├── /home/webservice/api                ├── /home/webservice/api
├── /home/webservice/mng                ├── /home/webservice/mng
├── /home/webservice/react              ├── /home/webservice/react
└── /home/webservice/sales              └── /home/webservice/sales

도메인 매핑

서비스	로컬 (Docker)	개발 서버	운영 서버
React (사용자)	dev.sam.kr	dev.codebridge-x.com	codebridge-x.com
API	api.sam.kr	api.dev.codebridge-x.com	api.codebridge-x.com
MNG (관리자)	mng.sam.kr	admin.codebridge-x.com	mng.codebridge-x.com
Sales	sales.sam.kr	sales.dev.codebridge-x.com	sales.codebridge-x.com
5130 (레거시)	5130.sam.kr	—	—

명령어 비교 (로컬 vs 개발 vs 운영)

작업	로컬 (Docker)	개발/운영 서버 (네이티브)
artisan 실행	docker exec sam-api-1 php artisan <명령>	cd /home/webservice/api && php artisan <명령>
composer 실행	docker exec sam-api-1 composer install	cd /home/webservice/api && composer install
마이그레이션	docker exec sam-api-1 php artisan migrate	개발: php artisan migrate / 운영: php artisan migrate --force
캐시 클리어	docker exec sam-mng-1 php artisan cache:clear	cd /home/webservice/mng && php artisan cache:clear
Queue 재시작	—	sudo supervisorctl restart sam-api-worker:*

로컬 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 사용
• 서버: php artisan, composer 직접 실행 (Docker 없음)
• 운영 서버 마이그레이션: --force 플래그 필수
• 마이그레이션은 반드시 API에서 실행 (로컬: docker exec sam-api-1, 서버: 직접)

---

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

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

브랜치 전략

브랜치	배포 대상	트리거 워드	Jenkins 배포
feature/*	—	—	—
develop	개발 서버 (dev.codebridge-x.com)	"개발서버 푸시"	Push 시 자동
main	운영 서버 (codebridge-x.com)	"운영서버 푸시"	Push 시 자동

로컬 작업 → develop push → 개발 서버 테스트 → main merge+push → 운영 서버
             ("개발서버 푸시")                    ("운영서버 푸시")

브랜치 동기화 규칙 (필수)

cherry-pick 방식에서는 develop→main 자동 동기화가 불필요하다. main에 직접 변경이 발생한 경우에만 develop에 동기화한다.

상황	조치
"운영서버 푸시" 완료 후	동기화 불필요 (cherry-pick은 develop에 이미 존재하는 커밋)
main에 직접 변경 발생 시 (hotfix 등)	develop에서 git merge main 실행
develop에서 새 작업 시작 전	git pull origin develop으로 최신화 확인

develop ──작업──→ develop push (개발서버)
    │
    └── cherry-pick 선택 커밋 ──→ main push (운영서버)

로컬 환경 (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

개발 서버 업데이트 (자동)

develop 브랜치에 Push 시 Gitea Webhook → Jenkins가 자동으로 배포한다. 수동 배포가 필요한 경우:

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

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

운영 서버 배포 (Jenkins 자동화)

main 브랜치에 PR 머지 시 Jenkins가 자동으로 배포한다. 수동 배포는 비상 절차로만 사용한다.

# 비상 수동 배포 (Jenkins 장애 시에만)
# API 프로젝트
cd /home/webservice/api
git pull origin main
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:clear && php artisan cache:clear && php artisan route:cache && php artisan view:cache
sudo supervisorctl restart sam-api-worker:*

# MNG 프로젝트
cd /home/webservice/mng
git pull origin master
composer install --no-dev --optimize-autoloader
php artisan config:clear && php artisan cache:clear && php artisan view:cache
sudo supervisorctl restart sam-mng-worker:*

요약 표

작업	로컬 (Docker)	개발 서버	운영 서버
배포 방식	수동	Jenkins 자동 (develop push)	Jenkins 자동 (main push)
git pull	WSL에서 직접	Jenkins 자동	Jenkins 자동
composer install	docker exec sam-api-1 composer install	Jenkins 자동	--no-dev --optimize-autoloader
migrate	docker exec sam-api-1 php artisan migrate	Jenkins 자동	--force 플래그 포함
config:clear	docker exec sam-api-1 php artisan config:clear	Jenkins 자동	route:cache + view:cache 포함

체크리스트 (pull 후)

• API: git pull → composer install → php artisan migrate → config:clear
• MNG: git pull → composer install → config:clear (마이그레이션 없음)
• 운영 배포: main에 PR 머지 → Jenkins 자동 처리 (수동 금지)

---

사용 가능한 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	설명
svg-precision	SVG 결정론적 생성, 검증(validate), PNG 렌더링. 다이어그램/차트/아이콘에 사용
duplicate-file-cleaner	중복 이미지/미디어 파일 정리
npm-release-manager	NPM 패키지 배포 자동화

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

---

문서 작성 규칙 (개발팀 협약 - 필수 준수)

경고: 개발자들이 sam/docs의 문서 작성 기법을 준용하기로 협약했습니다. 모든 문서 작성 시 반드시 따르세요!

참조 경로

• 인덱스: /home/aweso/sam/docs/INDEX.md (전체 문서 목록 및 폴더 구조)
• 작업 전 확인: 작업 유형에 맞는 문서를 INDEX.md에서 찾아 먼저 읽고 시작

폴더 선택 기준 (의미 기반 분류)

폴더	질문	설명
plans/	"무슨 작업을 할 것인가?"	임시 개발 계획 (완료 후 삭제)
standards/	"어떻게 코드를 작성할 것인가?"	코딩 컨벤션, 스타일 가이드
architecture/	"왜 이렇게 설계하는가?"	시스템 설계, 아키텍처 결정
rules/	"무엇이 유효한 데이터인가?"	비즈니스 규칙, 검증 규칙
specs/	"무엇을 구현할 것인가?"	기술 스펙, DB 스키마
guides/	"어떻게 구현할 것인가?"	단계별 구현 매뉴얼
features/	기능별 상세	기능 단위 심층 문서
changes/	"무엇이 변경되었는가?"	완료된 변경 이력

파일명 규칙

• 일반 문서: kebab-case.md (소문자 + 하이픈) 예: api-rules.md, item-policy.md
• 변경 이력: YYYYMMDD_short_description.md 예: 20260109_handover_report_api.md
• 폴더 인덱스: README.md (대문자)
• 크기 목표: 10KB 이하
• 새 문서 작성 시: 반드시 docs/INDEX.md에 추가

문서 구조 템플릿

정책/규칙 문서 (rules/, standards/)

# 제목

> **작성일**: YYYY-MM-DD
> **상태**: 설계 확정

---

## 1. 개요
### 1.1 목적
### 1.2 핵심 원칙

---

## 2. 테이블 구조 (해당 시)
### 2.1 ERD 개요

---

## N. 비즈니스 규칙
### N.1 검증 규칙

---

## N. API 엔드포인트

---

## 관련 문서

---

**최종 업데이트**: YYYY-MM-DD

변경 이력 문서 (changes/)

# 변경 내용 요약

**날짜:** YYYY-MM-DD
**작업자:** Claude Code

## 변경 개요

## 수정된 파일
| 파일 | 변경 내용 |
|------|----------|

## 상세 변경 사항

## 테스트 체크리스트
- [x] 완료 항목
- [ ] 미완료 항목

## 관련 문서

작성 스타일 규칙

항목	규칙
언어	한글 기본, 코드/경로/기술 식별자만 영어
어조	서술형 ("X를 해야 한다" 아닌 "X 한다")
경고	> **경고: ...** 블록인용 형식
금지/필수	❌ 금지, ✅ 필수 접두사
우선순위	🔴 필수, 🟡 중요, 🟢 권장
섹션 번호	## 1., ### 1.1 번호 매기기
규칙 번호	R1, R2, R3... 순차 라벨
코드 블록	반드시 언어 지정 (php, bash, json, sql)
인라인 코드	파일 경로, 메서드명, 변수명, 컬럼명에 백틱
다이어그램	┌─┐│└─┘ 박스 문자, → 화살표 사용
구분선	--- 주요 섹션 사이마다
테이블	API: `

plans/ 워크플로우

1. 개발 계획 문서를 plans/에 작성
2. 작업 진행
3. 완료 후 결과물을 해당 폴더(features/, changes/ 등)에 정리
4. plan 문서 삭제

체크리스트 (문서 작성 시)

• 적절한 폴더에 배치 (위 폴더 선택 기준 참고)
• kebab-case.md 파일명 사용
• 문서 구조 템플릿 준수
• 한글 기본, 기술 용어만 영어
• 코드 블록에 언어 지정
• docs/INDEX.md에 새 문서 등록
• 10KB 이하 크기 유지

---

PPT / 프레젠테이션 제작 규칙 (필수 준수)

경고: 모든 프레젠테이션 및 문서 제작 시 반드시 따르세요!

회사 정보

항목	값
공식 회사명	(주)코드브릿지엑스
서비스명	SAM (Smart Automation Management)
푸터 표기 예시	`SAM 서비스 요금 안내

금지 사항

❌ "주일/경동" — 문서, 슬라이드, 푸터 어디에도 사용 금지
❌ "주일", "경동" 단독 사용 금지
❌ 내부 제조사(주일/경동) 이름을 외부 문서에 노출 금지

배경: 주일/경동은 SAM을 기반으로 만든 내부 제조업체 이름이며, 대외 문서에 노출되어서는 안 된다. 모든 대외 문서의 회사명은 (주)코드브릿지엑스를 사용한다.

SAM BI (Brand Identity) 이미지

프로젝트 내 경로: /home/aweso/sam/docs/assets/bi/

파일	용도	배경
sam_bi_black.png	밝은 배경 슬라이드	투명 배경, 검정 로고
sam_bi_white.png	다크 배경 슬라이드	투명 배경, 흰색 로고
sam_bi_blue.png	청색 테마 슬라이드	투명 배경, 파란 로고
sam_bi_green.png	녹색 테마 슬라이드	녹색 배경, 흰색 로고
sam_bi_red.png	적색/대외비 슬라이드	적색 배경, 흰색 로고
sam_bi_orange.png	주황 포인트 슬라이드	주황 배경, 흰색 로고
sam_bi_purple.png	보라 테마 슬라이드	보라 배경, 흰색 로고

PPT 슬라이드 제작 시 적용 규칙

1. 표지(slide-01)에 BI 로고 필수 — 배경색에 맞는 BI 이미지 사용
2. 푸터에 회사명: (주)코드브릿지엑스 (주일/경동 절대 금지)
3. BI 로고 + "SAM" 텍스트 조합 사용 권장
4. 배경색별 BI 선택:
   • 다크 배경 → sam_bi_white.png
   • 밝은 배경 → sam_bi_black.png
   • 테마 컬러 배경 → 해당 색상 BI (green, blue, red 등)

체크리스트 (PPT 제작 시)

• 회사명: (주)코드브릿지엑스 사용
• "주일/경동" 미포함 확인
• 표지에 SAM BI 로고 포함
• 푸터에 (주)코드브릿지엑스 표기
• 배경색에 맞는 BI 색상 선택