docs: 개발 참조 문서 추가 (reference/)

- API 엔드포인트 정리 (api_endpoints.md)
- 인프라 정보 정리 (infrastructure.md)
- 환경변수 정리 (environment_variables.md)
- 배포 파이프라인 정리 (deployment_pipelines.md)
- 상수/설정값 정리 (constants.md)
- 네이밍 컨벤션 정리 (naming_conventions.md)
- 로깅 규칙 정리 (logging_rules.md)

목적: 개발 시 중복/오류 방지, 빠른 참조
모든 문서 100줄 이하 유지, 파일:줄번호 참조 사용

book/300_architecture/300_README.md

@@ -20,6 +20,16 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습
 - 360_로빙_컨테이너_경량화_전략.md
 - 370_임베딩_서비스_분리_아키텍처.md
 
+## 참조 문서 (reference/)
+개발 시 빠른 참조를 위한 정리 문서:
+- [API 엔드포인트](./reference/api_endpoints.md)
+- [인프라](./reference/infrastructure.md)
+- [환경변수](./reference/environment_variables.md)
+- [배포 파이프라인](./reference/deployment_pipelines.md)
+- [상수/설정값](./reference/constants.md)
+- [네이밍 컨벤션](./reference/naming_conventions.md)
+- [로깅 규칙](./reference/logging_rules.md)
+
 ## 핵심 메시지
 컨테이너는 몸, 기억은 영혼. 100개의 로빙이 1개의 스킬 서비스를 공유하는 효율적 아키텍처.
 

book/300_architecture/reference/api_endpoints.md

@@ -0,0 +1,116 @@
+# API 엔드포인트 참조
+
+**작성일**: 2025-12-06
+**목적**: 개발 시 API 엔드포인트 중복/오류 방지, 빠른 참조
+
+---
+
+## rb8001 (메인 서비스, 8001)
+
+### 메시지 처리
+| 엔드포인트 | 메서드 | 설명 | 인증 |
+|-----------|--------|------|------|
+| `/api/message` | POST | Gateway/Frontend 메시지 처리 | JWT 필수 |
+| `/api/feedback/chat` | POST | 채팅 피드백 (좋아요/싫어요) | JWT 필수 |
+
+**참고**: `rb8001/app/router/message_endpoint.py:26`, `rb8001/main.py:85`
+
+### LLM
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/api/llm/generate` | POST | 텍스트 생성 |
+| `/api/llm/summarize` | POST | 요약 |
+| `/api/llm/complete` | POST | 완성 |
+| `/api/llm/health` | GET | 헬스체크 |
+
+**참고**: `rb8001/app/router/llm_endpoint.py:28,55,93,124`
+
+### 감정 분석
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/api/emotion/infer` | POST | 감정 추론 |
+| `/api/emotion/timeseries` | GET | 시계열 데이터 |
+| `/api/emotion/team-insight` | GET | 팀 인사이트 |
+| `/api/emotion/process-message` | POST | 메시지 처리 |
+| `/api/emotion/health` | GET | 헬스체크 |
+
+**참고**: `rb8001/app/router/emotion_endpoint.py:75,150,188,263,303`
+
+### 기억 온톨로지
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/api/v1/memory/event` | POST | 사건 저장 |
+| `/api/v1/memory/recall` | POST | 회상 |
+| `/api/v1/memory/stats` | GET | 통계 |
+
+**참고**: `rb8001/app/router/memory_ontology.py:69,118,181`
+
+### Intent 리뷰
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/api/intent-review/queue` | GET | 큐 조회 |
+| `/api/intent-review/{item_id}/label` | PUT | 라벨 업데이트 |
+| `/api/intent-review/stats` | GET | 통계 |
+
+**참고**: `rb8001/app/router/intent_review_endpoint.py:33,58,81`
+
+### IR Deck 평가
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/api/ir-deck/upload` | POST | PDF 업로드 |
+| `/api/ir-deck/evaluate` | POST | 평가 시작 |
+| `/api/ir-deck/evaluation/{evaluation_id}` | GET | 평가 결과 |
+| `/api/ir-deck/chat` | POST | 채팅 |
+| `/api/ir-deck/feedback` | POST | 피드백 |
+
+**참고**: `rb8001/app/router/ir_deck.py:109,169,263,297,344`
+
+### Slack
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/slack/events` | POST | Slack 이벤트 |
+| `/slack/slash` | POST | 슬래시 명령어 |
+| `/slack/health` | GET | 헬스체크 |
+
+**참고**: `rb8001/app/router/slack_endpoint.py:33,70,117`
+
+---
+
+## skill-* 서비스
+
+| 서비스 | 포트 | 주요 엔드포인트 | 참고 |
+|--------|------|----------------|------|
+| skill-email | 8501 | `/health` | - |
+| skill-news | 8505 | `/health` | `skill_news/README.md:30` |
+| skill-slack | 8502 | `/health` | `skill-slack/README.md:23` |
+| skill-rag-file | 8508 | `/healthz`, `/api/upload`, `/api/search` | `skill-rag-file/app/main.py:60` |
+| skill-calendar | 8512 | `/health`, `/api/events` | `skill-calendar/README.md:23` |
+
+---
+
+## robeing-monitor (9024)
+
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/health` | GET | 헬스체크 |
+| `/api/stats/{robeing_id}` | GET/PUT | 스탯 조회/업데이트 |
+| `/api/monitor/robeings` | GET | 로빙 상태 |
+| `/api/monitor/skills` | GET | 스킬 서비스 상태 |
+
+**참고**: `robeing-monitor/README.md:68`, `robeing-monitor/app/api/monitor.py`
+
+---
+
+## Gateway (8100)
+
+| 엔드포인트 | 메서드 | 설명 |
+|-----------|--------|------|
+| `/gateway/slack/events` | POST | Slack 이벤트 프록시 |
+| `/gateway/*` | * | 각 서비스 프록시 |
+
+**참고**: `AGENTS.md:88-92`
+
+---
+
+**업데이트**: 서비스 추가/변경 시 즉시 반영
+

book/300_architecture/reference/constants.md

@@ -0,0 +1,100 @@
+# 상수/설정값 참조
+
+**작성일**: 2025-12-06
+**목적**: 코드 중복 방지, 일관성 유지
+
+---
+
+## 스킬 레벨
+
+| 레벨 | 스킬 | 설명 |
+|------|------|------|
+| 1 | 기본 대화 | 기본 채팅 |
+| 2 | 이메일 읽기 | Gmail 읽기 |
+| 3 | Slack 대화 | Slack 연동 |
+| 4 | 이메일 전송 | Gmail 전송 |
+| 5 | 데일리 브리핑 | 뉴스 요약 |
+| 7 | 일정 관리 | 캘린더 |
+| 11 | 문서 작성/편집 | 문서 작업 |
+| 13 | 데이터 분석/차트 | 분석 |
+| 17 | 프로젝트 관리 | 프로젝트 |
+| 19 | AI 인사이트/예측 | 인사이트 |
+| 23 | 자동화 워크플로우 | 자동화 |
+
+**참고**: `DOCS/journey/troubleshooting/250830_skill_level_system_restructure.md:45-57`
+
+---
+
+## 스킬 타입
+
+| 타입 | 설명 | 사용 위치 |
+|------|------|-----------|
+| `EMAIL` | 이메일 스킬 | `rb8001/app/services/brain/decision_engine.py:76` |
+| `NEWS` | 뉴스 스킬 | 동일 |
+| `SLACK` | Slack 스킬 | 동일 |
+| `LLM` | LLM 처리 | 동일 |
+| `CALENDAR` | 캘린더 스킬 | 동일 |
+| `TOOL` | 도구 스킬 | 동일 |
+
+**참고**: `rb8001/app/services/brain/decision_engine.py:76-108`
+
+---
+
+## 감정 분류
+
+| 감정 | 설명 |
+|------|------|
+| `fear` | 두려움 |
+| `surprise` | 놀람 |
+| `anger` | 분노 |
+| `sadness` | 슬픔 |
+| `neutral` | 중립 |
+| `happiness` | 행복 |
+| `disgust` | 혐오 |
+
+**참고**: `rb8001/app/services/emotion_classifier.py`
+
+---
+
+## 스탯 요구사항
+
+| 스킬 | Memory | React | Compute | Empathy |
+|------|--------|-------|---------|---------|
+| EMAIL | 10 | 5 | 5 | 5 |
+| NEWS | - | 10 | 5 | - |
+| SLACK | 15 | - | - | 10 |
+| ANALYSIS | 15 | - | 20 | - |
+| LLM | - | - | 15 | 10 |
+
+**참고**: `rb8001/app/services/brain/decision_engine.py:560-565`
+
+---
+
+## HTTP 상태 코드
+
+| 코드 | 의미 | 사용 예시 |
+|------|------|-----------|
+| 200 | 성공 | 정상 응답 |
+| 401 | 인증 실패 | JWT 만료 |
+| 403 | 권한 없음 | 레벨 부족 |
+| 404 | 없음 | 리소스 없음 |
+| 500 | 서버 오류 | 내부 에러 |
+
+---
+
+## 로그 레벨
+
+| 레벨 | 설명 | 사용 시점 |
+|------|------|-----------|
+| `DEBUG` | 디버그 정보 | 개발 중 |
+| `INFO` | 일반 정보 | 정상 동작 |
+| `WARNING` | 경고 | 예상 가능한 문제 |
+| `ERROR` | 오류 | 처리 실패 |
+| `CRITICAL` | 치명적 오류 | 시스템 중단 |
+
+**참고**: `rb8001/app/core/logger.py`
+
+---
+
+**업데이트**: 상수 추가/변경 시 즉시 반영
+

book/300_architecture/reference/deployment_pipelines.md

@@ -0,0 +1,99 @@
+# 배포 파이프라인 참조
+
+**작성일**: 2025-12-06
+**목적**: 배포 프로세스 빠른 참조
+
+---
+
+## 자동 배포 (Gitea Actions)
+
+### 배포 대상 서비스
+- rb8001
+- robeing-monitor
+- skill_email
+- skill_news
+- skill-rag-file
+- skill-publish
+- skill-slack
+- fluent-bit
+- frontend-customer
+- frontend-ir-valuation
+
+**참고**: `AGENTS.md:28-29`
+
+### 배포 플로우
+1. 로컬에서 코드 수정
+2. `git push origin main`
+3. Gitea Actions 자동 실행 (51123 서버)
+4. SSH로 51124 서버 접속
+5. `git pull origin main`
+6. `docker compose down && docker compose up -d --build`
+7. 헬스체크 확인
+
+**참고**: `AGENTS.md:83-85`
+
+### 워크플로우 파일 위치
+- 경로: `.gitea/workflows/*.yml`
+- 예시: `rb8001/.gitea/workflows/cicd.yml`
+
+---
+
+## 수동 배포
+
+### 배포 대상 서비스
+- skill-embedding
+- skill-calendar
+
+**참고**: `AGENTS.md:29`
+
+### 배포 절차
+```bash
+cd /home/admin/ivada_project/[서비스명]
+git pull origin main
+docker compose down && docker compose up -d --build
+docker ps  # 재시작 확인
+```
+
+---
+
+## 배포 검증
+
+### 필수 확인 사항
+- [ ] `docker ps`로 컨테이너 실행 확인
+- [ ] 헬스체크 엔드포인트 응답 확인
+- [ ] 로그 확인 (`docker logs [컨테이너명] --tail 50`)
+
+**주의**: Actions 성공 메시지만 믿지 말고 실제 컨테이너 상태 확인
+
+**참고**: `AGENTS.md:30-31`
+
+---
+
+## SSH Secrets
+
+| Secret 이름 | 설명 | 사용 위치 |
+|------------|------|-----------|
+| `SSH_PRIVATE_KEY_51124` | 51124 서버 SSH 키 | Gitea Actions |
+| `SSH_HOST_51124` | 192.168.219.52 | Gitea Actions |
+| `SSH_USER_51124` | admin | Gitea Actions |
+
+**참고**: `DOCS/journey/plans/251206_skill_calendar_자동배포_구성.md`
+
+---
+
+## 트러블슈팅
+
+### Actions 캐시 문제
+- 증상: 워크플로우 수정이 반영되지 않음
+- 해결: `/root/.cache/act/` 삭제
+- 참고: `DOCS/journey/troubleshooting/250929_actions_cache_problem.md`
+
+### SSH 인증 실패
+- 증상: "Permission denied (publickey)"
+- 해결: Gitea Secrets의 SSH 키 확인
+- 참고: `DOCS/journey/troubleshooting/250728_happybell80_nginx프록시및CI배포문제해결.md`
+
+---
+
+**업데이트**: 배포 프로세스 변경 시 즉시 반영
+

book/300_architecture/reference/environment_variables.md

@@ -0,0 +1,92 @@
+# 환경변수 참조
+
+**작성일**: 2025-12-06
+**목적**: 환경변수 중복/오류 방지, 빠른 참조
+
+---
+
+## 공통 환경변수
+
+| 변수명 | 필수 | 설명 | 예시 |
+|--------|------|------|------|
+| `SERVICE_NAME` | 예 | 서비스 이름 | `skill-slack` |
+| `PORT` | 예 | 서비스 포트 | `8502` |
+| `LOG_LEVEL` | 선택 | 로그 레벨 | `INFO` |
+| `DATABASE_URL` | 예* | PostgreSQL 연결 문자열 | `postgresql://...` |
+| `JWT_SECRET_KEY` | 예* | JWT 시크릿 키 | - |
+
+*일부 서비스만 필수
+
+---
+
+## rb8001
+
+| 변수명 | 필수 | 설명 | 참고 |
+|--------|------|------|------|
+| `DATABASE_URL` | 예 | PostgreSQL 연결 | `rb8001/docker-compose.yml` |
+| `JWT_SECRET_KEY` | 예 | JWT 인증 | `rb8001/app/auth.py` |
+| `NEO4J_PASSWORD` | 선택 | Neo4j 비밀번호 | `rb8001/docker-compose.yml` |
+| `TAVILY_API_KEY` | 선택 | Tavily API 키 | `rb8001/docker-compose.yml` |
+| `USE_EMOTION_ANALYSIS` | 선택 | 감정 분석 활성화 | `true/false` |
+| `GEMINI_API_KEY` | 선택 | Gemini API 키 | - |
+
+---
+
+## skill-* 서비스
+
+### skill-slack
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `SERVICE_API_KEY` | 예 | 서비스 인증 키 |
+| `SLACK_BOT_TOKEN` | 예 | Slack 봇 토큰 |
+| `JWT_SECRET_KEY` | 예 | JWT 검증 |
+
+**참고**: `skill-slack/app/core/config.py`, `skill-slack/docker-compose.yml`
+
+### skill-rag-file
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `DATABASE_URL` | 예 | PostgreSQL 연결 |
+| `CHROMA_PORT` | 선택 | ChromaDB 포트 (기본: 8000) |
+
+**참고**: `skill-rag-file/docker-compose.yml:11`
+
+### skill-calendar
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `DATABASE_URL` | 예 | PostgreSQL 연결 (51123) |
+
+**참고**: `skill-calendar/docker-compose.yml:14`
+
+### skill-news
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `GEMINI_API_KEY` | 예 | Gemini API 키 |
+| `DATABASE_URL` | 예 | PostgreSQL 연결 |
+
+**참고**: `skill_news/README.md:36-39`
+
+---
+
+## robeing-monitor
+
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `DATABASE_URL` | 예 | PostgreSQL 연결 |
+| `ROBEING_URLS` | 예 | 로빙 서비스 URL 목록 |
+| `SKILL_URLS` | 예 | 스킬 서비스 URL 목록 |
+
+**참고**: `robeing-monitor/README.md:37-42`
+
+---
+
+## 주의사항
+
+- **민감 정보 하드코딩 금지**: API 키, 토큰, 비밀번호는 `.env` 파일에만 저장
+- **기본값 사용 금지**: 환경변수 미설정 시 명시적 에러 처리
+- **참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md` 섹션 12
+
+---
+
+**업데이트**: 환경변수 추가/변경 시 즉시 반영
+

book/300_architecture/reference/infrastructure.md

@@ -0,0 +1,96 @@
+# 인프라 참조
+
+**작성일**: 2025-12-06
+**목적**: 서버/포트/네트워크 정보 빠른 참조
+
+---
+
+## 서버 구성
+
+| 서버 | IP | 역할 | 주요 서비스 |
+|------|-----|------|------------|
+| 51123 | 192.168.219.45 | 메인 서버 | nginx, Gitea, auth-server, robeing-gateway, frontend-base, PostgreSQL |
+| 51124 | 192.168.219.52 | 로빙/스킬 서버 | rb8001, robeing-monitor, skill-*, ChromaDB |
+
+**참고**: `AGENTS.md:78-81`, `DOCS/book/300_architecture/310_전체_시스템_구조_컨테이너와_마이크로서비스.md:27-30`
+
+---
+
+## 포트 매핑
+
+### 51123 서버
+| 서비스 | 포트 | 프로토콜 | 설명 |
+|--------|------|----------|------|
+| nginx | 80, 443 | HTTP/HTTPS | 웹 서버 |
+| Gitea | 3000 | HTTP | Git 저장소 |
+| robeing-gateway | 8100 | HTTP | API 게이트웨이 |
+| frontend-base | 8000 | HTTP | 관리자 대시보드 |
+| auth-server | 9000 | HTTP | 인증 서버 |
+| PostgreSQL | 5432 | TCP | 데이터베이스 |
+| Neo4j | 7687 | TCP | 그래프 DB |
+
+### 51124 서버
+| 서비스 | 포트 | 프로토콜 | 설명 |
+|--------|------|----------|------|
+| rb8001 | 8001 | HTTP | 메인 로빙 서비스 |
+| robeing-monitor | 9024 | HTTP | 모니터링 서비스 |
+| skill-email | 8501 | HTTP | 이메일 스킬 |
+| skill-news | 8505 | HTTP | 뉴스 스킬 |
+| skill-slack | 8502 | HTTP | Slack 스킬 |
+| skill-rag-file | 8508 | HTTP | RAG 파일 스킬 |
+| skill-calendar | 8512 | HTTP | 캘린더 스킬 |
+| skill-embedding | 8511 | HTTP | 임베딩 스킬 |
+| skill-publish | - | HTTP | 퍼블리싱 스킬 |
+| ChromaDB | 8000 | HTTP | 벡터 DB |
+
+**참고**: `AGENTS.md:78-81`, 각 서비스 `docker-compose.yml`
+
+---
+
+## 네트워크 플로우
+
+### 배포 플로우
+```
+로컬 개발 → Gitea 푸시 → Actions (51123) → SSH (51124) → git pull → docker 재시작
+```
+
+**참고**: `AGENTS.md:83-85`
+
+### Admin Dashboard 라우팅
+```
+사용자 → nginx (51123) → robeing-gateway (8100) → frontend-base (8000)
+```
+
+**참고**: `AGENTS.md:88-92`
+
+### API 프록시
+```
+Frontend → nginx (/gateway/) → Gateway (8100) → 각 서비스
+```
+
+---
+
+## SSH 접속
+
+| 서버 | SSH 포트 | 사용자 | 용도 |
+|------|----------|--------|------|
+| 51124 | 51124 | admin | 배포 (Gitea Actions) |
+
+**참고**: `AGENTS.md:28-29`, Gitea Actions 워크플로우
+
+---
+
+## 데이터베이스
+
+| DB | 서버 | 포트 | 데이터베이스명 | 사용자 |
+|----|------|------|---------------|--------|
+| PostgreSQL | 51123 | 5432 | main_db | robeings |
+| Neo4j | 51123 | 7687 | - | neo4j |
+| ChromaDB | 51124 | 8000 | - | - |
+
+**참고**: `DOCS/book/300_architecture/database/tables.md`
+
+---
+
+**업데이트**: 서버/포트 변경 시 즉시 반영
+

book/300_architecture/reference/logging_rules.md

@@ -0,0 +1,105 @@
+# 로깅 규칙 참조
+
+**작성일**: 2025-12-06
+**목적**: 로그 일관성 유지, 디버깅 효율성 향상
+
+---
+
+## 로그 레벨 사용 규칙
+
+| 레벨 | 사용 시점 | 예시 |
+|------|-----------|------|
+| `DEBUG` | 상세 디버깅 정보 | 변수 값, 함수 진입/종료 |
+| `INFO` | 정상 동작 정보 | 요청 처리, 상태 변경 |
+| `WARNING` | 예상 가능한 문제 | 재시도, 폴백 처리 |
+| `ERROR` | 처리 실패 | 예외 발생, API 오류 |
+| `CRITICAL` | 시스템 중단 | DB 연결 실패, 서비스 다운 |
+
+**참고**: `rb8001/app/core/logger.py`
+
+---
+
+## 로그 포맷
+
+### 구조화된 로그
+```python
+logger.info(f"User {user_id} authenticated", extra={
+    "user_id": user_id,
+    "action": "authenticate"
+})
+```
+
+### JSON 로깅
+- 형식: JSON (python-json-logger 사용)
+- 필드: `time`, `level`, `module`, `msg`
+
+**참고**: `rb8001/app/core/logger.py`
+
+---
+
+## 로그 위치
+
+### 컨테이너 내부
+- 경로: `/code/logs/[서비스명].log`
+- 예시: `/code/logs/rb8001.log`
+
+### 호스트 (백업)
+- 경로: `/mnt/51123logs/[서비스명]/`
+- 백업 시간: 매일 03:00
+
+**참고**: `AGENTS.md:133-137`
+
+---
+
+## 로그 확인 방법
+
+### 실시간 로그
+```bash
+docker logs [컨테이너명] --tail 100
+```
+
+### 파일 로그
+```bash
+tail -f /code/logs/[서비스명].log
+```
+
+### 에러 필터링
+```bash
+docker logs [컨테이너명] | grep -iE "error|warn|fail"
+```
+
+**참고**: `AGENTS.md:133-137`
+
+---
+
+## 로그 보관
+
+### Docker JSON 로그
+- 위치: `/var/lib/docker/containers/*/json.log`
+- 권한: sudo 필요
+
+### OpenSearch
+- 주소: http://192.168.219.45:9200
+- 인덱스: `dataprepper-static` (서비스 로그)
+- 일별 인덱스: `dataprepper-YYYY.MM.DD` (fluent-bit 로그)
+
+**참고**: `AGENTS.md:137-142`
+
+---
+
+## 로깅 모범 사례
+
+### DO
+- 요청/응답 로깅 (INFO)
+- 에러 상세 정보 포함 (ERROR)
+- 사용자 ID 포함 (개인정보 제외)
+
+### DON'T
+- 민감 정보 로깅 (비밀번호, 토큰)
+- 과도한 DEBUG 로그 (프로덕션)
+- 중복 로그 (같은 정보 반복)
+
+---
+
+**업데이트**: 로깅 규칙 변경 시 즉시 반영
+

book/300_architecture/reference/naming_conventions.md

@@ -0,0 +1,94 @@
+# 네이밍 컨벤션 참조
+
+**작성일**: 2025-12-06
+**목적**: 코드 일관성 유지, 가독성 향상
+
+---
+
+## 파일명
+
+### Python
+- **router**: `{기능}_endpoint.py` (예: `message_endpoint.py`)
+- **service**: `{도메인}_{기능}.py` (예: `coldmail_filter.py`)
+- **state**: `{도메인}_repository.py` (예: `conversation_repository.py`)
+
+**참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md:53-63`
+
+### 디렉토리
+- `router/`: HTTP 엔드포인트
+- `services/`: 비즈니스 로직
+- `state/`: DB 접근 (Repository 패턴)
+- `models/`: ORM 모델
+- `schemas/`: Pydantic 모델
+
+**참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md:27-51`
+
+---
+
+## 변수명
+
+### Python
+- **snake_case**: 변수, 함수, 모듈
+- **PascalCase**: 클래스
+- **UPPER_CASE**: 상수
+
+**예시**:
+```python
+user_id = "uuid"  # 변수
+def get_user_info():  # 함수
+    pass
+class UserService:  # 클래스
+    pass
+MAX_RETRIES = 3  # 상수
+```
+
+---
+
+## API 엔드포인트
+
+### 경로 규칙
+- **kebab-case**: URL 경로 (예: `/api/intent-review/queue`)
+- **RESTful**: 리소스 중심 (예: `/api/events/{event_id}`)
+
+**참고**: `rb8001/app/router/intent_review_endpoint.py:33`
+
+---
+
+## 데이터베이스
+
+### 테이블명
+- **snake_case**: 소문자, 언더스코어 (예: `conversation_log`)
+- **복수형**: 컬렉션 의미 (예: `users`, `conversations`)
+
+### 컬럼명
+- **snake_case**: 소문자, 언더스코어 (예: `user_id`, `created_at`)
+- **UUID**: `id` 또는 `{entity}_id` (예: `user_id`)
+
+**참고**: `DOCS/book/300_architecture/database/tables.md`
+
+---
+
+## 환경변수
+
+### 명명 규칙
+- **UPPER_SNAKE_CASE**: 대문자, 언더스코어
+- **명확한 의미**: `DATABASE_URL`, `JWT_SECRET_KEY`
+
+**참고**: `DOCS/book/300_architecture/reference/environment_variables.md`
+
+---
+
+## 서비스명
+
+### 컨테이너명
+- **kebab-case**: 소문자, 하이픈 (예: `skill-slack`, `robeing-monitor`)
+
+### 서비스 ID
+- **소문자**: `rb8001`, `skill-email`
+
+**참고**: `AGENTS.md:78-81`
+
+---
+
+**업데이트**: 컨벤션 변경 시 즉시 반영
+