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 커밋 규칙 (최우선 필수 규칙)

경고: 이 규칙은 절대 누락되어서는 안 됩니다! 기준 문서: 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로 자동 제거됨
• 간결하고 명확한 한글 커밋 메시지만 유지

푸시 정책

• 사용자가 수동으로 푸시 진행
• 자동 푸시 하지 않음
• 커밋 후 푸시 여부를 묻지 않음

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 명령을 실행해야 합니다.

---

서버 접근 정책 (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)
❌ 서버 재부팅

서버 접속 정보

서버	호스트	계정
운영 서버	114.203.209.83	pro

배포 흐름

Claude 역할                         사용자/팀장 역할
┌───────────────────────┐           ┌─────────────────┐
│ 코드 작성/수정         │           │                 │
│ git add / git commit   │           │                 │
│                        │──push──→ │ git push         │
│ 서버 진단 (Level 1)   │           │                 │
│ 서버 변경 (Level 2)   │──확인──→ │ 승인             │
│ 위험 작업 (Level 3)   │──안내──→ │ 직접 실행        │
└───────────────────────┘           └─────────────────┘

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

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

---

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

경고: React(Next.js) 빌드는 반드시 로컬에서 실행합니다. 서버에서 빌드 절대 금지!

배경

서버 스펙(2코어, 3.8GB RAM, Swap 없음)으로는 Next.js 빌드 시 메모리 부족으로 20분 이상 소요되거나 실패한다. 로컬(WSL)에서 빌드 후 결과물만 서버에 배포한다.

금지 사항

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

빌드/배포 방법

Claude 역할                    사용자/팀장 역할
┌─────────────────┐           ┌─────────────────┐
│ 코드 작성/수정   │           │                 │
│ git commit       │──push──→ │ git pull         │
│                  │           │ npm run build    │
│                  │           │ 서비스 재시작    │
└─────────────────┘           └─────────────────┘

빌드가 필요한 상황

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

React 코드가 변경되었습니다. git push 후 서버에서 배포해주세요.

---

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

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

핵심 원칙

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

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

이유

• 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로 개별 레코드만 수정
• 변경 후 부서 권한 설정이 유지되는지 확인

---

실행 환경 (필수 인지)

중요: 로컬과 서버의 환경이 다릅니다!

환경 비교

항목	로컬 (WSL)	서버 (운영)
구성 방식	Docker 컨테이너	네이티브 설치 (Docker 없음)
PHP/Laravel	컨테이너 내부	서버에 직접 설치
MySQL	컨테이너 (sam-mysql-1)	서버에 직접 설치
Nginx	컨테이너 (sam-nginx-1)	서버에 직접 설치
명령 실행	docker exec 필요	직접 실행

배경: 서버는 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 웹서버

서버 환경 (네이티브)

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

운영 서버 (114.203.209.83)
├── Nginx          ← 웹서버 (직접 설치)
├── PHP-FPM        ← PHP 처리 (직접 설치)
├── MySQL          ← DB (직접 설치)
├── /home/webservice/mng  ← MNG 앱
└── /home/webservice/api  ← API 앱

명령어 비교 (로컬 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	cd /home/webservice/api && php artisan migrate
캐시 클리어	docker exec sam-mng-1 php artisan cache:clear	cd /home/webservice/mng && php artisan cache:clear

로컬 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 없음)
• 마이그레이션은 반드시 API에서 실행 (로컬: docker exec sam-api-1, 서버: 직접)

---

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

중요: 코드를 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

서버 환경 업데이트 (네이티브 — Docker 없음)

서버에는 Docker가 없다. PHP, Composer 등이 직접 설치되어 있으므로 명령어를 그대로 실행한다.

# 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	설명
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 색상 선택