From 8f8ef1d0c0dcb7fb5516197cbc6c00262828d3c9 Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Tue, 16 Dec 2025 14:52:35 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EC=A4=91=EB=B3=B5=20=EC=BD=94=EB=93=9C?=
 =?UTF-8?q?=20=EC=A0=9C=EA=B1=B0=20=EC=9B=90=EC=B9=99=20=EB=B0=8F=20utils?=
 =?UTF-8?q?=20=EB=84=A4=EC=9D=B4=EB=B0=8D=20=EA=B7=9C=EC=B9=99=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 book/300_architecture/311_FastAPI_구조_원칙.md  | 13 +++++++++++++
 .../guidelines/naming_conventions.md                |  2 ++
 2 files changed, 15 insertions(+)

diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md
index 66efe25..763e5cc 100644
--- a/book/300_architecture/311_FastAPI_구조_원칙.md
+++ b/book/300_architecture/311_FastAPI_구조_원칙.md
@@ -64,6 +64,11 @@
 - `database.py`: 통합 DB 접근
 - `{도메인}_repository.py`: 도메인별 CRUD 캡슐화
 
+### utils/
+- `{기능}_extractor.py`: 데이터 추출 (json_extractor.py)
+- `{기능}_helper.py`: 도우미 함수
+- 명확하고 구체적인 이름 사용
+
 ### models/
 - `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py)
 
@@ -93,6 +98,13 @@ utils
 
 ## 5. 코드 작성 원칙
 
+### 중복 코드 제거 우선
+- 동일한 로직이 2개 이상의 위치에 반복되면 `utils/`에 유틸리티 함수로 추출
+- 한 곳만 수정하여 전체 반영 가능하도록 설계
+- 범용적이고 재사용 가능한 함수로 구현
+
+**참고**: `DOCS/book/300_architecture/guidelines/utility_functions.md`
+
 ### LangGraph 워크플로우
 - **복잡한 다단계 처리**: LangGraph 적극 활용
 - **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트 구현 (권장)
@@ -165,6 +177,7 @@ utils
 - [ ] 비즈니스 로직이 router에 있지 않은가?
 - [ ] 순환 import 가능성은 없는가?
 - [ ] 핵심 파일은 300줄 이하로 유지할 수 있는가?
+- [ ] 중복 코드는 utils/로 추출할 수 있는가?
 - [ ] DB 스키마 변경 시 ORM/DDL/Repository 동시 수정 확인
 - [ ] LLM 호출 횟수 계산 및 최적화 검토
 - [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`)
diff --git a/book/300_architecture/guidelines/naming_conventions.md b/book/300_architecture/guidelines/naming_conventions.md
index bebc4cb..e516ffc 100644
--- a/book/300_architecture/guidelines/naming_conventions.md
+++ b/book/300_architecture/guidelines/naming_conventions.md
@@ -11,6 +11,7 @@
 - **router**: `{기능}_endpoint.py` (예: `message_endpoint.py`)
 - **service**: `{도메인}_{기능}.py` (예: `coldmail_filter.py`)
 - **state**: `{도메인}_repository.py` (예: `conversation_repository.py`)
+- **utils**: `{기능}_extractor.py`, `{기능}_helper.py` (예: `json_extractor.py`)
 
 **참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md:53-63`
 
@@ -18,6 +19,7 @@
 - `router/`: HTTP 엔드포인트
 - `services/`: 비즈니스 로직
 - `state/`: DB 접근 (Repository 패턴)
+- `utils/`: 공통 유틸리티 함수
 - `models/`: ORM 모델
 - `schemas/`: Pydantic 모델