docs: 유틸리티 함수 설계 원칙 가이드라인 추가

book/300_architecture/300_README.md

@@ -25,6 +25,7 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습
 - [네이밍 컨벤션](./guidelines/naming_conventions.md) - 파일명, 변수명, API 경로 규칙
 - [로깅 규칙](./guidelines/logging_rules.md) - 로그 레벨, 포맷, 보관 원칙
 - [상수/설정값 구조](./guidelines/constants.md) - 스킬 레벨, 타입, 감정 분류 구조
+- [유틸리티 함수 설계 원칙](./guidelines/utility_functions.md) - 코드 재사용성, 중복 제거 원칙
 - [배포 패턴](./guidelines/deployment_patterns.md) - 배포 프로세스 패턴
 
 **참고**: 자주 변하는 정보(포트, 엔드포인트, 환경변수 값)는 각 서비스 README.md 참조

book/300_architecture/guidelines/utility_functions.md

@@ -0,0 +1,88 @@
+# 유틸리티 함수 설계 원칙
+
+**작성일**: 2025-12-16  
+**목적**: 코드 재사용성 향상, 중복 제거, 유지보수성 개선
+
+---
+
+## 핵심 원칙
+
+### 1. 중복 코드 제거 우선
+- 동일한 로직이 2개 이상의 위치에 반복되면 유틸리티 함수로 추출
+- 중복 코드는 버그 발생 가능성과 유지보수 비용 증가
+- 유틸리티 함수로 통일하여 한 곳만 수정하면 전체 반영
+
+### 2. 범용성과 재사용성
+- 특정 도메인에 종속되지 않는 범용 함수로 설계
+- 다양한 상황에서 사용 가능하도록 매개변수화
+- 타입 안전성 지원 (타입 힌트, 타입 체크)
+
+### 3. 명확한 책임 분리
+- 하나의 함수는 하나의 명확한 작업만 수행
+- 함수명이 기능을 명확히 표현
+- 복잡한 로직은 여러 함수로 분리
+
+---
+
+## 유틸리티 함수 위치
+
+### 디렉토리 구조
+```
+app/
+└── utils/              # 공통 유틸리티 함수
+    ├── __init__.py
+    └── {domain}_extractor.py  # 예: json_extractor.py
+```
+
+### 네이밍 규칙
+- 파일명: `{기능}_extractor.py`, `{기능}_helper.py` 등
+- 함수명: `extract_{대상}()`, `parse_{대상}()`, `format_{대상}()` 등
+- 명확하고 구체적인 이름 사용
+
+---
+
+## 설계 패턴
+
+### 예시: JSON 추출 유틸리티
+
+**문제**: LLM 응답에서 JSON을 추출하는 로직이 9개 위치에서 중복
+
+**해결**: 범용 JSON 추출 함수 도입
+```python
+# app/utils/json_extractor.py
+def extract_json_from_text(text: str, expected_type: type = dict) -> Optional[Union[Dict, List]]:
+    """다양한 형식의 LLM 응답에서 JSON 추출"""
+    # 코드 블록, 설명 텍스트 등 다양한 형식 자동 처리
+```
+
+**효과**: 
+- 9개 위치의 중복 코드 제거 (90줄 절약)
+- 한 곳만 수정하여 전체 반영 가능
+- 다양한 LLM 응답 형식 자동 처리
+
+---
+
+## 재사용성 체크리스트
+
+유틸리티 함수 생성 전 확인:
+- [ ] 동일한 로직이 2개 이상의 위치에 있는가?
+- [ ] 범용적으로 사용 가능한가? (도메인 종속성 없는가?)
+- [ ] 함수명이 기능을 명확히 표현하는가?
+- [ ] 타입 안전성을 지원하는가?
+- [ ] 에러 처리가 적절한가?
+
+---
+
+## 금지 사항
+
+- ❌ 특정 도메인에 종속된 로직을 유틸리티로 만들지 않음
+- ❌ 너무 복잡한 로직 (책임 분리 필요)
+- ❌ 한 곳에서만 사용되는 로직 (과도한 추상화 방지)
+- ❌ 비즈니스 로직을 유틸리티에 포함 (서비스 레이어에 있어야 함)
+
+---
+
+**참고**: 
+- JSON 추출 유틸리티 사례: `rb8001/app/utils/json_extractor.py`
+- 관련 troubleshooting: `DOCS/journey/troubleshooting/251216_coldmail_processing_improvements.md`
+