27 KiB
27 KiB
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설명'이라고 말하면:
- 위 경로의
SAM_PROJECT_OVERVIEW_FOR_AI.md파일을 읽어서 전체 내용을 파악하세요 - SAM 프로젝트의 비즈니스 도메인, 기술 스택, 현재 작업 현황을 이해한 상태로 작업하세요
Git 커밋 규칙 (최우선 필수 규칙)
경고: 이 규칙은 절대 누락되어서는 안 됩니다! 기준 문서:
sam/docs/standards/git-conventions.md
필수 수행 절차
모든 코드 작업 완료 후 반드시 다음을 수행:
- 변경된 파일이 있는 Git 저장소로 이동
git status로 변경사항 확인git add <파일들>로 스테이징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 — 크론 작업 조회
✅ docker ps, docker logs — 컨테이너 상태 조회
🟡 Level 2: 경미한 변경 (확인 후 실행)
실행 전 명령어를 사용자에게 보여주고 승인받은 후 실행:
⚠️ git pull — 코드 업데이트
⚠️ composer install — 의존성 설치
⚠️ php artisan migrate — DB 마이그레이션
⚠️ php artisan config:clear, cache:clear — 캐시 초기화
⚠️ chmod, chown — 파일 권한 변경 (소규모)
⚠️ systemctl restart — 서비스 재시작
⚠️ npm install — 패키지 설치
실행 절차:
- 실행할 명령어를 먼저 사용자에게 표시
- 사용자 승인 확인
- 승인 후 실행
🔴 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
# 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 실행 금지
❌ 메뉴 시더 파일 생성 금지
❌ 메뉴 데이터를 일괄 삭제 후 재생성하는 방식 금지
메뉴 변경 시 올바른 절차
메뉴 추가/수정/삭제/이동이 필요할 때는 사용자에게 수동 실행 안내를 제공합니다:
- tinker 명령어를 안내 (사용자가 직접 실행)
- 또는 SQL 쿼리를 안내 (사용자가 phpMyAdmin 등에서 직접 실행)
- 절대 시더를 만들어 실행하지 않음
안내 예시
메뉴를 추가하려면 아래 명령을 서버에서 실행해 주세요:
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 | 설명 |
|---|---|
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/ 워크플로우
- 개발 계획 문서를
plans/에 작성 - 작업 진행
- 완료 후 결과물을 해당 폴더(
features/,changes/등)에 정리 - 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 슬라이드 제작 시 적용 규칙
- 표지(slide-01)에 BI 로고 필수 — 배경색에 맞는 BI 이미지 사용
- 푸터에 회사명:
(주)코드브릿지엑스(주일/경동 절대 금지) - BI 로고 + "SAM" 텍스트 조합 사용 권장
- 배경색별 BI 선택:
- 다크 배경 →
sam_bi_white.png - 밝은 배경 →
sam_bi_black.png - 테마 컬러 배경 → 해당 색상 BI (green, blue, red 등)
- 다크 배경 →
체크리스트 (PPT 제작 시)
- 회사명: (주)코드브릿지엑스 사용
- "주일/경동" 미포함 확인
- 표지에 SAM BI 로고 포함
- 푸터에 (주)코드브릿지엑스 표기
- 배경색에 맞는 BI 색상 선택