From bf8737f0039dc00a27fa7097242c363deab0a95e Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Tue, 23 Dec 2025 18:27:55 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20LLM=20=EC=9A=B0=EC=84=A0=20=EC=A0=91?=
 =?UTF-8?q?=EA=B7=BC=20=EC=9B=90=EC=B9=99=20=EC=B6=94=EA=B0=80=20=EB=B0=8F?=
 =?UTF-8?q?=20LangGraph=20=EC=9B=90=EC=B9=99=20=EB=B3=B4=EC=99=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../311_FastAPI_구조_원칙.md              | 50 ++++++++++++++++---
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md
index 815391a..1b2425d 100644
--- a/book/300_architecture/311_FastAPI_구조_원칙.md
+++ b/book/300_architecture/311_FastAPI_구조_원칙.md
@@ -107,8 +107,13 @@ utils
 
 ### LangGraph 워크플로우
 - **복잡한 다단계 처리**: LangGraph 적극 활용
+  - 의도 분류, 엔티티 추출, 스킬 선택 등 다단계 워크플로우는 LangGraph로 구현
+  - 상태 관리, 조건부 분기, 재시도 로직 등 복잡한 제어 흐름에 적합
 - **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트 구현 (권장)
+  - 장기 실행 워크플로우는 상태 영속성 필수
+  - 중단 시 복구 가능하도록 체크포인트 저장
 - **실험/경량 플로우**: stateless LangGraph 허용
+  - 단순한 워크플로우는 stateless로 시작, 필요 시 체크포인트 추가
 
 ### 계층별 원칙
 - **router**: 서비스 호출만, DB/비즈니스 로직 금지
@@ -180,6 +185,8 @@ utils
 - [ ] 중복 코드는 utils/로 추출할 수 있는가?
 - [ ] DB 스키마 변경 시 ORM/DDL/Repository 동시 수정 확인
 - [ ] LLM 호출 횟수 계산 및 최적화 검토
+- [ ] 애매한 케이스는 LLM 우선 접근 원칙 적용 확인
+- [ ] 복잡한 워크플로우는 LangGraph 활용 검토
 - [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`)
 
 ## 10. 예외 상황
@@ -219,7 +226,38 @@ utils
 - ❌ `docker-compose.yml`의 `environment:` 섹션에 하드코딩된 값
 - ❌ 코드에 API 키, 토큰, 비밀번호 등 민감 정보를 기본값/백업 값으로 직접 하드코딩
 
-## 13. LLM 호출 최적화 원칙
+## 13. LLM 우선 접근 원칙
+
+**핵심 원칙**: 애매한 경우에는 하드코딩된 규칙(heuristic) 대신 LLM을 적극 활용
+
+### LLM 우선 적용 대상
+1. **의도 분류가 애매한 경우** (확신도 < 0.7)
+   - 규칙 기반 패턴 매칭 실패 시 LLM으로 재분류
+   - 짧은 질문("어디서?", "결과는?")은 LLM이 맥락을 해석하여 확장
+2. **맥락 의존 질문** ("그거 어떻게 됐어?", "취소해줘")
+   - LLM이 직전 대화 맥락을 참고하여 선행사 해석 및 질문 확장
+3. **모호한 표현 처리** ("어떻게 생각해?", "괜찮아?")
+   - LLM이 컨텍스트를 이해하여 적절한 응답 생성
+4. **엔티티 추출 및 해석**
+   - 규칙 기반 추출 실패 시 LLM으로 재시도
+   - 대명사, 지시어 해소는 LLM 활용
+
+### 규칙 기반은 보조적으로만 사용
+- **명확한 케이스**: 인사("안녕"), 명령어("/news") 등 패턴이 명확한 경우만 규칙 사용
+- **성능 최적화**: FastPath로 명확한 케이스를 빠르게 처리, 애매한 경우만 LLM 호출
+- **비용 최적화**: 확신도 높은 케이스는 규칙으로 처리, 애매한 경우만 LLM 사용
+
+### 금지 사항
+- ❌ 애매한 케이스를 규칙/패턴 매칭으로 강제 처리
+- ❌ LLM 호출을 피하기 위해 복잡한 규칙 체인 구축
+- ❌ 새로운 패턴마다 규칙 추가하는 방식 (유지보수 부담 증가)
+
+### 장점
+- **유연성**: 새로운 패턴에 대한 규칙 추가 없이 LLM이 자연스럽게 처리
+- **정확도**: 맥락 이해 능력으로 규칙 기반보다 정확한 해석
+- **유지보수**: 규칙 관리 부담 감소, LLM이 자동으로 패턴 학습
+
+## 14. LLM 호출 최적화 원칙
 
 **핵심 원칙**: 호출 횟수 계산 및 최적화 사전 검토 필수
 
@@ -243,7 +281,7 @@ utils
 - 호출 횟수 미검토 시 API 할당량 초과(429 에러) 발생 가능
 - 단일 프롬프트로 통합 가능한 작업은 반드시 통합하여 호출 횟수 최소화
 
-## 14. 장기 작업(LLM/RAG 등) 처리 원칙
+## 15. 장기 작업(LLM/RAG 등) 처리 원칙
 
 **핵심 원칙**: HTTP 요청으로 노출되는 장기 작업(LLM, RAG, 대용량 PDF 처리 등)은 동기식으로 붙잡지 말고, 항상 "즉시 ID 반환 + 비동기 백그라운드 작업 + 후속 조회/웹훅" 패턴으로 설계한다.
 
@@ -266,7 +304,7 @@ utils
 - HTTP(port 80)와 HTTPS(port 443) 블록 모두에 동일한 타임아웃 설정 적용
 - 프록시 타임아웃은 백엔드 작업 시간보다 충분히 길게 설정
 
-## 15. 정적 파일 서빙 원칙
+## 16. 정적 파일 서빙 원칙
 
 ### 필수 원칙
 - **백엔드 금지**: FastAPI 백엔드는 정적 파일(HTML/CSS/JS)을 서빙하지 않음
@@ -279,18 +317,18 @@ utils
 - 프로덕션 환경에서 표준적인 배포 방식
 - 백엔드와 웹서버의 명확한 역할 분리
 
-## 16. Slack API 호출 원칙
+## 17. Slack API 호출 원칙
 
 - **skill-slack API 사용 필수**: rb8001에서 Slack API 호출 시 WebClient 직접 사용 금지, skill-slack HTTP API 사용
 - **thread_ts 처리**: None/빈 문자열일 때는 payload에 포함하지 않음 (조건부 포함 필수)
 - **메시지 업데이트**: 인터랙티브 버튼 응답은 원본 메시지 업데이트(`/api/v1/update`) 사용
 
-## 17. 테스트 원칙
+## 18. 테스트 원칙
 
 - **실제 테스트 필수**: 코드 수정 후 추측하지 말고 실제로 테스트 (curl, Slack 직접 사용, DB 조회)
 - **Git 커밋 확인**: 각 프로젝트 폴더에서 개별 확인 (루트에서 확인 금지)
 
-## 18. 모범 사례 참고
+## 19. 모범 사례 참고
 
 본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다: