From 3847483090f8bdf2c5d05ac50878bd8e3ffb2445 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?=
 <lightone2017@codebridge-x.com>
Date: Sat, 21 Feb 2026 21:15:35 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20=EC=A0=84=EC=97=AD=20?=
 =?UTF-8?q?=EC=84=A4=EC=A0=95=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- PPT 제작 규칙 (회사명, BI 로고, 금지 사항)
- Git 커밋/푸시 정책, 서버 접근 금지 등 전역 규칙
---
 CLAUDE.md | 729 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 729 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ca30f35
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,729 @@
+# 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 (생략가능)
+```
+
+**예시:**
+```bash
+feat: [calendar] 달력 기능 개선
+
+- 클릭시 오류 기능 개선
+- 색상 변경
+```
+
+```bash
+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 명령을 실행해야 합니다.**
+
+---
+
+## 서버 직접 접근 금지 (최우선 필수 규칙)
+
+> **경고: 운영/개발 서버에 SSH로 직접 접속하여 파일을 수정하거나 명령을 실행하지 마세요!**
+> **2026-02-21 사고**: Claude가 서버에 SSH로 직접 접속하여 설정을 변경한 결과 502 Bad Gateway 발생. 개발팀장이 복구함.
+
+### 핵심 원칙
+
+서버는 **개발팀장이 관리**한다. Claude는 서버에 절대 직접 접근하지 않는다.
+
+### 금지 사항
+
+```
+❌ ssh pro@114.203.209.83 ... 로 서버 접속 금지
+❌ ssh hskwon@114.203.209.83 ... 로 서버 접속 금지
+❌ 서버에서 파일 수정, 프로세스 종료/시작, 설정 변경 금지
+❌ 서버에서 npm run build, npm start, node server.js 등 실행 금지
+❌ 서버에서 git pull, composer install, php artisan 등 실행 금지
+❌ scp, rsync로 서버에 파일 직접 전송 금지
+```
+
+### 허용 사항
+
+```
+✅ 로컬에서 코드 작성 및 수정
+✅ 로컬에서 git add → git commit
+✅ 사용자에게 git push 안내 (사용자가 수동으로 실행)
+✅ 사용자에게 서버 배포 절차 안내 (사용자가 수동으로 실행)
+```
+
+### 배포 흐름
+
+```
+Claude 역할                    사용자/팀장 역할
+┌─────────────────┐           ┌─────────────────┐
+│ 코드 작성/수정   │           │                 │
+│ git add          │           │                 │
+│ git commit       │──push──→ │ git pull         │
+│                  │           │ 서버 배포        │
+│                  │           │ 서비스 재시작    │
+└─────────────────┘           └─────────────────┘
+```
+
+### 서버 작업이 필요한 경우
+
+사용자에게 명령어를 안내만 한다:
+
+```
+서버에서 다음 명령을 실행해주세요:
+cd /home/webservice/api && git pull && composer install && php artisan migrate
+```
+
+### 체크리스트 (모든 작업 시)
+
+- [ ] SSH 명령 사용하지 않음
+- [ ] 서버 파일 직접 수정하지 않음
+- [ ] 배포가 필요하면 사용자에게 안내만 제공
+- [ ] git push까지만 Claude 역할
+
+---
+
+## 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 전용 시더만 허용
+```
+
+### 마이그레이션 실행
+
+```bash
+# 마이그레이션은 반드시 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 명령어 패턴
+
+```bash
+# 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) 업데이트
+
+```bash
+# 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
+```
+
+### 서버 환경 업데이트
+
+```bash
+# 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`)
+
+---
+
+## 문서 작성 규칙 (개발팀 협약 - 필수 준수)
+
+> **경고: 개발자들이 `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/`)
+
+```markdown
+# 제목
+
+> **작성일**: YYYY-MM-DD
+> **상태**: 설계 확정
+
+---
+
+## 1. 개요
+### 1.1 목적
+### 1.2 핵심 원칙
+
+---
+
+## 2. 테이블 구조 (해당 시)
+### 2.1 ERD 개요
+
+---
+
+## N. 비즈니스 규칙
+### N.1 검증 규칙
+
+---
+
+## N. API 엔드포인트
+
+---
+
+## 관련 문서
+
+---
+
+**최종 업데이트**: YYYY-MM-DD
+```
+
+#### 변경 이력 문서 (`changes/`)
+
+```markdown
+# 변경 내용 요약
+
+**날짜:** YYYY-MM-DD
+**작업자:** Claude Code
+
+## 변경 개요
+
+## 수정된 파일
+| 파일 | 변경 내용 |
+|------|----------|
+
+## 상세 변경 사항
+
+## 테스트 체크리스트
+- [x] 완료 항목
+- [ ] 미완료 항목
+
+## 관련 문서
+```
+
+### 작성 스타일 규칙
+
+| 항목 | 규칙 |
+|------|------|
+| **언어** | 한글 기본, 코드/경로/기술 식별자만 영어 |
+| **어조** | 서술형 ("X를 해야 한다" 아닌 "X 한다") |
+| **경고** | `> **경고: ...**` 블록인용 형식 |
+| **금지/필수** | `❌` 금지, `✅` 필수 접두사 |
+| **우선순위** | `🔴 필수`, `🟡 중요`, `🟢 권장` |
+| **섹션 번호** | `## 1.`, `### 1.1` 번호 매기기 |
+| **규칙 번호** | R1, R2, R3... 순차 라벨 |
+| **코드 블록** | 반드시 언어 지정 (```php, ```bash, ```json, ```sql) |
+| **인라인 코드** | 파일 경로, 메서드명, 변수명, 컬럼명에 백틱 |
+| **다이어그램** | `┌─┐│└─┘` 박스 문자, `→` 화살표 사용 |
+| **구분선** | `---` 주요 섹션 사이마다 |
+| **테이블** | API: `| Method | Path | 설명 |`, 필드: `| 필드 | 타입 | 설명 |` |
+
+### 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 색상 선택